OAuth Scopes

Overview

Available since 1.50.0

OAuth scopes provide you with another dimension for applying access controls to applications. Scopes are requested by OAuth clients (applications) during authorization and optionally consented to by the user providing the authorization. The consented scopes make their way into the access token granted to the client and can be checked when the client uses the access token to access protected resources.

In FusionAuth, applications can be designated as first-party or third-party. First-party applications are often synonymous with the authorization server from the user’s perspective and don’t require consent for requested scopes. Third-party applications, by contrast, require consent by an authorizing user for the scopes they request.

This page details these features and explains how you can use them to customize FusionAuth’s behavior.

Application Configuration

The Scopes tab allows you to configure the application’s OAuth scope handling policies.

Form Fields

Relationship

The application’s relationship to the authorization server, otherwise known as the OAuth server.

The possible values are:

First-party - The application has the same owner as the authorization server. Consent to requested OAuth scopes is granted implicitly. This was the default behavior for all versions of FusionAuth before version 1.50.0.
Third-party - The application is external to the authorization server. Users will be prompted to consent to requested OAuth scopes based on Consent mode .

Note: An Essentials or Enterprise plan is required to utilize third-party applications.

Consent mode

Controls the policy for prompting a user to consent to requested OAuth scopes. This field is only visible when the application’s Relationship is Third-party.

The possible values are:

Always prompt - Always prompt the user for consent.
Remember decision - Remember previous consents; only prompt if the choice expires or if the requested or required scopes have changed. The duration of this persisted choice is controlled by the tenant’s Remember OAuth scope consent choice configuration.
Never prompt - The user will be never be prompted to consent to requested OAuth scopes. Permission will be granted implicitly as if this were a First-party application. This configuration is meant for testing purposes only and should not be used in production.

Unknown scope policy

Controls the policy for handling unknown scopes on an OAuth request.

The possible values are:

Allow - Unknown scopes will be allowed on the request, passed through the OAuth workflow, and written to the resulting tokens without consent. This is the behavior for all versions of FusionAuth before version 1.50.0.
Remove - Unknown scopes will be removed from the OAuth workflow, but the workflow will proceed without them.
Reject - Unknown scopes will be rejected and cause the OAuth workflow to fail with an error. This is the default behavior for new applications.

Scope handling policy

Controls the policy for handling of OAuth scopes when populating JWTs and the UserInfo response.

The possible values are:

Compatibility - OAuth workflows will populate JWT and UserInfo claims in a manner compatible with versions of FusionAuth before version 1.50.0.
Strict - OAuth workflows will populate token and UserInfo claims according to the OpenID Connect 1.0 specification based on requested and consented scopes.

Provided scopes

Configuration for standard scopes provided by FusionAuth. Each provided scope is reserved by FusionAuth and can be individually Enabled and Required. A disabled scope will be treated as unknown by FusionAuth and handled in accordance with the Unknown scope policy. A user must consent to all Required scopes present in an OAuth workflow, but may choose whether or not to consent to Enabled fields that are not Required.

Scope Handling Policy

The application’s Scope handling policy controls behavior when populating access tokens, Id tokens, and the UserInfo response.

The Compatibility option is meant to maintain backwards compatibility with versions of FusionAuth before 1.50.0 or when the integration does not support the requirements of Strict mode. The Strict option follows specification recommendations by populating access tokens, Id tokens, and the UserInfo response based on the requested and consented scopes. It also restricts the tokens the UserInfo endpoint will accept. New applications default to the Strict policy.

The JWT populate and UserInfo populate lambdas can be used to override the claims in both configurations.

The following table describes the differences between the two options in more detail.

	Compatibility	Strict
Access token claims	The token contains the `email`, `email_verified`, and `preferred_username` claims for the user when that information is available.	The token contains no identifying information about the user other than the `sub` claim, which contains their unique user Id.
Id token claims	The token contains the `email`, `email_verified`, and `preferred_username` claims for the user when that information is available.	The claims on the token are based on the `scope` parameter from the OAuth workflow. See below for details on the claims included for each scope.
UserInfo request	The endpoint will accept either an access token or Id token on the request. No particular `scope` claim is required on the token.	The endpoint only accepts access tokens on the request. The provided token must contain `openid` in the space-delimited `scope` claim in order to be accepted.
UserInfo response	The response starts with claims from the provided token, removes some that are not relevant to the UserInfo response, and then augments the response based on information available for that user.	The claims on the response are based on the `scope` claim of the provided token. See below for details on the claims included for each scope.

The Strict policy uses the requested and consented OAuth scopes to determine which claims to add to the Id token and UserInfo response. The address, email, profile, and phone scopes are provided by FusionAuth and are used to populate claims according to available user data and Section 5.4 of the OpenID Connect specification.

address - FusionAuth does not include physical addresses in its user data model. A lambda could be used to populate the address claim based on custom user data.
email - populates the email and email_verified claims
phone - Populates the phone_number claim based on the user’s mobilePhone value. FusionAuth does not verify phone numbers, so the phone_number_verified claim is not included.
profile - Populates various profile-related data. The following describes how each claim maps to FusionAuth user data.

Claim	User field
`given_name`	`firstName`
`middle_name`	`middleName`
`family_name`	`lastName`
`name`	`fullName`
`preferred_username`	`username`
`birthdate`	`birthDate`
`picture`	`imageUrl`
`locale`	The first value of `preferredLanguages`
`zoneinfo`	`timezone`

Provided Scopes

FusionAuth provides the following scopes defined by the OpenID Connect specification.

address
email
phone
profile

These scope names cannot be used to define custom scopes. Each of the scopes can be individually Enabled or Required. Provided scopes that have been disabled are considered unknown and will be handled according to the application’s Unknown scope policy .

The user must grant consent to all Required provided scopes during the OAuth consent prompt in order to successfully complete the OAuth workflow.

Reserved Scopes

FusionAuth reserves the openid and offline_access scopes. These scope names cannot be used to define custom scopes, and their configuration cannot be changed.

The openid scope is used to request identity information according to the OpenID Connect specification.

The offline_access scope is used to request a refresh token on the authorization response. Its behavior is controlled by the Generate refresh tokens and Enabled grants configurations on the application OAuth tab.

Reserved Prefixes

FusionAuth reserves the prefixes idp-link:, source-entity:, and target-entity:. Scope names starting with these prefixes cannot be used when defining custom scopes.

This feature is only available in an Essentials or Enterprise plan. Please visit our pricing page to learn more.

An application whose Relationship has been configured as Third-party (which requires a paid plan) has the option to prompt users to consent to the requested OAuth scopes in order to complete the OAuth workflow. The consent prompt is a mechanism for users to limit the information shared with third-party applications. For example, a third-party application may require the email scope in order to access the user’s email address and create their account but optionally request the phone scope in order to send notifications via SMS. Applications can also define custom scopes to be requested by third-parties for more fine-grained access control to APIs or limiting ability to perform certain actions on behalf of the user.

The Consent mode controls when users will be prompted to grant consent to the requested scopes.

Always prompt - Always prompt the user for consent.
Remember decision - Remember previous consents; only prompt if the choice expires or if the requested or required scopes have changed. The duration of this persisted choice is controlled by the tenant’s Remember OAuth scope consent choice configuration.
Never prompt - The user will be never be prompted to consent to requested OAuth scopes. Permission will be granted implicitly as if this were a First-party application. This configuration is meant for testing purposes only and should not be used in production.

The Remember decision option requires some additional context. The duration that a user’s decision is persisted can be controlled on the tenant’s Advanced tab using the Remember scope consent choice configuration. After a user has made a consent decision for an application configured with the Remember decision option, the user will only be prompted again when any of the following is true:

Their persisted choice has expired based on the tenant’s configured duration.
A scope is requested that is not included in their persisted choices.
A previously declined optional scope is requested, but it is now required.

If a user has an existing persisted consent choice and is prompted for consent, their decision on the requested scopes will be merged with their existing persisted choices. Only scopes on the current request will be updated in the persisted choice. Scopes that exist in the user’s persisted choice that were not on the request that triggered the prompt will not have their choice updated.

For example:

An application has defined custom scopes a, b, and c as optional
A user has previously made consent decisions on these three scopes, and their choice to consent to a but decline b and c has been persisted
Later, scopes b and c are updated to be required and a new optional scope d is defined
The user completes another OAuth workflow with scopes c and d on the request, which triggers a consent prompt because:
1. c was previously declined but is now required
2. The user has not made a decision on scope d
The user chooses to consent to c and decline d
The persisted choice is updated to move c from declined scopes to approved scopes, and d is added to the list of declined scopes
a is still persisted as an approved scope
b is still listed as a declined scope even though it is now required because the user did not make a new decision for b
If b is included in a future OAuth request, the user would be prompted for consent

Users are prompted for consent using the OAuth consent prompt themed page.

The page informs the user of the requested OAuth scopes. Required scopes are listed first with a checkmark icon and cannot be de-selected. Optional scopes use a checkbox form element to allow the user to decline consent to the corresponding scope.

Clicking the Allow button will complete the OAuth workflow and grant consent to the selected scopes. The consented scopes will be added to the scope claim on the resulting tokens. Clicking the Cancel button will terminate the OAuth workflow and send the user to the redirect_uri with an OAuth error.

The OAuth2 consent template can be customized like any other themed page and also features an expanded message lookup policy in order to allow customizing scope consent messages and details without requiring a separate theme for each verbiage change.

OAuth scope consent messages and details follow an ordered theme message lookup policy from most-to least-specific. The theme will render the first option that contains a value using the OAuth2 consent template’s resolveScopeMessaging function. For an example data:read scope attached to an Application with the Id a2afb0f5-eb2d-4d8f-a55d-05e978e95fda, below the options for overriding the message are listed from most to least preferred.

Any : or = characters in the scope name need to be escaped in the theme messages definition.

# Most preferred: Override at the application level using the application Id
[{application}a2afb0f5-eb2d-4d8f-a55d-05e978e95fda]{scope-message}data\:read=Application-specific consent message
[{application}a2afb0f5-eb2d-4d8f-a55d-05e978e95fda]{scope-detail}data\:read=Application-specific consent detail

# Override at the tenant level using the tenant Id
[{tenant}e122574f-6ec5-4399-b6b2-04ede9796380]{scope-message}data\:read=Tenant-specific consent message
[{tenant}e122574f-6ec5-4399-b6b2-04ede9796380]{scope-detail}data\:read=Tenant-specific consent detail

# Least preferred: Override at the theme level
{scope-message}data\:read=Themed consent message
{scope-detail}data\:read=Themed consent detail

If a themed message cannot be found using the given application, tenant, or theme, the scope.defaultConsentMessage and scope.defaultConsentDetail values will be used. If scope.defaultConsentMessage is empty, the scope.name will be used as the message. If scope.defaultConsentDetail is empty, no detail value will be displayed.

Results

Recent

OAuth Scopes

Overview

Application Configuration

Form Fields

Scope Handling Policy

Provided Scopes

Reserved Scopes

Reserved Prefixes

Results

Recent

Results

Recent

OAuth Scopes

Overview

Application Configuration

Form Fields

Scope Handling Policy

Provided Scopes

Reserved Scopes

Reserved Prefixes

Consent Mode

Consent Prompt

Consent Messages Lookup

Results

Recent