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
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:
- Request the first authentication flow using GET if it receives a request with the
- Distinguish between various authentication flows and account flows and present a UI based on the identity authenticators available in the flow.
- Based on user input, update a flow and its identity authenticators using PUT.
- Request a followup response using GET when the current authentication flow is satisfied.
- 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.
- The auth UI checks for a
flowquery parameter in the redirect URI received from the Broker. The value of the
flowparameter 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.
- 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.
- The auth UI receives input from the end user, which it submits to the Broker by updating the flow response and performing a PUT.
- If the authentication flow’s enforcement criteria are satisfied, then the response returned by the Broker will include a
successflag 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.
- The auth UI performs a GET of the followup URI.
- 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_urifield, and phase 3, above, is repeated. Otherwise, the followup response will contain a
continue_redirect_urifield, 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.
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
When providing a request body with PUT requests, clients should include a
Content-Type request header with the value
Auth API URIs
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.
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.
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.