Introduction to OpenID Connect (OIDC)

Introduction

OpenID Connect (OIDC) is an authentication protocol built on the OAuth 2.0 framework. It allows applications to verify users' identities based on the authentication performed by an authorization server, providing a secure and standardized way to authenticate users in various environments.

With OIDC, you can enable single sign-on (SSO) capabilities for your application, allowing users to authenticate once and access multiple services seamlessly. By leveraging OIDC, you can simplify the authentication process and enhance the user experience.

Key Benefits of OIDC

• Standardized Authentication: OIDC provides a well-defined authentication mechanism widely supported by identity providers and libraries, making it easier to integrate authentication into your application.
• User Identity Verification: Using OIDC, you can ensure the authenticity of user identities, preventing unauthorized access and protecting sensitive data.
• Single Sign-On (SSO): OIDC enables SSO functionality, allowing users to log in once and access multiple applications and services without reauthenticating each one.
• Secure Authentication Flow: OIDC supports secure authentication flows, such as authorization code flow and PKCE (Proof Key for Code Exchange), which protect against various security threats, including token interception and code injection attacks.

Client ID (client_id)

Each environment will have a distinct client id to be passed in the client_id parameter in your API calls to Next Identity. Those client ids will be provided to you by your Next Reason Solutions Architect.

Configurations are applied to the application as a whole, then each specific Client ID/property can have configurations that override the default settings.

For integrations that only use the OIDC and OAuth endpoints, a login client should be used with just the client id. This type of client is scoped with read and write access to only the currently authenticated user. It can only be used with sign-in and registration-based API endpoints. All client-side API calls should be made using a client with this feature.

📘

Non-standard integration note

For server-to-server API calls that are required to access user records without an access token, a direct_access client should be used. Each direct_access client should be scoped to only read/write the attributes that it needs access to.

Your Next Reason Solutions Architect can configure this.

Public Client vs. Confidential Client

OAuth defines two types of clients: confidential clients and public clients.

Confidential clients are applications that are able to securely authenticate with the authorization server, for example, being able to keep their registered client secret safe.

Public clients cannot use registered client secrets, such as applications running in a browser or on a mobile device.

Client Secret

The client secret (for use only with confidential client types and with certain endpoints that require authentication) is paired with the client id and serves as a password for that client id. This is only used with confidential client types that use server-side calls for the /token endpoint. Public clients that use PKCE for security on the /token call will not have or need a client secret.

Please see the earlier section on sharing credentials securely for details on how and when the client's secret can be shared with your team.

This credential should be treated like a password. It should not be shared over email, ticket, or chat. If you expose this credential to your team or to anyone on the Next Reason team, either in plain text or encoded as a basic authentication string, the team will need to reset your client secret just as we would reset a password if exposed.

📘

Non-standard integration note

If you are using a direct access client to modify the database directly in any API calls, you may need a client secret as well.

Redirect URI (redirect_uri)

This is the URI where the end user is redirected after authorization or other activity is completed with the hosted screens. This is also the endpoint you will use to handle receiving authorization codes and access tokens. You must provide URLs complete with the directory path if present; wildcard URLs or paths cannot be whitelisted. We also recommend using the state parameter to represent variable URL paths if needed.

This value must be whitelisted by your Next Reason Solutions Architect.

State (state)

An anti-forgery state token is required in order to keep a relationship between your application and Next Identity. The application should create a state token based on industry best practices. The state token is passed as a parameter for every request going inbound (authorization, reset-password, personal-details) and should expect the state parameter to be returned on the way back out from the authorization request, reset-password, and logout.

Creating a state token parameter

An anti-forgery state token is required in order to keep a relationship between the app and the Next Identity. The application can create a state token based on industry best practices.

The state token is passed into the Next Identity for every request going inbound (authorization, reset-password, personal-details) and should expect the state on the way back out from the authorization request, reset-password, and logout.

After completing the process, it is mandatory to validate the state parameter. For your convenience, we have provided this reference to help you properly validate this parameter.