Skip to content
Arc XP

How to use Arc XP Identity as IDP (OIDC)

OpenID Connect (OIDC) is an authentication layer that provides a standardized way for applications to authenticate users based on identity information, which is provided by an OpenID Connect provider. Arc XP’s integration with OIDC lets you accomplish several things:

  • Social login: By letting your customers use their social profiles to connect to your site, you eliminate the need for them to create new credentials unique to your site.
  • Alternative identity provider: Arc XP Identity has integrated OIDC so you can build a sign-in flow for any OIDC provider, not just social networks. You can use this sign-in flow to connect with social providers and other IDPs, like Auth0, as long as you are using the OIDC protocol.
  • Arc XP as a Provider: Arc XP Identity is also capable of serving as an OIDC provider, which allows sharing user accounts between several organizations or sites. This lets you build a sign-in flow for users who have an active session with Arc XP Identity to transfer that session to an OIDC client website without having to sign in on that site.

A client may have a web application/site that is not hosted by Arc XP, but to which the publisher wishes for its existing customers, with accounts hosted by Arc XP, to be able to sign in. For this use case Arc XP has implemented a set of APIs that make it possible to use Arc XP as an identity provider (IdP) through the OIDC protocol.

When using Arc XP as an IdP (using the OIDC protocol), your OIDC client application must be capable of interacting with Arc XP’s APIs as an OIDC client that complies with the OIDC/OAuth authorization code with PKCE flow.

The flow of events, when using Arc XP as an IdP looks as follows:

Events flow when using Arc XP as an IDP

Figure 1. Arc XP as an IDP flow

  1. User visits site/application owned by the publisher, but not hosted by Arc XP. The site has its own account management system, but as a convenience to the user, he/she will be allowed to sign in using an account that has already been registered with Arc XP.
  2. Publisher’s site redirects the user to a sign-in page hosted by Arc XP. The redirect URL must include a hashed OIDC PKCE string issued by the client site in addition to an OIDC state/session tracker also issued by the client site.
  3. The Arc XP hosted sign-in page ensures that the user is signed into his/her Arc XP account and then calls Arc XP’s OIDC login API which returns an OIDC code flow token.
  4. The Arc XP hosted sign-in page redirects the user to the publisher’s site passing the code flow token.
  5. The publisher’s site calls Arc XP’s token exchange API passing the code flow token and receiving Arc XP’s access, refresh and ID tokens.
  6. The user is now signed into the publisher hosted site which may call Arc XP hosted APIs on behalf of the user, or which tracks the user in its own database knowing who he/she is based on the ID token received in step 5.

Arc XP’s OIDC provider APIs are:

  • Login: Called by an already authenticated (to Arc XP) user to obtain the auth code that the publisher’s backend application must use during the token exchange.
  • Token Exchange: To be called by the publisher’s backend application to exchange an auth token for access, refresh and ID tokens.
  • JWKS: To be called by the publisher’s backend application to retrieve the public key used by Arc XP for signing the ID token returned by Arc XP during the token exchange step.

Arc XP as a Client

Arc XP Subscriptions Identity has enabled clients to connect identity providers to Arc XP Identity through the OIDC Authorization Code Flow.

The OIDC integration makes Arc XP Identity a ‘receiver’ of users that have signed into an external identity provider (external to Arc XP). This lets clients add a “Sign in with” option for any OIDC Identity providers.

Arc XP has two types of OIDC flows:

  • General OIDC flow: This is the standard OIDC Authorization Code Flow with PKCE. This flow is used for all OIDC providers except Apple.
  • Apple OIDC flow: This is a variation of the standard OIDC Authorization Code Flow without the PKCE. This flow is used for Apple as an IdP and involves a custom-designed helper API endpoint.

General OIDC flow

The following figure details the general OIDC flow:

OIDC Identity Flow

Figure 2.General OIDC identity flow

In this illustration only steps three through seven are defined by the OIDC protocol. Steps one, two, and eight are handoffs from Arc XP to IdP and back to Arc XP. Here is what happens in each step:

  1. Initiate Login Session: User decides that he/she wants to sign in with the Arc XP client’s IdP and calls Arc XP’s Initiate API. Arc XP provides a JS SDK for use in browsers to enable this.
  2. Session is created: Arc XP creates a login session that is valid for 10 minutes and returns a URL for the browser to redirect to. This URL is OIDC compliant and contains both a state and PKCE parameters. The PKCE challenge method will always be S256. Additionally, Arc XP will always request the OIDC openid, email, and profile scopes.
  3. Browser is redirected to IdP: The browser is redirected to the IdP’s authentication/authorization application. Here the user signs in and agrees that the IdP is allowed to share the user’s profile information with Arc XP.
  4. Browser is redirected to client’s sign-in page for Arc XP: After signing in and agreeing that the IdP can share information with Arc XP, the browser is redirected/returned to the client’s sign-in page for Arc. As defined in the OIDC Authorization Code Flow, the IdP passes an opaque code and the state parameter from step to the sign-in page through URL parameters.
  5. Code and state parameters are passed to Arc’s backend: Using a JS SDK provided by Arc XP, the browser passes the code and state parameters to Arc XP’s backend.
  6. Arc calls the IdP: Arc XP’s backend calls the IdP’s token exchange endpoint to exchange the opaque token for information about the user. During the call to the IdP, Arc XP authenticates itself through basic authentication in the HTTP authorization header.
  7. The IdP returns information to Arc XP: The IdP returns (among other information) an ID JWT to Arc XP. Arc XP will validate the JWT, which it expects to be signed, before registering the user and signing him/her into Arc XP. For signature purposes, Arc XP expects to be able to verify using one of RS256, RS384 or RS512. If all is well then Arc XP establishes an account for the user in its systems.
  8. Arc signs the user in: Arc XP’s API returns (to the SDK) access and refresh tokens that identify the user to Arc XP. The SDK stores these tokens in local storage for use by other Arc XP Subscriptions SDKs.

Arc XP’s development team has used Google’s and AWS’s Cognito implementations to validate its implementation of the OIDC Authorization Code Flow. These are available as a reference app through GitHub upon request.

Apple OIDC flow

The OIDC sign-in flow with Apple differs from the general flow. Arc XP developed a helper POST /identity/public/v2/oidc/redirect endpoint needed to assist with Apple sign-in.

The following diagram illustrates the flow of events when using Apple as an IdP: OIDC sign in flow with Apple

Figure 3. Apple OIDC identity flow

The following steps are involved in the flow:

  1. A user: Decides to sign in to your organizations’ application with Apple.
  2. A frontend application in a browser: Calls Arc XP’s GET /identity/public/v2/oidc/{clientId}/initiate endpoint to initiate the sign-in process. This call does not involve any PKCE data exchange.
  3. Arc XP’s GET /identity/public/v2/oidc/{clientId}/initiate endpoint: Returns a 200 message.
  4. A frontend application in a browser: Redirects the user to the Apple sign-in page.
  5. Apple: Renders a sign-in screen.
  6. A user: Enters their Apple credentials.
  7. Apple: Signs the user into Apple and calls the POST /identity/public/v2/oidc/redirect endpoint. Note: Apple a uses a POST call rather than HTTP redirect.
  8. The POST /identity/public/v2/oidc/redirect endpoint: Prompts the HTTP redirect.
  9. A frontend application in a browser: Redirects to organization’s sign-in application with OIDC URL parameters.
  10. Arc XP’s GET /identity/public/v2/oidc/signin endpoint: Returns a 200 message.
  11. Frontend application in a browser: Stores Arc XP’s tokens based on the business your organization (the publisher) developed.
  12. The user: Signed in with Apple and redirected to the page where they started.

Session Management

For clients that wish to be able to revoke sessions from their IdP, Arc XP has implemented the OIDC backchannel logout protocol. Clients may configure their IdPs to call Arc XP’s backchannel logout API to terminate a user’s session with Arc XP. On Arc XP’s side, the session is terminated by Arc XP refusing to issue new access tokens for session tokens that were issued before the time that the IdP called Arc XP’s logout API.

Arc XP as a Provider

Arc XP Identity is also capable of serving as an OIDC provider, which allows sharing user accounts between several organizations or sites. This lets clients build a sign-in flow for users who have an active session with Arc XP Identity to transfer that session to an OIDC client website without having to sign in there (SSO).

Details on implementation can be found at Setup Arc XP Identity as an OIDC Provider.

Arc XP’s OIDC provider APIs are:

  • Login: Called by an already authenticated (to Arc XP) user to obtain the auth code that the publisher’s backend application must use during the token exchange.
  • Token Exchange: To be called by the publisher’s backend application to exchange an auth token for access, refresh and ID tokens.
  • JWKS: To be called by the publisher’s backend application to retrieve the public key used by Arc XP for signing the ID token returned by Arc XP during the token exchange step.