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 andclient_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
- Verify the
state
parameter to prevent CSRF attacks. - 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": "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"
}
This data creates the user's profile, facilitating a personalized and secure sign-in experience.
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 theid_token
claims by the Identity Provider (IdP).
Please consider this limitation when planning your integration.
Updated 7 months ago