Access Management 7.2.2

Dynamic OAuth 2.0 authorization

You can configure AM to grant scopes statically or dynamically:

  • Statically (Default). You configure several OAuth 2.0 clients with different subsets of scopes and resource owners are redirected to a specific client depending on the scopes required. As long as the resource owner can authenticate and the client can deliver the same or a subset of the requested scopes, AM issues the token with the scopes requested. Therefore, two different users requesting scopes A and B to the same client will always receive scopes A and B.

  • Dynamically. You configure an OAuth 2.0 client with a comprehensive list of scopes and resource owners authenticate against it. When AM receives a request for scopes, AM’s Authorization Service grants or denies access scopes dynamically by evaluating authorization policies at runtime. Therefore, two different users requesting scopes A and B to the same client can receive different scopes based on policy conditions.

Example use case

Consider the case of a company deployment that supports custom OAuth 2.0 clients and internal applications. The use of the internal application is bound by the terms and conditions specified by the company; therefore, the user does not need to consent to provide with their user profile information (for example, the profile scope).

To provide the internal application with the user profile automatically, the administrator creates a policy that grants the profile scope to all requests made by authenticated users using a particular OAuth 2.0 client.

How does dynamic OAuth 2.0 authorization work?
Shows the relationship between realms, policies, and policy sets when granting or denying OAuth 2.0 scopes.
Figure 1. Granting or Denying OAuth2 2.0 Scopes Dynamically

When issuing access tokens, AM deduces consent status based on a policy result: an allow policy result means consent is granted, while a deny result means it is denied.

If AM cannot deduce consent using a policy, for example, because none is defined, it is down to the resource owner to decide whether to grant consent. Note that this is only possible in flows where the resource owner interacts with the consent screen. If the resource owner cannot interact with the consent screen, for example, during the ROPC Grant flow, AM denies the scope.

Just like when granting scopes statically, AM only evaluates default scopes configured in the OAuth 2.0 client profile when no scope is requested. AM follows the same rules to deduce consent for both default and requested scopes.

When issuing refresh tokens, AM issues any scope that was previously consented to either by policy or by the resource owner on the consent screen, unless it is explicitly denied by a policy.

To understand which flows are interactive and which ones are not, see the examples in OAuth 2.0 grant flows and OpenID Connect grant flows.

OAuth 2.0 authorization is implemented by using the OAuth2 Scope resource type. Configure policies for your OAuth 2.0 service in a custom policy set with the OAuth2 Scope resource type, or use the default oauth2Scopes policy set.

Related information: Policies.

Writing policies for OAuth 2.0 may not be straightforward if your environment requires complex conditions. The easiest way to test if your OAuth 2.0 policies are granting or denying the scopes you expect before setting them in production is to configure AM as an OAuth 2.0 client and authorization provider and request some tokens.

Configure Access Management for the examples

  1. Configure an instance of the OAuth 2.0 provider.

    See Authorization server configuration.

    Ensure that:

    • Use Policy Engine for Scope Decisions is enabled.

    • Response Type Plugins is configured for token and id_token.

    • Grant Types is configured for Resource Owner Password Credentials and Implicit.

  2. Go to Realms > Realm Name > Applications > OAuth 2.0 and add a client.

    Configure the client properties as follows:

    • Client ID: myClient

    • Client secret: forgerock

    • Redirection URIs: https://www.example.com:443/callback

    • Scope(s): profile email openid

    • Grant Types: Resource Owner Password Credentials

  3. Go to Realms > Realm Name > Authorization > Policy Sets, and select Default OAuth2 Scopes Policy Set.

  4. Create a new policy as follows:

    • Name: myOAuth2Policy

    • Resource Type: OAuth2 Scope

    • Resources: Select the * resource pattern and replace it with email.

      Once the policy is created, you will see the Summary tab.

  5. On the Actions tab, add the GRANT action, and set the default state to Allow. Save your changes.

  6. On the Subjects tab, specify the subject condition All of…​ Authenticated Users. Save your changes.

  7. If the demo user is not present in your environment, create it by performing the following step:

    • Go to Realms > Realm Name > Identities, and add a new user called demo with password Ch4ng31t.

Test OAuth 2.0 policies in a non-interactive flow

This procedure shows how to test OAuth 2.0 policies with the ROPC Grant flow. In this flow, the resource owner does not interact with the consent screen and cannot therefore grant scopes.

  1. Request an access token from AM by specifying:

    • The client name, myClient, and its password, forgerock.

    • The resource owner password credentials grant type, password.

    • The user and password to authenticate with, demo and Ch4ng31t.

    • The requested scopes, email and profile.

    $ curl \
--request POST \
--data "grant_type=password" \
--data "username=demo" \
--data "password=Ch4ng31t" \
--data "scope=profile email" \
--data "client_id=myClient" \
--data "client_secret=forgerock" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"

  2. Review the JSON response.

    It should be similar to the following:

    {
  "access_token":"B78LPVHaycIrObh12Qps0n9ynYM",
  "scope":"email",
  "token_type":"Bearer",
  "expires_in":3599
}

    Note how the requested scopes were email and profile, but the scope granted was email, which matches the GRANT=Allow action defined in the policy.

Test OAuth 2.0 policies in an interactive OpenID Connect flow

This procedure shows how to test OAuth 2.0 policies with the OpenID Connect Implicit Grant flow. In this flow, the end user can interact with the consent screen, and can therefore grant scopes.

  1. In a web browser, make a call to the oauth2/authorize endpoint with the following parameters:

    • nonce=123

    • state=456

    • scope=openid+email+profile

    • response_type=id_token

    • client_id=myClient

    • redirect_uri=https://www.example.com:443/callback

    For example: https://openam.example.com:8443/openam/oauth2/authorize?nonce=123&state=456&scope=openid+email+profile&response_type=id_token&client_id=myClient&redirect_uri=https://www.example.com:443/callback. You will be prompted to log in to AM.

  2. Log in as the demo user.

    You will be prompted to provide consent for the profile scope:

    AM requests the user to consent to sharing the profile scope
    Figure 2. Requesting Consent for the Profile Scope

    Notice that you are not prompted to provide consent for the email scope.

  3. Allow the flow to continue.

  4. Review the URL of the browser.

    It should show something similar to: http://example.com/#scope=openid%20profile%20email&id_token=eyJ0eXJKV1Q…​8WK1eg&state=456.

    Notice that the email scope has been granted automatically.

    If the authorization policy had been configured as GRANT=Deny, you still would have not seen the email scope in the consent page, but the scope would not appear in the URL of the browser.