Invoke an External IDP

Uses an external IDP in your journey.

Description

This step allows you to integrate external IDP in your journey flow. For example, it can be used to redirect to an existing external IDP to authenticate the user in the IDP platform and retrieve information.

The IDP you'd like to use must be configured as an External Connection in the platform. The connection will define the custom OIDC provider configuration, including the login endpoint, authorization flow, etc. The step specifies the external connection as well as different parameters.

Once initiated, the step instructs the client to act as a relying party. Before redirecting to the external IDP, the client needs to save the journey state. Once authentication is complete, the external IDP redirects back to the page executing the journey, and the journey resumes. The OIDC flow completion occurs automatically on the journey side, and token exchange is performed. The result of the flow gets stored in an output variable so it can be accessed in subsequent journey steps.

Note

The entire journey will fail if a connection to the external IDP fails or if the IDP is inoperable.

Configuration

Field	Description
IDP Configuration	Configuration with request-specific parameters.
Output Variable	Name of the variable that stores the step result.

IDP configuration

Field	Description
External Connection *	Specify external connection from the list. If you don't have one, create it as described here.
Requested Scopes	OIDC scopes that should be included in the invocation request, in addition to the `openid` scope which is always sent. These scopes define the OIDC scopes of the access token.
Scope Expression *	Expression that yields additional scopes, which should evaluate to an array of strings.
Redirect URI	Page that the IDP would redirect the browser to when the invocation is completed. For web applications, this page needs to reinitialize the SDK and resume the journey using the SDK function that restores from state (see IDO SDK for Web)
Response Mode	Mechanism to use for returning parameters from the Authorization endpoint, where "Query" represents parameters passed as query parameters to the redirect URI and "Form Post" represents parameters encoded as HTML form values and transmitted via the HTTP POST method
Get user info from UserInfo endpoint	Select this to invoke the UserInfo Endpoint for requested claims.
Requested ACR Values	Set of ACR values requested to be used for processing the authentication request, with values appearing in order of preference. If the ACR value is satisfied by the authentication performed, it is returned as the `acr` claim value.
ACR Expression	Expression that yields additional ACR values, which should evaluate to an array of strings.
ACR Claim Validation	If ACR values are requested, this determines how the returned acr claim will be validated.
Requested Claims	Expression that resolves to a JSON object that will be passed via the claims request parameter. This allows requesting additional claims for the ID token or userinfo response (in addition to the defaults, and those returned based on the requested scopes and ACR values).
Additional Authorize Parameters	Additional parameters sent in the request to the authorization endpoint. The parameters are set as name/value pairs, where the value is an interpolated string that is evaluated when the request is sent (upon step execution). For example, to send the `login_hint` parameter with the user’s email address, set the Query Parameter Name to `login_hint` and the value to `${clientData.userEmail}` that contains an email address previously collected from the user with a "Get Information from Client" step.

Example

Consider a journey where authentication is delegated to an external identity provider. Once the journey reaches the Invoke External IDP step, it triggers an external connection and the client redirects to the IDP for login and then resumes the journey after completing the authentication process.

When executed, this step sends a callback to the client with the IDO service response object. It will have the journeyStepId set to invokeIDP and the data will include provider- and request-specific details:

Copy

Copied

{
 "data": {
   "authorization_url": "<URL_OF_THE_AUTHORIZATION_ENDPOINT>",
   "authorization_request_method": "<GET_OR_POST>",
   "invocation_method": "<PAGE_OR_POPUP>",
   "idp_name": "<IDP_NAME>"
 }
}

Upon extracting the values from data, the client needs to save the state of the IDO SDK by calling the serialize state function (see IDO SDK for Web) and, for example, saving the state in the local storage. Once the user completes authentication, the external IDP redirects back to the client that loads the state in order to resume the journey (see IDO SDK for Web). The client then processes incoming query parameters and submits the response to the journey using the IDO SDK call.

Copy

Copied

// On page load
const params = Object.fromEntries(new URLSearchParams(window.location.search).entries());
const sdkState = loadFromLocalStorage(); // Implementation of this function is up to the developer
if (params.code && params.state && sdkState) {
    // Indicates the journey resumes after redirection
    const idoResponse = window.tsPlatform.ido.restoreFromSerializedState(sdkState);
    if (idoResponse.journeyStepId === IdoJourneyActionType.InvokeIDP) {
      handleInvokeIdp(idoResponse);
    } else { /* Handle this */ }
} else { // Indicates a regular journey flow
    // TODO: Init IDO DK, start journey, and loop+switch on IdoJourneyActionType
    //
}

// Handle the InvokeIDP step
async function handleInvokeIdp(idoResponse) {
  const params = Object.fromEntries(new URLSearchParams(window.location.search).entries());

  if (params.code && params.state) {
    // External IDP returns the code and state in the URL
    // Submit the data to the SDK
    const data = {
      idp_response: {
        code: params.code,
        state: params.state,
      },
    };

    await window.tsPlatform.ido.submitClientResponse(ClientResponseOptionType.ClientInput, data);
  } else {
    // If the code and state are not in the URL, redirect the user to the IDP
    const sdkState = window.tsPlatform.ido.serializeState();
    await saveToLocalStorage(sdkState); // implementation of this function is up to the developer

    window.location.href = idoResponse.data?.authorization_url;
  }
}