Purpose

This document is intended for use by application developers who are integrating with the Identity Cloud and OpenID Connect (OIDC) to retrieve user information. This document covers the following topics:

• Objective
• Integration tasks
• UX elements
• OpenID Connect
• Login sequence
• Mobile considerations
• Application session
• Authorization checks
• Logout

Objective

Applications need to integrate with the Identity Cloud to securely access profile information for users employing that application. With the provided user information, applications can do such things as personalize the user experience within the application or grant access to protected resources.

Integration tasks

• Build UX elements that trigger an authentication request to the Identity Cloud.
• Implement OpenID Connect in order to receive identities from the Identity Cloud.
• Perform additional authorization checks required by your application.
• Update the application session with the user information and determine when users must re-authenticate.
• Logout and revoke issued tokens.

Each of these integration tasks is explained in more detail in the following sections of this document.

UX elements

Eventually, end users of your application will reach a point in the user experience where they must log in in order to access protected features of the application. 

Applications can trigger the need to log in based on what the user is trying to do. Alternatively, the user can be presented with an option to log in: if the user accepts this option they can then personalize their experience or access protected features.

Applications have full control over how they render the user actions that result in a login request.  Regardless of how this rendering takes place, the key point is this: when the specified actions are taken (for example, when the user visits a protected resource or clicks a login button), this should trigger the application’s OpenID Connect implementation.

OpenID Connect

When an identity is needed, the application must generate a request to the Identity Cloud using OpenID Connect.

Applications should leverage certified OIDC Relying Party libraries whenever possible to ensure both conformance with the OIDC standard and interoperability. The OpenID Connect Basic Client Implementer’s Guide is a valuable resource for any application using the authorization code flow.

Applications must manage three configuration items:

1. The OpenID Connect Discovery Document.
2. Client details:
   • For confidential clients, this will include a client ID and secret.
   • For public clients, this will include only a client ID. Public clients do not have a client secret.
3. Redirect URI. After a successful login at the OpenID provider, the user is redirected back to the URL configured as the app’s redirect_uri and registered as part of the client configuration.  Be sure to share the redirect URI with your Identity Cloud system administrator.
    

Login sequence

From an OpenID Connect standpoint, the following sequence of calls and actions must be performed:

1. Make an authentication request by calling the /authorize endpoint: the end user will be redirected to the OpenID Provider and must complete authentication before they are sent back to the app.
2. The user will be granted an authorization code and redirected back to the app’s redirect_uri.
3. The app must then make a request to the /token endpoint to exchange the authorization code for a set of tokens (ID token, access token, refresh token).
4. Upon receiving the  ID token, that token must be validated according to Section 2.2.1 of the Basic Client Implementer’s Guide. The Identity Cloud public key needed to verify the token signature is found in the JSON Web Key (JWK) UR referenced in the Discovery document.
5. Depending on the scopes and claims included in your authentication request, the application will get back information from the user profile at the same time the tokens are issued. If additional user data is required, the application can also call the /userinfo endpoint.

Mobile considerations

Mobile applications have some additional considerations and should follow the best practices for “native apps” outlined in RFC 8252. In short, mobile apps must:

• Use the system browser and not a webview. Both iOS and Android offer special app features to make this experience seamless for the end user:
  • iOS - ASWebAuthenticationSession
  • Android - Chrome Custom Tabs
• Set up a redirection scheme for the app’s redirect_uri using either:
  • A custom mobile redirect_uri (e.g. com.example.app://oauth2redirect/example-provider).
  • A claimed HTTPS redirect URI. Android and iOS offer support for this feature via the following:
    • iOS Universal Links
    • Android App Links
• Use Proof Key for Code Exchange (PKCE) - RFC 7636:
  • The Identity Cloud requires public clients to use PKCE.
  • With PKCE, public clients generate a one-time secret for the transaction and send a hashed version with the /authorize request. When calling the /token endpoint public clients authenticate by sending this secret.

Google has published open source libraries for mobile apps (AppAuth) that demonstrate how to implement the preceding requirements for mobile apps. These libraries are maintained by the OpenID Foundation and implement the best practices outlined in RFC 8252:

• AppAuth iOS
• AppAuth Android
   

Application session

Once the ID token received from the Identity Cloud has been validated, the application session should be enriched with user’s identity information. Issued tokens should be securely stored to support ongoing access to the user’s identity information.

The application session needs to determine how long the session is valid before the user must re-authenticate. This can be determined based on time (logins are valid for 8 hours) or can be more granular (for example, when accessing a checkout flow the user must have authenticated within the last 15 minutes).

Authorization checks

After the application has received the user’s information from the Identity Cloud, it must determine whether the user meets the requirements to use the application.

Authorization checks could include:

• Verifying user claims:
   
  • Does the user have the appropriate role?
  • Does the user have a valid subscription?
  • Is the user the appropriate age?
  • Has the user agreed to the necessary consents?

The app might also make an API call to another service to gather additional details about the user for access control decisions.

• Ensuring that the user has the necessary data in their profile to use application features:
• If any data is missing, then the app can collect this data before allowing the user to proceed.

Logout

When a user’s session is terminated -- either by the application after a predetermined period of time or by the user clicking the logout button -- the app should clean up the application session and delete the tokens that it has been issued.

The Identity Cloud implements an OAuth token revocation endpoint that conforms to RFC 7009 and invalidates all active tokens for the client. After calling the token revocation endpoint, the application should delete the tokens that were being managed locally as part of closing out the application session.