Rate this page

Auth API Concepts

You should understand these concepts and terms when working with the Data Governance Broker Auth API.

Auth UI

The auth UI is the application that manages user interactions with the Broker during authentication and authorization. It acts as a client to the Auth API, but to prevent confusion with external applications, we’ll avoid use of the word client when referring to the auth UI.

The Data Governance Broker is bundled with a production-ready default auth UI. Its TypeScript source is included with the product binary in the webapps directory and is also available on GitHub. You may either customize this UI or write your own.

The OAuth Service

All interactions with the Data Governance Broker essentially radiate from a client application’s need to either identify a user or to access user data. Clients accomplish these goals by making an OpenID Connect request or, more generally, an OAuth 2 request.

When the Broker’s OAuth service receives a request, it determines if the end user should be prompted for authentication or authorization information. If such prompting is required, then the OAuth service’s authorization endpoint directs the auth UI to the authentication service. Governed by both the Broker’s configuration and its policies, the authorization endpoint orchestrates interactions between the auth UI and the authentication service.

The Authentication Service

The authentication service implements the Auth API. It handles the auth UI’s interactions with flows and identity authenticators.


Every logged-in user’s authentication state is tracked by a session persisted to the user store. Because sessions are persisted to the data layer, Auth API requests may be load balanced freely among a cluster of servers. The lifetime of a session is determined by a combination of configuration and policy called the authentication context.

Sessions are correlated to a particular user-agent using a cookie (called ‘SST’). The lifetime of this cookie may exceed the lifetime of the session itself.

Note that neither the session cookie nor the session itself is maintained by the auth UI.

Identity Authenticators

An identity authenticator is the fundamental building block of authentication with the Data Governance Broker, used to establish a user’s identity or to provide additional assurance about the identity of an authenticated user. Examples of built-in identity authenticators include the Username Password identity authenticator, which authenticates end users based on username/password credentials stored in a directory server, and the TOTP identity authenticator, which handles one-time passwords that the user provides from a special smartphone app.

Identity authenticators act as gates for an authentication flow. An authentication flow cannot be completed until some subset of its identity authenticators reaches a success state. Identity authenticators have four possible states:

Authenticator status Description
unavailable The identity authenticator cannot be used by the current user.
ready The identity authenticator is available for use.
failure The last authentication attempt using the identity authenticator was rejected, or the identity authenticator requires additional interaction.
success The user has successfully completed authentication with the identity authenticator.

Authentication Chains

An authentication chain is a collection of the identity authenticators used by a particular flow. Each chained identity authenticator has an evaluation order index and an enforcement criterion; taken together, these properties determine the behavior and success requirements of an authentication flow.

Example: Authentication Chain configuration

Understanding how authentication chains determine the outcome of the authentication process is crucial, so it’s worth pausing on an example. Consider the configuration depicted in the following image:

Example authentication chain configuration

Evaluation Order is processed in order from least to greatest, so the identity authenticators in this chain are processed in this order:

  1. Username Password
  2. Linked External Identity
  3. reCAPTCHA
  4. Registration

The Enforcement Criteria specify whether any particular identity authenticator is necessary and/or sufficient to satisfy the authentication flow. Enforcement Criteria have the following possible values:

Enforcement Criterion Description
required-continue The authenticator is required to succeed. If it succeeds or fails, authentication still continues to proceed down the chain.
required-stop-on-failure The authenticator is required to succeed. If it succeeds, authentication continues down the chain. If it fails, authentication does not proceed down the chain and is considered failed.
optional-stop-on-success The authenticator is not required to succeed. If it does succeed, authentication does not proceed down the chain and is considered success. If it fails, authentication continues down the chain.
optional-continue The authenticator is not required to succeed. If it succeeds or fails, authentication still continues to proceed down the chain.

Putting this information together, we can understand how the flow using this example authentication chain will be processed:

  • The first two identity authenticators in this configuration, Username Password and Linked External Identity, have enforcement criteria of optional-stop-on-success. They are not necessary to satisfy the authentication flow, but they are sufficient. If the user successfully authenticates with either of these identity authenticators, then this flow will be satisfied.
  • Otherwise, processing will fall through to the reCAPTCHA authenticator. At this point, the reCAPTCHA authenticator is necessary but not sufficient. If it fails, then the flow will not be satisfied, because the enforcement criterion is required-stop-on-failure.
  • As mentioned, the reCAPTCHA authenticator is not sufficient on its own. If it succeeds, then processing must continue to the Registration authenticator. At this point, there are no other identity authenticators, so the Registration authenticator must succeed for the flow to be satisfied.

Notice how the combination of ordering and enforcement criteria was used to create a coupling between the reCAPTCHA and Registration identity authenticators.


A flow represents a distinct phase during authentication processing. The Auth API presents a flow to the auth UI as a JSON document consisting of identity authenticator fields, plus fields that are specific to the flow. The auth UI retrieves a flow by making a GET request; it authenticates an end user by modifying the flow and submitting it back to the Auth API using PUT.

All flows — with the exception of the Consent Flow — are associated with a single authentication chain. Each authentication chain governs which identity authenticators are accepted and required by the flow.

Login Flow

The Login Flow establishes the identity of the end user and creates a session.

Second Factor Flow

The Second Factor Flow is used to provide additional assurance about the identity of a user who has already authenticated through the Login flow.

The Consent Flow is a special authorization flow, used to request approval from an authenticated user for a set of OAuth 2 scopes.

Account Flows

The Broker provides two offshoot flows that do not directly affect a user’s authentication state but handle account activities that may help the user to complete authentication. These are the Username Recovery Account Flow and the Password Recovery Account Flow.