Rate this page

Application patterns

In this article, we’ll look at some common patterns that you can use to structure your application’s interactions with the Ping Identity Data Governance Broker.

Basic goals

At a fundamental level, a client uses the Data Governance Broker for one or more of the following:

  1. Authenticate users.
  2. Gain access to data.
  3. Read and/or modify data.

Authenticating users and gaining access to data are discussed in the authentication section of this guide and the OAuth 2 and OpenID Connect API reference.

Handling data is discussed in the resources section of this guide and the SCIM API reference.

In the rest of this article, we’ll look at some specific patterns related to these topics.

Sessions

Data Governance Broker clients use the ID token issued by the Data Governance Broker’s OpenID Connect service to determine if a user is authenticated. This authentication state can then be reflected in the application itself, often by establishing a session for the user.

Because HTTP is a stateless protocol, server-side web applications typically need to use sessions to correlate requests coming from the same user. Typically, this is done by setting a cookie on the user’s browser with a unique session ID, which acts as a key to session context data maintained by the web application. Techniques for storing the session data vary. For a low-scale web application, it may be sufficient to store session data in memory, while an application in a clustered environment might need to share session data in a data store, such as a relational database or a key-value store.

For client-side applications — single-page applications, in particular — the same instance of the application resides in the browser’s memory for the duration of the user’s interaction, so there might be no need for an explicit session mechanism. However, OpenID Connect requires that the application redirect the user’s browser from the application to the Data Governance Broker’s authentication service and back to the application again, so some context must be temporarily stored. A cookie may be used, or a SessionStorage object from the HTML5 Web Storage API may be used.

One alternative is to use the ID token received from the Data Governance Broker as a session mechanism. If it is stored as the value of a cookie, then the browser will send it to the application with every request. The application can then check the ID token with each request to determine if the user should be considered authenticated. If the ID token is expired, then the client can make another OpenID Connect request to refresh the authentication state. See ID token as session mechanism to learn more about this approach, including advantages and disadvantages.

Another alternative is to present all interactions with the authentication server in a popup window. This allows the client-side application’s state to be preserved in the original browser window, without any need for temporary storage.

Triggering an authentication request

At some point, a Data Governance Broker must initiate an OpenID Connect request in order to determine the user’s authentication state and to receive an access token. There are basically two strategies for doing this; the correct strategy to choose depends upon the application’s interaction requirements.

  1. Upon initialization. As soon as the application loads, make an OpenID Connect request and handle the response.
  2. Upon first resource request. Wait until the application needs to retrieve a protected resource, such as a SCIM resource. If the request fails with a 401 response, make an OpenID Connect request to the Data Governance Broker to obtain an access token.

How the authentication process is presented to the user also depends upon the application design. In some cases, it might make sense to simply redirect the user’s browser to the authentication request URL. In other cases, it might be appropriate to display an interstitial interface so that the transition to the Data Governance Broker authentication UI is less jarring to the user. In the latter case, the interstitial interface might present a login button or link, with the authentication request URL as the target.

Before an application triggers an authentication request, it should persist the state and nonce values to be used in the request.

The sample applications provide examples of creating an OAuth 2/OpenID Connect request.

Sample Authentication handler
Broker Groovy Sign In Sample LoginHandler.groovy
My Account scim.service.ts, in the init() method

Receiving an authentication response

The Data Governance Broker’s authentication response is always returned via the client’s registered redirect URI. This is typically a route dedicated to processing the authentication response. Duties handled by this endpoint may include:

  • Handling an error, if applicable.
  • Confirming that an expected state value was returned.
  • Exchange an authorization code for an access token, if applicable.
  • Confirming that expected scopes were granted.
  • Verifying the ID token.
  • Redirecting the browser to another application route.

The sample applications provide examples of OAuth 2/OpenID Connect redirect handling.

Sample Redirect handler
Broker Groovy Sign In Sample CallbackHandler.groovy
My Account scim.service.ts, in the init() method

Step-up access

For some applications, it may make sense to step up the client’s access or the user’s level of authentication after an initial authorization or authentication request. For example, an application might require a user to authenticate using their username and password before allowing the user to view purchase receipts. But it may require that the user provide a second authentication factor before allowing the user to update their shipping address.

Step-up authorization

Step-up authorization is a step-up method in which the application needs one or more scopes than have already been granted. When the user performs some interaction requiring a greater level of access, the application simply makes another OAuth 2/OpenID Connect request, specifying the extra scopes needed and instructing the Data Governance Broker to present its approval UI by providing the prompt parameter with a value of consent.

Sample Step-up handler
Broker Groovy Sign In Sample ScopeProtectedResourceHandler.groovy

Step-up authentication

Step-up authentication is a step-up method in which the application needs the user to authenticate at a higher level based on an ACR. When the user performs some interaction requiring a higher level of authentication, the application makes another OpenID Connect request, specifying the desired level of authentication using the acr_values parameter and instructing the Data Governance Broker to present its authentication UI by providing the prompt parameter with a value of login.

Sample Step-up handler
Broker Groovy Sign In Sample AcrProtectedResourceHandler.groovy