---
agentTools:
  projectIndex: https://developers.northpass.com/llms.txt
---

# OpenID Connect Integration Guide

This guide is designed to assist you in integrating your Identity Provider (IdP) with our product using OpenID Connect (OIDC). Follow these steps to establish a secure authentication flow, enabling your users to access our product seamlessly with their existing credentials.

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:

```plaintext
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:

```plaintext
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:

```plaintext
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:

```json
{
  "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:

```json
{
  "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": "user@example.com",
  "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:

```json
{
  "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": "user@example.com",
  "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.