OAuth Scopes
This feature is only available in an Essentials or Enterprise plan. Please visit our pricing page to learn more.
Overview
Available since 1.50.0
Scope management in FusionAuth allows an administrator to define OAuth scopes and the messaging used on the OAuth consent screen when these scopes are requested.
Scopes in FusionAuth are associated with an application. While there is no limit to the number of scopes an application can have, each must have a unique name.
By providing the scope parameter on an OAuth request, you can limit the scope of access for the resulting access token. Providing a scope value that matches the level of access the token needs for the current workflow enhances security by limiting what can be done with the token if it is intercepted or stolen.
For applications that do not have the same owner as the authorization server, called third-party applications in FusionAuth, OAuth scopes and the themeable consent prompt allow users the chance to limit the information shared with the third-party or decline access to their information entirely.
This page provides more detail around managing custom OAuth scopes. The OAuth Scopes page has more information on configuring how the application handles scopes, including the consent prompt.
Managing Scopes
This is the Manage Scopes homepage for a given application. From here you can see a list of all the configured OAuth scopes as well as perform the following actions:
| Create a new OAuth scope | |
| Edit a previously created OAuth scope | |
| View a previously created OAuth scope | |
| Remove a previously created OAuth scope |
Create and Edit a Scope
Creating and editing scopes for an application is straight forward.
Here is what you can expect when creating a new scope:
Once created, a scope is implicitly enabled and can be requested by the application during an OAuth workflow.
Here is what you can expect when updating an existing scope:
Form Fields
NamerequiredThe name of the OAuth scope. This is the value that will be used to request the scope in OAuth workflows.
Once a scope has been created the name cannot be updated. In this situation, you will need to create a new scope and delete the old one.
DescriptionA description of the OAuth scope for internal use.
Consent messageThe default message to display on the OAuth consent screen if one cannot be found in the theme. Learn more about setting this value using themes.
Consent detailsThe default detail to display on the OAuth consent screen if one cannot be found in the theme. Learn more about setting this value using themes.
RequiredDetermines if the OAuth scope is required when requested in an OAuth workflow.
View a Scope
Additional details about a particular OAuth scope can be viewed by clicking the action:
Remove a Scope
When a scope is no longer needed, it can be removed by clicking the action:
Deleting a scope can impact the OAuth workflows for an application in different ways depending on the Unknown scope policy configured for that application. It will also affect resource servers or APIs which may be expecting a scope to be presented in a token.
