OpenID Authentication Flows

Built on top of the OAuth2 Authorization framework, OpenID Connect (OpenID) is an identity protocol that adds support for identity and authentication flows. The OpenID specification describes a number of different authentication scenarios, while OAuth2 focuses more on granting access.

It is recommended that you review the different authentication flows and grants, how to use them and which one best corresponds to your use case and application. For further information, refer to the public specifications:

Key terminology:

The Identity Provider (also known as OpenID Provider), a system that manages identities and information about them. The system provides authentication mechanisms and features through the OpenID REST API. This is the HID Authentication Service.
The resource owner (the end user), an entity that owns a protected resource and is granted access to it by authenticating themselves. This entity can be a human being and is then referred to as an end user.
The Authorization Server, the server that issues tokens and authenticates clients and resource owners.
The client (the relying party), the application that must be authenticated (trusted) before it can verify the identities of resource owners requesting access to protected resources. Most commonly, your application is the 'client' of the HID Authentication Service.

Grants and Flows

Authorization Grants are OAuth2 protocols that define the interaction between the various elements required to authenticate a user and grant access to the resources they own.

Each grant has a corresponding flow and the selecting the one that best corresponds to your needs depends on the type of client.

The following table provides guidelines about the grants and flows you should use:

Application	Grant and Flow	Tokens Issued
Server-side web application	Authorization Code (with Confidential Client) Authorization Code with PKCE	Access Tokens ID Tokens
Mobile application	Authorization Code (with Public Client and PKCE)	Access Tokens ID Tokens
Desktop application	Authorization Code (with Public Client and PKCE)	Access Tokens ID Tokens
Javascript application	Authorization Code (with Public Client and PKCE)	Access Tokens ID Tokens
Single-page application (SPA)	Authorization Code with PKCE	Access Tokens ID Tokens
Trusted application where both the client application and resource are managed by the authorization server	Resource Owner Password	Access Tokens ID Tokens
Server-side client application that does not require end user authentication	Client Credentials	Access Tokens

Supported Grant Types

The token endpoint of the HID Authentication Service server accepts the following grant types:

Standard OAuth 2.0 grant types:
- Authorization code (authorization_code) – obtained from the authentication endpoint (see section 3.1.3 of the OpenID Connect Core specification)
- Resource owner password credentials (password) – see section 4.3 of the OAuth 2.0 specification
- Client credentials (client_credentials) – see section 4.4 of the OAuth 2.0 specification
- Refresh token (refresh_token) – the client uses a refresh token to renew an access token without end-user interaction (as defined in section 12 of the OpenID Connect Core specification).
- CIBA (urn:openid:params:grant-type:ciba) - the client retrieves the authentication result by polling the token endpoint using the authentication request ID as the new grant type (as defined in section 10.1 of the OpenID CIBA specification)
  For further information, see Configuring CIBA Feedback Mode.

Proprietary grant types:
- Client secret PKI (urn:hid:oauth:grant-type:client-secret-pki) – the client authenticates itself via a mutual TLS (mTLS) authentication connection to the token endpoint with the client certificate which is registered as a HID Authentication Service PKI credential during registration.
- OTP via API (api_otp) - get an OTP (returned in the response) that you can then send to a user
- CIBA delete request (ciba_delete) - to delete a pending push request

The following standard OAuth 2.0 grant types are NOT supported:

Implicit (used only in the implicit flow which is not supported)

Authorization Code Flow

The Authorization Code flow is the most secure and the most convenient to integrate. It completely reduces the exposure of tokens to the servers (your application's back end, as well as the HID Authentication Service). Neither the end user, nor the client application has access to tokens.

Indeed, you completely delegate the authentication process to the HID Authentication Service. The end user's credentials are never disclosed to any third party application. This also means you can focus on building your application's business logic, leaving the authentication to the HID Authentication Service.

This flow is particularly suitable for web-based applications.

While being the most secure and convenient, this is also the most complex flow. Upon request of the client (your application), the resource owner (the end user) is redirected via a user agent (most commonly, the end user's browser) to the HID Authentication Service (the authorization server) that will handle the authentication. Once the authentication is carried out, the authorization server redirects the end user back to the client (your application).

During the redirection, a code parameter is exchanged between the authorization server and the client (your application). This code allows the client (your application) to get a token from the authorization server.

This way, the client (your application) completely delegates the login activity to the authorization server and never handles the credentials of the resource owner (the end user).

Resource Owner Password Flow

The Password flow is generally the most popular flow in the context of password-based authentication. The client (your application) prompts for credentials, and simply passes them to the authorization server to get a token.

This flow is ideal for trusted applications that can handle the login flow on their own (and thus process the credentials of the end user).

Note: In contrast to the client credentials flow, the received token authenticates the resource owner (the end user) and not the client (your application).

Client Credentials Flow

The Client Credentials flow is the most straight forward OpenID flow. It involves a client (your application) and an authorization server (the HID Authentication Service).

In this flow, your application authenticates against the HID Authentication Service. The client (your application) is also the resource owner.

This flow is ideal for M2M (Machine to Machine) architectures, where applications do not need any human interaction to work. For example, standalone server applications, batch services, back end daemons.

PKI authentication is recommended over password authentication in this particular flow. For further information, see Client ID authentication with JWT (PKI).

Note: This flow should only be used in M2M architectures. Other OpenID flows are preferred when human interaction involved, requiring client authentication.

Hybrid Flow

Using the OpenID hybrid authentication flow, both an authorization code and id_token can be requested from the authentication endpoint at the same time. For example, this allows the client (your application) to immediately obtain information about the the resource owner (the end user) in an ID token before it completes the process to exchange the authorization code for a token.

The HID Authentication Service OpenID API supports the combination of an authorization code and id_token as the response type (that is, code id_token).

The hybrid authentication flow is as follows:

Your client redirects the user's authentication request to the HID Authentication Service OpenID API authentication endpoint with the response type parameter set to code id_token.
HID Authentication Service authenticates the user and obtains the end-user consent (if applicable).
HID Authentication Service redirects the end user back to your client with an authorization code and id_token as defined by the response type.
Your client sends the authorization code to the token endpoint to request an access token.
Your client can then access the protected resource using this access token on behalf of the user during the validity period.

Possible use cases for the hybrid flow are to support:

Support custom scopes to get the corresponding user consent and custom claims in the ID token
Support public clients as confidential clients (public client with PKCE)

For further information about the OpenID hybrid flow, see the OpenID Connect Core specifications - section 3.3.

Implicit Flow

The implicit flow is similar to the Authorization code flow, where the only difference is that the tokens are directly returned to the user agent (the client then does not receive a code in the first place, but tokens). This flow is not currently supported by the HID Authentication Service.