Identity providers

The identity provider object and the allowed CRUD operations on the related resource endpoint

Identity providers allow users to authenticate themselves to the Commerce Layer Dashboard using a single set of credentials. Identity providers leverage the open standard and decentralized authentication protocol OpenID connect, built on top of OAuth 2.0 and JWT (JSON Web Token), actually enabling Single Sign-On (SSO) on the Dashboard.

Identity providers can be created, updated, and deleted by Enterprise users only (the user must be the organization's owner). For non-enterprise users and all the members of enterprise organizations other than the owner identity providers are read-only.

Setting up SSO

To enable SSO for your user you need to create at least one identity provider resource and properly set up the domains in scope. In detail:

1. Create an identity provider — to do that, choose a meaningful name (must be unique across all Commerce Layer users), specify the list of domains you want to put in scope (i.e. that will be used to validate the email address of the user that will try to log in via SSO), and add all the necessary information and parameters supplied by your IdP of choice (Auth0 by Okta, Microsoft Azure, etc. or any custom one — you can find some examples here), such as:

   • Client ID

   • Client secret

   • Issuer

   • Token URL

   • Authorize URL

   • JWKS (JSON Web Key Sets) URL

2. Add the TXT record you get from the successful response to all the domains specified in the list (you must be the domain owner).

Redirect URI

If the 3rd-party service you've chosen as your IdP requires a redirect_uri to be specified, use the following:

https://auth.commercelayer.io/users/auth/openid/callback

Identity provider status

Identity providers are created in pending status and a verification job on the specified domains is immediately started (domain existence, correct TXT record presence, etc.). On success, the status is automatically moved to verified. Otherwise, it remains pending or is moved to error (e.g. domain non-existent, verification process timed-out, etc.).

You can temporarily disable an identity provider by passing the _disable trigger attribute and eventually re-enable them by passing the _enable trigger attribute.

Since the txt_record attribute you get from the response is encoded based on the IdP keys (client ID, client secret, issuer, etc.), if you change one of them a new TXT record will be generated and the identity provider status moved back to pending until you update the TXT record with the new one on all the domains specified in the list.

Examples

Please find below some examples of how the required parameters must be set when creating an identity provider using some of the most common 3rd-party services:

Auth0

An example of how to set the required parameters when using Auth0 by Okta (replace your values):

"data": {
  "type": "identity_providers",
  "attributes": {
    "name": "My Auth0 IdP",
    "issuer": "https://dev-ioqs7ks8enwwer5i.us.auth0.com/",
    "client_id": "c6CDk4v1ZV99GrtKcfYVEZRnDDtfy3A0",
    "client_secret": "lRoJB-TrKcjhZBX8l2u0snV_GZebQwk5X9NJvJfzbD_6LL9Tk796N6ng7vxKz_If",
    "token_url": "https://dev-ioqs7ks8enwwer5i.us.auth0.com/oauth/token",
    "authorize_url": "https://dev-ioqs7ks8enwwer5i.us.auth0.com/authorize",
    "jwks_url": "https://dev-ioqs7ks8enwwer5i.us.auth0.com/.well-known/jwks.json",
    "authorize_params": {
      "organization": "org_oXGVhZkDKyi2GcLw"
    }
  }
}

Azure

An example of how to set the required parameters when using Microsoft Azure (replace your values):

"data": {
  "type": "identity_providers",
  "attributes": {
    "name": "My Entra IdP",
    "issuer": "https://login.microsoftonline.com/b55c22d0-835b-48d3-a9ac-c3513ad2476f/v2.0",
    "client_id": "9e27b34e-2289-4acc-928d-d97adf8eaabb",
    "client_secret": "A0B8Q~eM2QwggZBqnSvkgiV7sxIPB1cMDiRbCbzH",
    "token_url": "https://login.microsoftonline.com/b55c22d0-835b-48d3-a9ac-c3513ad2476f/oauth2/v2.0/token",
    "authorize_url": "https://login.microsoftonline.com/b55c22d0-835b-48d3-a9ac-c3513ad2476f/oauth2/v2.0/authorize",
    "jwks_url": "https://login.microsoftonline.com/b55c22d0-835b-48d3-a9ac-c3513ad2476f/discovery/v2.0/keys"
  }
}

Miniorange

An example of how to set the required parameters when using Miniorange (replace your values):

"data": {
  "type": "identity_providers",
  "attributes": {
    "name": "My Miniorange IdP",
    "issuer": "https://mybrand.xecurify.com/moas/discovery/v2.0/r0SkYtcRAqWC02I",
    "client_id": "r0SkYtcRAqWC02I",
    "client_secret": "4chkmsjKYesUjowUFm1ZcLtuLgI",
    "token_url": "https://mybrand.xecurify.com/moas/rest/oauth/token",
    "authorize_url": "https://mytestbrand.xecurify.com/moas/idp/openidsso",
    "jwks_url": "https://mybrand.xecurify.com/moas/discovery/v2.0/r0SkYtcRAqWC02I/.well-known/jwks"
  }
}

Logging in to the Dashboard with SSO

Once you have successfully set up and verified one or more identity providers, you can use them to log in to Dashboard with SSO. To do that:

1. Click on the Log in with SSO button.

2. Enter the name of one of the identity providers you created for your user.

3. Click on the Log in button and enter your credentials.

Login errors

When authenticating in with SSO to the Dashboard you may receive some 302 Found errors, mostly due to possible identity provider misconfigurations. Follow the suggestion displayed in the error message to fix them and try to log in again:

• Disabled — The selected provider has been disabled, please contact the organization owner.

• Non-existent — The selected provider does not exist.

• Not verified — The selected provider is not verified. Please add the provided DNS TXT record to your domain.

• In error — The selected provider is in error. The domain may not exist or we may be unable to resolve it.