Introduction to OpenID Connect (OIDC)

Introduction

Here are the basics you need to know about working with Open ID Connect.

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 are only using 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 are unable to 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 the 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 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.

This is an example:

developers.google.com

OpenID Connect | Google Identity | Google Developers

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.

At the end of the process, the application must validate the state parameter based on the doc above.