Integrate with Hosted Journeys

Overview

The Next Identity Journeys offers a range of hosted customer identity solutions, including pre-registration, registration, login, forgot password, and profile management, all integrated with the OpenID Connect (OIDC) standard. By leveraging Next Identity Journeys, you can quickly deploy these features, adhere to industry best practices, ensure security and privacy, and stay at the forefront of customer identity management worldwide.

This document provides instructions to integrate Next Identity Journeys Hosted with your applications, enabling seamless user experiences.

Protected by Threat Guard

Next Identity Journeys incorporates Threat Guard, a security feature designed to safeguard your customers and protect your brand.

Before you Begin

Before integrating with Next Identity, please follow these steps:

1. Getting Started: Make sure your application connects to Next Identity, and you have the necessary client credentials and endpoint information for integration. Refer to our Getting Started page for detailed instructions.

2. Introduction to OpenID Connect: Familiarize yourself with the key concepts and terms used in OpenID Connect. Visit our Introduction to OpenID Connect page to start.

3. Developer Resources: Ensure you have the required developer resources in place for both front-end and back-end changes:

   • Front-End (UI/UX) Changes: If you plan to modify your website's user interface and experience, ensure you have the necessary front-end developer resources. These changes are typically related to allowing users to navigate to hosted screens and any other modifications you intend to make.

   • Back-End Changes: For back-end integration, you'll need to implement the following functionalities:

     • Exchange of authorization code for an access token.
     • Validation of received tokens.
     • Retrieval of additional user details or checks against your own database of user roles and permissions, if required.

Starting with the Authorize Flow for Integration

The recommended starting point for integrating Next Identity Hosted Journeys is the authorize (login) workflow. The following sequence provides an overview of the required steps, with additional details provided below.

1. The application redirects to hosted /authorize endpoint

At the minimum, your application team will need to build a button or link that will direct users to the hosted /authorize page will include all the needed parameters to make that page display and function correctly.

Full details on the /authorize endpoint and the required parameters can be found on our Hosted Journeys Login endpoint reference page.

One parameter to pay particular attention to on this first call is the state parameter. We have this separate guide dedicated to using the state parameter and guiding how applications can utilize it to preserve user navigation cues, leading to an improved user experience upon returning to your application after authentication. Explore the possibilities with the state parameter.

2. The end user authenticates on hosted screen and is redirected back to the application with an auth code

When the /authorize endpoint is hit, the hosted service will first check for an existing session for the user based on browser storage data. If an active session is found, the hosted journeys will immediately redirect back to the redirect_uri endpoint, along with an authorization code.

For users without an active session, the hosted screens will then display a sign-in screen based on the application configuration (for example, it may prompt for email and password, mobile and password, or social authentication, it depends on how the onboarding team has configured the hosted service for your specific application).

The end user will then fill in the required details, and if authentication is successful, it will redirect back to the app redirect URL along with a valid authorization code parameter.

These two scenarios will appear identical from the application’s perspective since both will result in a redirect back to your app with that authorization code appended to the URL. Other parameters will also be included in this step (such as the state parameter, which remains unchanged as it goes from your app to the hosted screens and back).

3. The application exchanges the auth code for a token

After redirecting the user back to your application, the next step is exchanging the auth code for an access token.

To get full details on using this endpoint, refer to the reference page for the token call.

Depending on the configuration, the call may be made from the front end (for single page applications with no back end and public client type configuration) or securely server to server for other configurations.

As a result, your application will receive a token (either JWT or opaque) and an id_token for the end user, with the contents of those tokens varying based on the token type and scope granted for the specific application and user.

4. The application validates the token

To ensure the validity of the provided token, the application team can validate it using the introspect endpoint. Both Opaque and JWT access tokens can be validated via our introspect endpoint.

For id_token validation, you can find the public keys to validate the kid parameter in the header at the well-known configuration, available at this link.

Detailed documentation for the introspect endpoint can be found on our introspect reference page.

5. The application takes the next step for the user

After acquiring and validating the token, the application determines the subsequent actions to be taken for the user. Possibilities include personalizing the welcome screen based on user details provided in the id_token, retrieving additional third-party information into a user dashboard, checking user roles and permissions against the application's own user store, and initiating an application-managed session.

Interaction with the hosted journeys is unnecessary unless there is a need to display the hosted journeys profile page for user profile management, fetch additional user details from Next Identity services, or log the user out of the Next Identity Hosted Journeys session.

6. The application logs out the user

When ending a user's application session, in addition to any steps taken to clear the application session, it is recommended that the application also calls the Next Identity Journeys to revoke issued tokens and end any hosted sessions.

There are two common approaches for ending a session:

1. Automatic session expiration: The application defines a session lifetime and automatically ends the session when it reaches the expiration time.

2. User-initiated logout: The application includes a logout button for the end user, triggering the logout process when clicked.

In both cases, the application should call the Next Identity /endsession endpoint to complete the logout process within Next Identity Journeys. This endpoint ensures the revocation of issued tokens and termination of hosted sessions. Further details about the /endsession endpoint can be found in the /endsession reference page.

Managing User Sessions and Re-authentication

While the Next Identity service manages its own hosted screens' sessions, it does not control the application or website session. The application always communicates with the Next Identity service, which does not actively call or alert the website/application.

As a result, if the Next Identity session lifetime is set to 20 minutes, whenever the application hits the /authorize endpoint within that 20-minute window, the Next Identity service automatically redirects the user back to the application site with an authorization code. After the Next Identity session lifetime expires, the user will be prompted to re-enter their username and password before the Next Identity service provides an authorization code.

In both scenarios, the application receives an authorization code for the user, and it's the application's responsibility to determine the subsequent actions. The application site should handle user permissions and site sessions that allow users to access content or perform tasks.

Typically, after receiving a valid authorization code through redirection, the application may start a session on its site for the user, retrieve the JWT with more user data using the /token endpoint, or both. The Next Identity configuration only affects Next Identity endpoints, not the application site itself. The application can terminate the Next Identity session proactively at any time using the /endsession endpoint. However, Next Identity cannot log out the user from their activities on the application site, as the application manages its own sessions.

By following these recommendations and utilizing the provided libraries, you can ensure a secure and optimal integration of Next Identity Journeys with your mobile applications.

📘

Seeking Further Assistance

For more specific questions or assistance, please reach out to your integration consultant.