Rate this page

Using the Auth API

For developers accustomed to working with REST APIs, the Auth API interaction model will be unfamiliar. The Auth API is fundamentally oriented around flows rather than resources, and the progress of these flows are driven by the server rather than by the client.

Interacting with the Auth API

Auth API interaction diagram

The Data Governance Broker authentication process is a loop in which the auth UI receives an authentication flow message from the authorization endpoint, interacts with the flow until its enforcement criteria are satisfied, and then requests the next flow until no more flows are required.

If you are writing a custom auth UI, it will essentially need to do the following:

  1. Request the first authentication flow using GET if it receives a request with the flow query parameter.
  2. Distinguish between various authentication flows and account flows and present a UI based on the identity authenticators available in the flow.
  3. Based on user input, update a flow and its identity authenticators using PUT.
  4. Request a followup response using GET when the current authentication flow is satisfied.
  5. Recognize followup responses and follow them to the next flow by requesting the included URI using GET.

The following describes the authentication process in greater detail.

Phase 1: Client app requests authentication/authorization

An end user authenticates to the Ping Identity Data Governance Broker when an application makes an OAuth 2 or OpenID Connect request to the Broker. When the Broker receives the OAuth 2 request, it checks its policies to determine whether an authentication UI needs to be presented to the end user. If so, the browser is redirected to the auth UI.

Phase 2: Auth UI receives flow URI from authorization endpoint

From that point, control passes from the OAuth 2 client to the auth UI. The auth UI must now load an authentication flow.

  1. The auth UI checks for a flow query parameter in the redirect URI received from the Broker. The value of the flow parameter will be a URI. The auth UI requests the flow URI using GET. This loads the first authentication flow.

Phase 3: Auth UI interacts with authentication flow

The auth UI now has the information it needs to present an authentication interface to the end user.

  1. The auth UI inspects the flow response for any identity authenticators and presents a UI to the end user based on the identity authenticators found.
  2. The auth UI receives input from the end user, which it submits to the Broker by updating the flow response and performing a PUT.
  3. If the authentication flow’s enforcement criteria are satisfied, then the response returned by the Broker will include a success flag with a value of true. If true, the auth UI moves to the next stage. If false, the auth UI repeats this phase.

Phase 4: Auth UI requests followup URI

After a flow has been satisfied, the auth UI makes a followup request to the authorization endpoint to determine the next flow to load.

  1. The auth UI performs a GET of the followup URI.
  2. If the Broker determines that another flow must be initiated in order to prompt for further information from the end user, then the followup response will contain a flow_uri field, and phase 3, above, is repeated. Otherwise, the followup response will contain a continue_redirect_uri field, and the auth UI proceeds to the final phase.

Phase 5: Auth UI requests continue redirect URI

If the followup response contains a continue redirect URI, then the auth UI should GET this URI. This will redirect the browser back to the OAuth 2 client, ending authentication.

Media Types

All requests and responses use the UTF-8 character encoding and are formatted as JSON.

Clients must accept the application/json media type, and should always provide an Accept request header with the value application/json.

When providing a request body with PUT requests, clients should include a Content-Type request header with the value application/json.


The final component of any flow URI generated by the Auth API is a large, opaque string. For example:


This is the flow state, an encrypted object that encapsulates the state of the current authentication process. The Auth API will change the URI’s flow state after every request in which the authentication state is changed, and the auth UI should always use the current URL with every new request.

The Auth API uses a session cookie to correlate related requests. Be sure that your auth UI sends cookies along with each request. A JavaScript application, for example, may need to explicitly set certain flags on requests using the XMLHttpRequest or Fetch API to ensure that cookies are sent with requests.

Checking for an existing login

Every flow supports a field called sessionIdentityResource. If the end user is already logged in to the Broker, then this field will be populated with specific attribute values belonging to the user. Examples might include the end user’s username, full name, or icon. The attributes included here are determined by the Session Resource Attribute property of the Broker’s Authentication Service configuration.

An auth UI can use the sessionIdentityResource to display user interface elements pertinent to the currently authenticated user, such as a username and account link. The auth UI can also use this data to streamline the login process for the user’s convenience. For example, if the auth UI is processing the Login Flow with the Username Password Authenticator, if it already has the end user’s username value from sessionIdentityResource, then it would only need to prompt for the user’s password, as in the screenshot below.

Login page with existing session

Logging in a different end user

As the above screenshot indicates, an auth UI can present UI allowing the end user to log in using a different account. It can do this from the Login Flow by simply re-prompting for the user’s credentials and submitting them.

Abandoning the authentication process

As already discussed, an auth UI transitions to a different flow by requesting the followup URI using GET. Under normal circumstances, it does not do this until the flow’s success flag is set to true. However, if the authentication process needs to be abandoned before it has succeeded, then the auth UI can immediately request the followup URI. This will cause a continue redirect URI to be returned. Once the auth UI requests the continue redirect URI, the browser will be redirected back to the client that initiated the authentication process with an error.