OIDC authentication

You can configure the Generic OAuth2 Rule to use OpenID Connect (OIDC) to authenticate users and authorize them. In an environment where OIDC and OAuth 2.0 are implemented for authorization and authentication, a Service consumer calls an endpoint through a browser. The browser sends the caller to the Identity Provider (IdP) to sign in. This service could be Google, Azure, or any organization that supports OIDC through an identity provider. If not logged in, the Service consumer logs into the IdP.

If the consumer is calling an endpoint for the first time, the IdP might ask prompt the caller to share certain information. Once the consumer is authenticated and given any necessary consent, the IdP sends an ID token back to the browser. This ID token securely confirms the caller's identity. Tokens have expiration times and are encoded to prevent tampering.

The following identifies the parties and steps in the OIDC flow:

  • Authentication Request: A web application (also known as the client) directs the user to the OIDC IdP, requesting authentication. This is typically done through a browser redirect.
  • Authentication: The IdP prompts the user to authenticate by entering a username and password.

  • Authorization: If the user hasn't already granted the client permission to access their data, the IdP asks them for consent.

  • Authentication Response: After successful authentication and authorization, the IdP redirects the user back to the client. This redirect includes an authorization code, which is passed in the URL.
  • Token Request: Using the authorization code, the client makes a request directly to the IdP to exchange the code for an ID token and an access token.
  • Token Response: The IdP sends the ID token and access token to the client.
  • ID Token: The JSON Web Token (JWT) that contains information about who the user is, when they are authenticated, and how long the token is valid.
  • Access Token: This is a bearer token that the client can use to access protected resources on behalf of the user. For OIDC, it often allows the client to retrieve more information about the user from the IdP.
  • Discovery Document: A document that contains all the endpoints provided by OpenID Connect Providers. It always has the suffix .well-known/openid-configuration.

  • UserInfo Endpoint: Optionally, the client can use the access token to request additional user information from the IdP's UserInfo endpoint.

Recommendations

We recommend the following:

  • Consult the official documentation of your OIDC Provider and follow security best practices when implementing authentication and authorization mechanisms.
  • Keep your OIDC implementation updated.
  • Implement a logout mechanism that clears tokens from the client and optionally logs the user out of the OIDC provider.
  • Always use HTTPS.
  • Handle tokens securely by not exposing them unnecessarily and using secure cookie policies and storage mechanisms.
  • Before going live, thoroughly test the OIDC flow from the user’s perspective, and verify that tokens are validated correctly by the Service.
  • Document the authentication process for users or developers that will consume your API. This should include details on how to obtain tokens, how to use them with your API, and any relevant information about token expiration and renewal.