Attribute Scopes

An attribute scope is an OAuth scope, such as profile or email, that decides which user or tenant attributes a client receives. Each attribute scope maps to a set of claims. When a client requests the scope and it's granted, Descope adds those claims to the tokens it issues and to the /userinfo response.

Attribute scopes are defined once for the project and used by Inbound Apps and Federated OIDC Apps. Each app can use the project's definition of a scope as is, or define its own version of it. To add claims to every token regardless of which scopes a client requests, use JWT templates instead.

Attribute Scopes and Permission Scopes

Attribute scopes and the permission scopes on a Resource answer different questions:

• Permission scopes decide what a client can do, such as contacts.read on your API. They live on a Resource and map to roles.
• Attribute scopes decide what a client can know about the user, such as their name and email. They map to claims and don't grant access to anything.

A client often requests both kinds in one authorization request, for example openid profile contacts.read.

Viewing Attribute Scopes

Attribute scopes live in the Descope Console under Resources, on the Attribute Scopes tab. Each scope shows its description, how many claims it maps, and the claim names. Scopes marked Auto-add to new apps are added to every new app automatically (see Adding Scopes to New Applications).

Every project starts with two default scopes:

Other scopes a client might expect, such as offline_access, aren't created by default. Create them yourself, as described in Creating an Attribute Scope.

Creating an Attribute Scope

Click + Scope to create a scope, or click an existing scope to edit it. Each scope has:

• Scope name: The scope string clients request, such as profile.
• Description: Optional text that explains what the scope shares.
• Add to new applications: Whether new apps get this scope automatically.
• Claims: The claims the scope adds.

Each row under Claims defines one claim:

• Key: The claim name as it appears in the token, such as given_name.
• Type: Dynamic to read the value from the user or tenant at token time, or Static for a fixed value.
• Value: For a dynamic claim, the attribute to read, such as user.name or user.givenName. For a static claim, the literal value.
• Token Placement: Which tokens the claim is written to. See Token Placement for the options.

Click + Add row to add a claim. To define all of the claims as a JSON object instead, click Advanced mode.

Dynamic Values

A dynamic claim reads its value from the user, the user's tenant, or the app when Descope builds the token. Descope omits the claim when the value is empty. These are the values you can read:

When a mapped claim has the same name as a claim that a standard scope adds, such as email from the email scope, the standard claim wins.

Roles, Permissions, and Custom Claims

The descope.claims and descope.custom_claims scopes add Descope-specific claims to the token. An attribute scope can replace the first and part of the second, under a scope name you choose.

• Roles and permissions: A claim with the key authz adds the same roles, permissions, and tenants payload that descope.claims adds. Descope ignores the claim's value. You can also add specific values, such as user.tenant.roles, from the table above.
• User custom attributes: A dynamic claim can read user.customAttributes.<name>, so a scope can return a custom attribute without descope.custom_claims.
• Claims a flow adds at sign-in: Attribute scopes can't read these. A flow's Custom Claims action adds them to the session, and only the descope.custom_claims scope returns them.

Place the claim in User Info to return it from the /userinfo endpoint, which both Inbound Apps and Federated OIDC Apps use.

Token Placement

By default, each claim is written to All Tokens. To limit where a claim appears, remove All Tokens and pick one or more of:

• Access Token: The token the client sends to your APIs.
• ID Token: The token that tells the client who signed in.
• User Info: The response from the /userinfo endpoint.

For example, you might put email in the ID token and User Info but leave it out of the access token, so it isn't sent to every API the client calls.

A dynamic claim can also carry authorization context that a client needs before it calls your APIs. Some identity brokers, such as Cloudflare Access, read only the ID token. To give them the user's tenants, you can add a dynamic claim with the value user.tenantNames (or user.tenantIds) and place it in the ID Token.

Adding Scopes to New Applications

When Add to new applications is on, every Inbound App and Federated OIDC App created from then on includes the scope, using the project's definition. The toggle only affects apps created after you turn it on:

• Turning it on doesn't add the scope to apps that already exist.
• Turning it off doesn't remove the scope from apps that already have it.

After an app is created, it owns its scope list. You can add or remove the scope on that app at any time.

Using Attribute Scopes in an App

Inbound Apps and Federated OIDC Apps each have an Attribute scopes section that lists the scopes the app's clients can request. You can add scopes to it in two ways:

• Add project-level scope: Adds a scope defined on the Attribute Scopes tab. The app uses the project's claims and token placement for it, so a change to the project-level scope applies to every app that uses it.
• Create app-level scope: Defines a scope that only this app uses, with its own claims and token placement. Use this when one client should get different information for a scope. For example, an app-level profile scope could return only given_name to one app, while other apps keep the project-level profile.

Click Manage attribute scopes to go to the Attribute Scopes tab.

Managing Attribute Scopes with the API

You can manage the project-level scopes with the Management API: get, set, or delete the scope claim mapping. Each entry has a scope, its claims, optional claimTargets for token placement, and addToNewApplications.

On an app, the same entries are listed in scopeClaimMapping. An entry with useProjectMapping set to true uses the project-level scope. With useProjectMapping set to false, the entry is an app-level scope and uses its own claims and claimTargets.