FAQ
ForgeRock Identity Platform
ForgeRock Identity Cloud

FAQ: OAuth 2.0 in Identity Cloud and AM

Last updated Apr 4, 2022

The purpose of this FAQ is to provide answers to commonly asked questions regarding OAuth 2.0 and OpenID Connect 1.0 (OIDC) in ForgeRock Identity Cloud and AM.


1 reader recommends this article

Frequently asked questions

Q. What information is included in an OAuth 2.0 access token created by Identity Cloud or AM?

A. The following data is included:

  • EXPIRY_TIME - the time the token expires.
  • SCOPE - the scope of the token.
  • USER_NAME - the Identity Cloud or AM user who created the token.
  • REDIRECT_URI - the redirect URI used to create the token.
  • REFRESH_TOKEN - the ID of the refresh token for this access token.
  • REALM - the realm in which this access token was created.
  • ID - the ID of this access token.
  • CLIENT_ID - the client_id used to create the access token.
  • NONCE - the nonce value passed in as a parameter when requesting the access token.

Q. How can I check that an OAuth access token is valid?

A. You should use the /oauth2/introspect endpoint. This endpoint is defined by RFC 7662. See /oauth2/introspect for further information.

Q. Why is the OAuth access token still valid after the Identity Cloud or AM session has ended?

A. OAuth 2.0 does not check whether the assertion has been consumed or not; it only checks if it is valid. This means that even when an underlying Identity Cloud or AM session has ended (for example, there has been an IdP initiated single logout, the access token is still valid. The access token can be reused until the validity of the assertion has expired.

Note

AM provides an OAuth 2.0 Post-Authentication Plugin as part of the standard product delivery. You can configure this plugin so that the OAuth 2.0 authentication module logs the resource owner out with the OAuth 2.0 provider when logging out of AM. See Implementing Post-Authentication Plugins for further details and caveats.

Q. Can I limit the number of OAuth 2.0 access tokens that can be issued per user?

A. No, you cannot do this within Identity Cloud or AM; the user can generate unlimited access tokens. You can constrain the use of tokens by applying a policy at token validation time; this is more in line with our continuous security approach.

Q. Why don't all special characters in client IDs and secrets need URL encoding?

A. The URL encoding of client IDs and secrets when using HTTP Basic Authorization is specified in the OAuth 2.0 standard: RFC 6749 (Section-2.3.1) and the standard linked to Appendix B on URL encoding (RFC 3629). As per these standards, some special characters need encoding whereas others do not:

  • Special characters that have specific meanings in an encoded URL (such as % and +) must be encoded.
  • Special characters that do not have any meaning within an encoded URL and are part of the standard character set (such as @ and $) do not need encoding.

Client IDs and secrets must be URL encoded (UTF-8) in Identity Cloud; AM 6.5 and later. Encoding a character that doesn't strictly need encoding will work, whereas not encoding a character that should be encoded will cause authentication to fail as seen in URLDecoder: Illegal hex characters in escape (%) pattern or Client authentication failed error when requesting an OAuth2 access token in Identity Cloud or AM (All versions).

Resolved RFE: OPENAM-13609 (Allow for URL encoded client id and secret in basic auth secured oauth endpoints)

Q. What parameters can I use with the oauth2/authorize and oauth2/access_token endpoints?

A. These endpoints are defined by the RFC 6749 standard. The oauth2/authorize endpoint can take realm, module and service parameters; the oauth2/access_token endpoint can take realm and auth_chain parameters.

If you want to specify a realm in the URL, you must use the realm parameter. For example, if the OAuth 2.0 provider is configured for the /employees realm, then use /oauth2/authorize?realm=/employees and /oauth2/access_token?realm=/employees.

See OAuth 2.0 Endpoints for further information.

Q. Can I retrieve SSO session properties as claims via the OIDC /userinfo endpoint?

A. No, this is not possible because the AccessToken sent in the UserInfo request does not provide a link to the SSO session. However, it is possible to include SSO session details in the JWT ID token as described in the following articles:

Q. Is it ok to expose these OAuth 2.0 endpoints publicly?

A. The following OAuth2 endpoints have to be exposed in order for the OAuth functionality to work correctly:

  • /openam/oauth2/authorize
  • /openam/oauth2/tokeninfo
  • /openam/oauth2/access_token

Both the /authorize and /access_token endpoints require authentication; the /tokeninfo endpoint is open to everyone without authenticating to allow any user or application to validate a token. These endpoints are publicly documented in: OAuth 2.0 Guide.

You should also consult RFC 6749, which discusses security considerations around OAuth 2.0 endpoints.

Q. What is the relationship between the Saved Consent Attribute Name and scopes?

A. The scope attribute in the authorization request lists the scopes that specify what type of access has been granted by the user. When a user is presented with a consent page and selects Save consent, an entry will be added in the user profile containing the requested scope. See How does OAuth 2.0 Saved Consent work in AM? for further information.

Q. Is it possible to bypass the Authorization Consent page?

A. You can bypass the OAuth 2.0 Authorization Consent page in Identity Cloud or AM when you are using the Authorization Code Grant flow as detailed in Allowing Clients To Skip Consent.

Q. Is it possible to bypass consent during Dynamic Client Registration?

A. No, you cannot set the Implied Consent option to true during Dynamic Client Registration as this is against the OAuth 2.0 standard (RFC 6749).

See OPENAM-12831 (OAuth2 and OpenIDConnect allow implied consent to be defined in dynamic registration) for further information and possible alternative solutions.

Q. What scopes can I request with the default Scope validator in Identity Cloud or AM?

A. You can use any user attributes as a scope. Additionally, the following attributes do not have hard-coded mappings:

  • email
  • address
  • phone

Q. How does the OAuth 2.0 authentication node or module create a session?

A. The OAuth 2.0 authentication node or module links an OAuth 2.0 access token (whether from Identity Cloud, AM or any OAuth 2.0 provider) to a local user; it uses the access token to receive information about the user (such as their email address), links it to a local user and returns a session. Although the Identity Cloud or AM session timeout and the OAuth 2.0 token timeout are independent of each other, you can refresh or renew an expired Identity Cloud or AM session without providing credentials again if the refresh token is still valid.

For example, if your OAuth 2.0 provider is Google™, and your Identity Cloud or AM session expires, you can send another authorization request to Google; Google will then refresh your Identity Cloud or AM session (without requiring your credentials) providing the refresh token is still valid. If the refresh token is not valid, you will need to re-authenticate to continue.

Note

OAuth 2.0 is an authorization protocol and using it as described above to create a session is using it as an authentication protocol. We imply authentication whilst the access token (being a bearer token) could be presented or replayed by anyone. Implying authentication through OAuth 2.0 is standard practice though and is therefore offered by Identity Cloud or AM. You should use the Social Provider Handler Node (Identity Cloud; AM 7.1 and later), OpenID Connect node (pre-AM 7) or OpenID Connect authentication module (AM), which is designed for Authentication, instead of the OAuth 2.0 node or OAuth 2.0 authentication module for authentication purposes.

See the following for further information:

Q. Can I modify the sub value to return a different user attribute in the id_token (AM only)?

A. The sub (Subject Identifier) value maps to the stored Principal username of the underlying authentication module, that is, the LDAP Users Search Attribute. In AM 6 and later, you can override the sub claim by editing the OIDC Claims Script to manipulate the attributes returned in the id_token:

  1. Select the OIDC Claims Script by navigating to: Realms > [Realm Name] > Scripts > OIDC Claims Script.
  2. Add the following new computedClaims.put line immediately before the final line in the script, for example: ... computedClaims.put("sub", identity.getAttribute("mail")[0]) return new UserInfoClaims((Map)computedClaims, (Map)compositeScopes)where this new line overrides the sub value by mapping it to the mail attribute in the user's profile. You can map to other profile attributes in the same way.

When tested for the demo user, this amendment adjusts the sub value in the id_token from "demo" (the principal from the underlying authentication module, that is, the LDAP Users Search Attribute) to the user's email address. For example, the sub value in the generated id_token now looks like this:

{  "at_hash": "m1ccfceGINU3d_TxJ9WiXQ",   "sub": "demo@example.com", ...

The above assumes the option to Always return claims in ID Tokens in the OAuth 2.0 Global service has been enabled. See Advanced OpenID Connect for further details.

Resolved RFE: OPENAM-7878 (Add functionality to modify the sub at the module level to override the clientID setting)

See Also

OAuth 2.0 and OIDC in AM

Social Authentication

Social Authentication Module Properties - OAuth 2.0

Social Authentication Module Properties - OpenID Connect 1.0

OAuth 2.0 Guide

OAuth 2.0 Key Rotation in AM 6.5


Copyright and Trademarks Copyright © 2022 ForgeRock, all rights reserved.