Implement social sign in using OIDC: Arc XP Identity

Arc XP Identity can serve as an authentication provider for an external system (see How to use Arc XP identity as IDP (OIDC)).

In this guide, we will demonstrate how to use two different organizations within Arc, showing how one organization can serve as the authentication provider for another. 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 in the OIDC Provider, and STAGING_QA needs to configure STAGING_DEV as the OIDC client.

This guide assumes that you have set up Identity as an OIDC provider. Please read through Configure Identity as OIDC Provider before following this guide.

OIDC flow overview and SDKs

There are several REST APIs involved in this flow, and for each one, ArcXP has created an identity SDK method to facilitate the integration into your system.

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

Call Identity.initiateOIDC with clientId (Identity.initiateOIDC(oidcClientId: string, scopes?: [string], redirect?: boolean)) from STAGING_QA. This initiates a sign-in session on Arc XP’s side which lasts 10 minutes. The response contains all the components required in order to redirect the user to the identity provider’s authorization screen. Calling this SDK will redirect to redirectURI (STAGING_DEV) 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.

You will be able to call Identity.initiateOIDC for both users who’re logged in and not logged in. Please check this document to learn more about how identities are being attached to existing accounts and or how new user accounts are being created.

Call Identity.loginWithArcIdentityAsOIDCProvider by grabbing query parameters from the redirected URI. This step is need only if you are using Arc XP as an OIDC identity provider. For our example, this call is done on STAGING_DEV 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 successful call, user would be redirected back to STAGING_QA with state and code passed in as query parameters.

Lastly, 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 in STAGING_DEV 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 ArcXP system, that mean an accessToken & refresh token will be returned.

Once the OIDC identity exists on Arc, you will be able to see this as part of the user account details. On CSR we are rendering Labels “[Not] connected to [oidcClient] account” for each oidc clients you have enabled into the system.

Other SDKs and APIs

Identity.unlinkOIDC(identifier: string) you can call this SDK to unlink custom OIDC identity from Arc. You’ll need to pass in an identifier to the SDK. Call /identity/public/v2/oidc/unlink in case you need to call the REST API directly.