# Identity providers
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](https://openid.net/developers/how-connect-works/), built on top of [OAuth 2.0](https://oauth.net/2/) and JWT (JSON Web Token), actually enabling Single Sign-On (SSO) on the Dashboard.
{% hint style="info" %}
Identity providers can be created, updated, and deleted by [Enterprise](https://commercelayer.io/pricing) 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**.
{% endhint %}
## 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](https://docs.commercelayer.io/provisioning/api-reference/identity_providers/create) — 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](#examples)), 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:
```http
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.
{% hint style="warning" %}
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.
{% endhint %}
### Examples
Please find below some examples of how the required parameters must be set when [creating an identity provider](https://docs.commercelayer.io/provisioning/api-reference/identity_providers/create) using some of the most common 3rd-party services:
{% tabs %}
{% tab title="Auth0" %}
An example of how to set the required parameters when using [Auth0](https://auth0.com/docs/authenticate) by Okta (replace your values):
```json
"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"
}
}
}
```
{% endtab %}
{% tab title="Azure" %}
An example of how to set the required parameters when using [Microsoft Azure](https://learn.microsoft.com/en-us/entra/identity/) (replace your values):
```json
"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"
}
}
```
{% endtab %}
{% tab title="Miniorange" %}
An example of how to set the required parameters when using [Miniorange](https://developers.miniorange.com/docs/idp/) (replace your values):
```json
"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"
}
}
```
{% endtab %}
{% endtabs %}
## 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](https://dashboard.commercelayer.io/) 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.
