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.

Auth API URIs

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

https://example.com/authentication/login/ARH5F9BcpEQgvFXa4ou5XScewjvmAAAAAAAAAAB46EGjDckYdyOLaptQrm9OV8vazSWZlhojAhedMLrEhiTVQk7io-I3pka7D7xMHuQMGpxy3XOfJ9wJXlZV58OarICKsOCmCg_ut8e8RyfXtLLHYjRdhFB2iGm41C3THS52pT6zc-o5GOTd7WGyxqoY51k21yCCN98rFv79FYoGObAcGqS5-3-Tq7BSb4v9A0mmYSFdNlX3W44vpxR0vCksaxVIa0fLUmz13LS6euOc944UmS3GJRUfpGvaiLlMJ4Z16yyMIbbG7iRRnQTY9c4V00PkRVehxj5sQnXUyCnr1lSz9oAxruzD3b3_shWoyD3roHcTwmlaXB3xHL7U7xaAx2f44NJG7QpVc9rwFTb4bUprZs-GmDhvYJ9ckpGOJzCRw1928bUYtQoj2K6BYLDRuDPwhSd8u-8PqGnZvECMT__5Yu1UrpzgnGoWGNNsAUPzHs1Z4MxMx4WJecoe8Fh4JhkvLI5O59WhOfYJp5mHFEprr_d3QpntUdl10dfHlRPQ1Omn4XtQqxCtx6Z5F9kaPq7HAZTpsQztb5AsyaxN_bA2eDGq7KO8a8wozZa4vM7tovZqpMKpm-wiZvR5tm0vpTG35RoQayYi8L9BuvfcHGX1H9I9MT-nyj0Vb_yPatFMdJd8UMEyhEDkZXj1gcnisra-9DkCmKV1fjYc5ATyzwVQYDIQcnBdmc2Z_M8mhWbGguA5nOAgeu1GDsFyMula1t4Ym8UdsMnIxvK1jB3etT_I2tvYletYXxKi0Avis6kKmIeSGcMD845WdAefd5iNPipz0FzRKzmVw2EMh9ihtMqajBytQuW4hjJLxH8a8TxO2J_SbRFfJma6VkDg4z0Jw4ufoJ3W3RwMcSzNj2qQxckFhHFDIimjQpHDfBAbOUA-Jwz8tX1NWfsEDn4knjlAMC07iktc0JgMQyLNLIMecDMUiDflIah2KPD4d41yl9jKWeUty3YCLcqWYKzLvQuxKZ7zeNtyncp1qHpNSimzY4V1t3PeNP_5m_m64fY4vEJoPOAvezHA_mw8omMhN6OYFMkjH8xbIGzRit6i-4A6Z539a1-FdnkumQpJUPS_GI4z_DKXmEsDaus6k_z521ZLUSIuejWqQYTwqZpwP4YdHiNOnqu1UWooH2wahvTa8KiAxSIOijYUTTlMsRVZnRIS6u6HC1-gZZIPWUiQ4xVIvw

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.

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.

Learning Tools

Before you begin writing a custom auth UI, we recommend that you spend some time familiarizing yourself with the API and its interaction patterns by doing some hands-on exploration.

Default Auth UI

The Data Governance Broker ships with a default auth UI that is tightly integrated with the example starter schema configuration. This UI, a single-page Angular application written in TypeScript, is quite suitable for real-world production use.

You can learn much about the Auth API and its proper use by simply using the default auth UI while following the Broker’s logs. We recommend using a log configuration such as the following; it will create a log at that records detailed information about the server’s authorization and authentication processing, while also omitting noise from unrelated messages.

dsconfig create-log-publisher \
  --publisher-name "Authentication Trace Logger" \
  --type file-based-trace \
  --set enabled:true \
  --set debug-message-type:authenticator-request-and-response \
  --set debug-message-type:external-identity-provider-request-and-response \
  --set debug-message-type:http-full-request-and-response \
  --set debug-message-type:server-sdk-extension \
  --set oauth-message-type:authz-request \
  --set oauth-message-type:code-consumed \
  --set oauth-message-type:code-granted \
  --set oauth-message-type:consent-deleted \
  --set oauth-message-type:consent-denied \
  --set oauth-message-type:consent-permitted \
  --set oauth-message-type:consent-requested \
  --set oauth-message-type:exception \
  --set oauth-message-type:id-token-granted \
  --set oauth-message-type:token-granted \
  --set oauth-message-type:token-revoked \
  --set oauth-message-type:token-validation \
  --set authentication-message-type:account-flow \
  --set authentication-message-type:authentication-chain-processing \
  --set authentication-message-type:login \
  --set authentication-message-type:logout \
  --set authentication-message-type:second-factor \
  --set 'exclude-path-pattern:/**/*.css' \
  --set 'exclude-path-pattern:/**/*.eot' \
  --set 'exclude-path-pattern:/**/*.gif' \
  --set 'exclude-path-pattern:/**/*.ico' \
  --set 'exclude-path-pattern:/**/*.jpg' \
  --set 'exclude-path-pattern:/**/*.js' \
  --set 'exclude-path-pattern:/**/*.png' \
  --set 'exclude-path-pattern:/**/*.svg' \
  --set 'exclude-path-pattern:/**/*.ttf' \
  --set 'exclude-path-pattern:/**/*.woff' \
  --set 'exclude-path-pattern:/**/*.woff2' \
  --set 'exclude-path-pattern:/console/**/template/**' \
  --set exclude-path-pattern:/status \
  --set log-file:logs/authn-trace \
  --set "rotation-policy:24 Hours Time Limit Rotation Policy" \
  --set "rotation-policy:Size Limit Rotation Policy" \
  --set "retention-policy:File Count Retention Policy" \
  --set "retention-policy:Free Disk Space Retention Policy"

Auth Explorer

We also provide a tool for learning the Auth API while interactively sending and receiving raw authentication requests, the Auth Explorer. You are encouraged to use this tool while following along with this reference documentation.

Using the Login flow with the Auth Explorer