--- title: Authorization server configuration description: Configure the OAuth2 Provider service in a realm to expose the OAuth 2.0 endpoints and OAuth 2.0 administration REST endpoints. component: pingam version: 8.1 page_id: pingam:am-oauth2:oauth2-configure-authz canonical_url: https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-configure-authz.html keywords: ["OAuth 2.0", "Endpoints", "Authorization", "Clients", "Grant Flow", "Setup & Configuration"] page_aliases: ["oauth2-guide:oauth2-configure-authz.adoc"] section_ids: oauth2-configuration-options: Additional configuration change-user-profile-attr-oauth2: Change the attribute used to find the user profile --- # Authorization server configuration Configure the OAuth2 Provider service in a realm to expose the [OAuth 2.0 endpoints](oauth2-client-endpoints.html) and [OAuth 2.0 administration REST endpoints](oauth2-admin-endpoints.html). 1. In the AM admin UI, go to Realms > *realm name* > Services, and click Add a Service. 2. From the drop-down list, select the OAuth2 Provider service, leave the remaining fields empty, and click Create. 3. On the OAuth 2.0 provider page, select the Advanced tab. 4. Configure the Grant Types that clients will be able to use to request access, refresh, and ID tokens. > **Collapse: Grant types reference** > > ```none > Implicit > SAML2 > Refresh Token > Resource Owner Password Credentials > Client Credentials > Device Code > Authorization Code > Back Channel Request > UMA > JWT Bearer > Token Exchange > ``` > > Related information: > > * [OAuth 2.0 grant flows](oauth2-implementing-flows.html) > > * [OpenID Connect grant flows](../am-oidc1/oidc-implementing-flows.html) > > * [UMA grant flow](../uma/uma-grant-flow.html) > > * [Token exchange](token-exchange.html) 5. Configure the Response Type Plugins you need in your environment, based on the grant type flows you'll allow. Response plugins let the provider issue access tokens, ID tokens, authorization codes, and others, when the client requests a flow that interacts with the `/oauth2/authorize` endpoint. > **Collapse: Response type plugin reference** > > ```none > code|org.forgerock.oauth2.core.AuthorizationCodeResponseTypeHandler > id_token|org.forgerock.openidconnect.IdTokenResponseTypeHandler > device_code|org.forgerock.oauth2.core.TokenResponseTypeHandler > token|org.forgerock.oauth2.core.TokenResponseTypeHandler > none|org.forgerock.oauth2.core.NoneResponseTypeHandler > ``` > > * The `id_token` and `none` response types are used in OpenID Connect flows. > > * The `code` response type is used in the OAuth 2.0 and OpenID Connect Authorization Code grant flows. > > * The `device_code` response type was used for the Device grant flow, but it is not required in the current implementation and will be removed in a future release of AM. > > * The `token` response type is used in the OAuth 2.0 and OpenID Connect Implicit flows. 6. Configure Persistent Claims *Persistence* lets you retain custom claims when you refresh an access token. In the Persistent Claims field, enter the claims that must be persisted between tokens. When an access token is refreshed, any claims that are listed here will be on the new token. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * These claims are added before the access token modification script, allowing you to manipulate them in the modification script. For example, if a token has a claim called `hostname` that must be persisted when the token is refreshed, you could add that claim to the Persistent Claims list. You could then modify the script to persist that `hostname` in the new token, if it exists, or to add a hostname to the new token, if it does not exist. * Only custom, non-standard claims can be persisted. Standard claims such as `scope` (defined in the OAuth2 specification) and `auditTrackingId` (defined by default in AM) cannot be persisted. | 7. For other configuration options, refer to [Additional configuration](#oauth2-configuration-options). ## Additional configuration The OAuth 2.0 provider is highly configurable: * To configure the OAuth 2.0 provider in the AM admin UI, go to Realms > *realm name* > Services, and select OAuth2 Provider. * To adjust global OAuth 2.0 provider defaults, go to Configure > Global Services, and click OAuth2 Provider. Find detailed information on the provider configuration in the [OAuth2 Provider](../setup/services-configuration.html#global-oauth-oidc) reference section. **OAuth 2.0 Provider Configuration Options** | Task | Resources | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | **Configure the authorization server to issue refresh tokens**Learn why refresh tokens are useful in your environment, how to configure AM to issue them, and how to request them. | [Refresh tokens](oauth2-refresh-tokens.html) | | **Adjust the lifetimes of tokens and codes**If necessary, adjust the lifetimes for authorization codes (a lifetime of 10 minutes or less is [recommended in RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1.2)), access tokens, and refresh tokens.Configure them on the Core tab of the provider. | N/A | | **Configure OAuth 2.0 server behavior**AM provides plugin points that let you extend default OAuth 2.0 server behavior. Use these extension points to customize:- The content of OAuth 2.0 access tokens - The validation of requested scopes - The resource owner information retrieved based on an issued access token - Scope values that are returned for an access token - Data that is returned from an authorization request | [Customize OAuth 2.0](customizing-oauth2-scopes.html) | | **Configure the OAuth 2.0 provider for token exchange**Following the [OAuth 2.0 Token Exchange](https://www.rfc-editor.org/info/rfc8693) specification, the provider can let your clients exchange tokens. | [Token exchange](token-exchange.html) | | **Configure the OAuth 2.0 service to provide scopes dynamically**The OAuth 2.0 provider can leverage the AM Authorization service to grant or deny scopes dynamically. | [Dynamic OAuth 2.0 authorization](../am-authorization/oauth2-authorization.html) | | **Configure a custom response plugin**To configure a custom response type plugin, add it to the AM classpath, and add the custom response types and the plugin class names to the list of Response Type Plugins field, on the Advanced tab. | N/A | | **Decide how scopes appear in the consent pages**To change how scopes appear, configure the Client Registration Scope Allowlist field on the Advanced tab of the OAuth 2.0 provider.Define each scope as a string that represents the internal scope name, optionally followed by a `\|locale` and a `\|localized description`.For example: `read\|en\|Permission to view email messages in your account`. | [OAuth 2.0 scopes](oauth2-scopes.html) | | **Decide how to manage consent**You can:- Allow users to save consent so the OAuth 2.0 provider remembers their consented scopes. - Allow clients to skip consent so no consent page is displayed to the resource owners. - Allow clients to revoke consent. | [Manage consent](oauth2-manage-consent.html) | | **Configure a remote consent server**This is useful, for example, when your environment must hand off the consent-gathering part of the OAuth 2.0 flows to a separate service. | [Remote consent](oauth2-remote-consent.html) | | **Configure the attribute AM uses to retrieve the user profile**This is useful, for example, in cases where the resource owner should log in with their email address instead of with a username. | [Change the attribute used to find the user profile](#change-user-profile-attr-oauth2) | | **Configure client-side tokens**Configure client-side tokens so that resource servers can directly introspect the tokens without making a call to AM. | [Configure AM for client-side OAuth 2.0 tokens](stateless-oauth2.html) | | **Configure OpenID-Connect specific options**UMA providers also use these options. | [OpenID provider configuration](../am-oidc1/configure-openid-connect-provider.html) | ## Change the attribute used to find the user profile If you use an external identity store, and users log in with an attribute other than their user ID (such as an email address), you must configure AM authentication to allow this. For example, to let resource owners log in using an email address, stored in the LDAP `mail` attribute, follow these steps: 1. On the OAuth2 provider Advanced tab, add the LDAP profile attribute to the User Profile Attribute(s) the Resource Owner is Authenticated On list, and save your changes. 2. Go to Realms > *realm name* > Identity Stores > *identity store name* > Authentication Configuration. 3. Set the value of the Authentication Naming Attribute field to the LDAP attribute required. For example, `mail`. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you change the value of Authentication Naming Attribute after you have deployed and configured AM, you must update or recreate all existing identities to refresh user DNs.Failure to do so could result in unsuccessful authentication or risk of impersonation attacks. | 4. Add an LDAP decision node to your authentication tree and configure the following fields: * In the Attribute Used to Retrieve User Profile field, set the attribute to `mail`. * In the Attributes Used to Search for a User to be Authenticated list, add the `mail` attribute. * Save your changes. 5. Ensure resource owners use the authentication tree you configured. Specify the authentication tree by using one or more of the methods below. AM checks for the configured value in the following order, using the first value found: 1. For a specific access token REST request. Set the `auth_chain` parameter. 2. Individually for a realm, overriding the realm-level setting below. Go to Realms > *realm name* > Services > OAuth2 Provider > Advanced, and set the `Password Grant Authentication Service` property. 3. Individually for a realm. Go to Realms > *realm name* > Authentication > Settings > Core, and set the `Organization Authentication Configuration` property. 4. Globally, for all realms. Go to Configure > Authentication > Core Attributes > Core, and set the `Organization Authentication Configuration` property. Find more information in [Configure sensible default authentication services](../security/securing-realms.html#configure-default-auth). For more information, refer to [Configure authentication](../am-authentication/authn-implementation-authn.html).