Setup Identity as an OIDC Provider

Arc XP Identity has integrated the OpenID Connect protocol (OIDC) so clients can build a sign-in flow for any OIDC provider. As part of this work, Arc XP Identity can now become an OIDC provider, which allows sharing of user accounts between several organizations or sites. See the How to use Arc XP identity as IDP article to learn more about it.

We will guide this documentation under the following scenario: The organization STAGING_QA wants to use the user accounts that already exist on “STAGING_DEV”. That means STAGING_DEV becomes the OIDC Provider, and STAGING_QA needs to configure STAGING_DEV as the OIDC client.

1. Configuring Arc as an identity provider

In STAGING_DEV or any organization with Arc XP Identity enabled that you want to use as an identity provider, you must create an OIDC Provider config. To do this, go to the settings tab, then OIDC providers.

Click the Add provider button to configure a new identity provider

Fill out the form.

Once satisfied with the configurations, click the Add button to save.

2. Configuring newly created Arc OIDC Identity Provider as an OIDC client

In STAGING_QA or in an organization where you want to use an identity provider set up in another organization, you must create the OIDC client.

See the OIDC section OIDC to set up an OIDC client.

Follow through on Set up Identity as an OIDC Provider using SDKs to finish setting up the Identity as an OIDC provider.

Select OIDC from the drop-down menu.

Fill out the required information and click Save.

OIDC flow overview and SDKs

Several REST APIs are involved in this flow, and Arc XP has created an identity SDK method for each one to facilitate integration into your system.

Once all the settings on Admin tool are completed OIDC Provider & OIDC Client setting, you are ready to implement the flow that will allow your clients sign in with an external identity provider using OIDC protocol.

Step 1: Call Identity.initiateOIDC with clientId (Identity.initiateOIDC(oidcClientId: string, scopes?: [string], redirect?: boolean)) from NewStaging

This initiates a 10-minute sign-in session on Arc XP's side. The response contains all the components required to redirect the user to the identity provider's authorization screen.

Calling this SDK will redirect to redirectURI (TheGuide) and will attach some information as query parameters.

When calling Identity.initiateOIDC, only clientId is required and this can be grabbed from calling GET  /identity/public/v1/config.

This SDK is in charge to redirect the user automatically to the page on the OIDC client side. But if you want to avoid that and get back all the configs on the BE side you should pass redirect:false. Default values for scopes are openid, email and profile and redirect is set to true. You can also override default scopes by passing an array with the scopes used by the OIDC client.

Step 2: Call Identity.loginWithArcIdentityAsOIDCProvider by grabbing query parameters from the redirected URI.

This step is needed only if you use Arc XP as an OIDC identity provider. For our example, this call is done on TheGuide organization side.

Identity.loginWithArcIdentityAsOIDCProvider(
{
        client_id: string,
        response_type: string,
        scope: string,
        redirect_uri: string,
        code_challenge: string,
        code_challenge_method: string,
        state: string
      }
)

On a successful call, the user would be redirected back to NewStaging with state and code passed in as query parameters.

Step 3: Once redirected, call Identity.signInWithOIDC with state and code from the query parameters (Identity.signInWithOIDC(state: string, code: string)).

In our example, this call is done on the NewStaging side. On successful execution, a new user account would be created, or an identity would be attached to an existing identity. At the end of this flow the user should be logged in into the Arc XP system and an accessToken and refresh token will be returned.

Once the OIDC identity exists on Arc XP, you will be able to see this as part of the user account details. In the Customer Service admin, each OIDC provider that has been enabled in the system is rendered in the Account Access tab.

Unlink Arc XP Account from OIDC Client

Call Identity.unlinkOIDC(identifier: string) to unlink a custom OIDC identity from Arc XP.

Backend APIs