OpenID Connect Client Authentication

TL;DR

This guide shows you how to authenticate a client application using OpenID Connect (OIDC) with the Authorization Code flow. This is a secure way for your app to get access tokens so it can use protected resources.

1. Register Your Client Application

First, you need to register your application with an OIDC provider (like Google, Auth0, or Okta). This gives your app a unique ID and secret.

• Client ID: A public identifier for your application.
• Client Secret: A confidential key used to authenticate your application. Keep this safe!
• Redirect URIs: URLs where the OIDC provider will send responses after authentication. You’ll need at least one, and it must match exactly what you configure in your code.

The exact steps for registration vary depending on your provider; consult their documentation.

2. Initiate the Authorization Request

Your application redirects the user’s browser to the OIDC provider’s authorization endpoint. This request asks for permission to access the user’s information and resources.

1. Construct the Authorization URL: This URL includes parameters like client_id, redirect_uri, response_type=code, scope (what you want to access), and optionally state (for security).

https://your-oidc-provider.com/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=openid profile email&state=RANDOM_STATE

Redirect the User: Send an HTTP redirect to this URL. The user will be prompted to log in and grant permissions.

3. Handle the Redirect Response

After the user authenticates, the OIDC provider redirects them back to your redirect_uri with an authorization code.

1. Verify the State: Check that the state parameter in the redirect URL matches the one you sent in the initial request. This prevents cross-site request forgery (CSRF) attacks.
2. Extract the Authorization Code: Get the code parameter from the URL.

4. Exchange the Authorization Code for Tokens

Your application sends a POST request to the OIDC provider’s token endpoint, exchanging the authorization code for an access token, refresh token (optional), and ID token.

1. Construct the Token Request: This request includes client_id, client_secret, grant_type=authorization_code, code, and redirect_uri.

POST https://your-oidc-provider.com/token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI

Send the Request: Use a library or make an HTTP POST request to the token endpoint.

Parse the Response: The response will be a JSON object containing access_token, refresh_token (if granted), and id_token.

5. Use the Access Token

The access token is used to authenticate requests to protected resources.

• Include in Headers: Typically, you’ll include the access token in the Authorization header of your HTTP requests as a Bearer token:

  Authorization: Bearer YOUR_ACCESS_TOKEN

6. Refresh Tokens (Optional)

If you received a refresh token, you can use it to get a new access token without prompting the user for credentials again.

1. Construct the Refresh Token Request: This request includes client_id, client_secret, grant_type=refresh_token, and refresh_token.

POST https://your-oidc-provider.com/token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN

Send the Request: Use a library or make an HTTP POST request to the token endpoint.

Parse the Response: The response will contain a new access_token and potentially a new refresh_token.