To begin integrating OpenID Connect, ensure you have the following details:

• Client ID and Client Secret: Unique credentials provided by your Identity Provider (IdP). For example, we'll use client_abc for the Client ID and client_secret_xyz for the Client Secret.
• Authorization Endpoint: The URL from your IdP to initiate the login process, such as https://your-company.com/authorize.
• Token Endpoint: The URL for exchanging an authorization code for an ID token and access token, like https://your-company.com/token.
• SSO JWKS URL: The endpoint offering the public keys to validate JSON Web Tokens (JWTs), which is https://your-company.com/jwks.
• Issuer: The URL identifying the token's issuer, set as https://your-company.com.

Authentication Process

Authorization Request Phase

The OpenID Connect flow begins with the authorization request, redirecting users to the IdP's login page to authenticate and grant access.

Example authorization request URL:

https://your-company.com/authorize?
  response_type=code&
  client_id=client_abc&
  redirect_uri=https://your-company.northpass.com/auth/openid_connect_two_phase/callback&
  scope=openid%20profile%20email&
  state=xyzABC123&
  nonce=system_generated_unique_string

This URL directs the user to your IdP's login page, where they authenticate and grant the requested permissions.

Callback Request Phase

Upon user authentication and authorization, they're redirected back with the following callback URL:

https://your-company.northpass.com/auth/openid_connect_two_phase/callback?
    code=authorization_code_from_idp&
    state=xyzABC123

Processing the Callback

1. Verify the state parameter to prevent CSRF attacks.
2. Exchange the authorization code for tokens by sending a request to the token endpoint with the Client ID and Client Secret in a Basic Authorization header.

Token exchange request example:

POST https://your-company.com/token HTTP/1.1
Authorization: Basic Y2xpZW50X2FiYzpjbGllbnRfc2VjcmV0X3h5eg==
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=authorization_code_from_idp&
redirect_uri=https%3A%2F%2Fyour-company.northpass.com%2Fauth%2Fopenid_connect_two_phase%2Fcallback

The IdP responds with tokens in JSON format:

{
  "access_token": "eyJz93a...k4laUWw",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "id_token": "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso",
  "scope": "openid profile email"
}

The id_token contains user information, validated using the public keys from the JWKS endpoint. Here's an example of a decoded id_token payload:

{
  "iss": "https://your-company.com",
  "sub": "1234567890",
  "aud": "client_abc",
  "exp": 1615190559,
  "iat": 1615186959,
  "auth_time": 1615186958,
  "nonce": "system_generated_unique_string",
  "at_hash": "HNW1ylk3b2v_KfR4Jh5aSw",
  "c_hash": "LDkCiD4Jnm0F6_BdYHznqg",
  "email": "[email protected]",
  "name": "Jane Doe",
  "preferred_username": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe"
}

This data creates the user's profile, facilitating a personalized and secure sign-in experience.

📘

WARNING

Ensure that the nonce value embedded within the id_token matches the one generated during the Authorization Request Phase. Otherwise your id_token would be rejected.

Dynamic Group Assignment via ID Token

Our platform supports dynamic group assignment through custom attributes in the id_token. This feature allows for seamless user categorization and access management based on predefined groups. To leverage this, include an additional attribute in the id_token as follows:

{
  "iss": "https://your-company.com",
  "sub": "1234567890",
  "aud": "client_abc",
  "exp": 1615190559,
  "iat": 1615186959,
  "auth_time": 1615186958,
  "nonce": "78jKlmnOP89",
  "at_hash": "HNW1ylk3b2v_KfR4Jh5aSw",
  "c_hash": "LDkCiD4Jnm0F6_BdYHznqg",
  "email": "[email protected]",
  "name": "Jane Doe",
  "preferred_username": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "lms": {
    "groups": ["GroupName1", "GroupName2", ...]
  }
}

In this structure, the lms object contains a groups array, which should list the names of the groups as strings. Users will be automatically added to the specified groups in this array upon signing in. This facilitates immediate and appropriate access to resources and functionalities aligned with the user's roles and permissions.

Unsupported Features

Our platform is designed to streamline the authentication process using OpenID Connect. However, it's important to note certain limitations in the current implementation:

• Userinfo Endpoint: We currently do not support the Userinfo endpoint. User profile information is solely derived from the id_token obtained during the token exchange process. This means that any user attributes needed by the application must be included in the id_token claims by the Identity Provider (IdP).

Please consider this limitation when planning your integration.