Documentation

Initial setup and configuration for Identity SSO

To set up the initial SSO configuration for Identity, you and your commercetools Customer Success Manager (CSM) must follow several steps. Once these steps are complete, your users can sign up for an Identity account using SSO authentication.

For frequently asked questions, see Identity FAQ.

Only one person, usually the IT administrator of your company, needs to follow the steps on this page.

Step 1: Create an Identity account

  1. Go to https://identity.commercetools.com and click the Create new account link.
    Create account
  2. Enter the email address you want to sign up with and click Create account. An email with a link to sign up will be sent to your email address. Follow the link in the email within 72 hours.
  3. Fill out the form and click Create account.
    Create account form

Step 2: Inform your commercetools CSM

Next, inform your commercetools CSM that you have created an Identity account and are ready to proceed with the creation of an SSO account.

You will also need to provide your commercetools CSM with a list of domains that should be used for SSO.

Step 3: commercetools CSM performs internal actions

At this point, your commercetools CSM will create an SSO Organization on behalf of your company and inform you once it is ready.

Step 4: Configure SSO in commercetools Identity

  1. From the Identity homepage, navigate to SSO Settings > Configuration.
  2. Add the Issuer URL, Client ID, and Client Secret provided by your identity provider.
  3. For PKCE (Proof Key for Code Exchange), verify whether your identity provider supports this feature. If not, select Disable PKCE.
Identity SSO page

Next, ensure that the client application in your identity provider has the following redirect URI configured in the list of allowed callback URLs:

https://auth.identity.commercetools.com/self-service/methods/oidc/callback

The following example shows the redirect URI added to Auth0, an identity provider:

Configure redirect URI

Important notes:

  • We recommend that you create a separate client application in your identity provider, as the application itself likely requires different settings, such as a client secret.
  • Use the authorization code grant type. This differs from Merchant Center SSO, which required the implicit flow.
  • The issuer URL should be the standard Issuer URL defined in the identity provider, without the “.well-known/*” part as required in Merchant Center. For example, for Microsoft the Issuer URL is usually https://login.microsoftonline.com/<tenant_id>/v2.0

Step 5: Verify and test SSO integration

You must attempt to log in to verify that the SSO integration works correctly.

  1. In your browser, open a separate incognito window to test the integration.

    This is important in case the integration doesn't work, as you'll still be able to update the configuration in the current active session.

  2. Navigate to https://identity.commercetools.com.
  3. Enter your email address, then click Next.
  4. Enter your account password, then click Submit.

    This is a one-time step required to link the account with SSO.

  5. You are now logged into your Identity account.
  6. Contact your commercetools CSM and let them know you've finished the steps in this guide. Your commercetools CSM will verify that the SSO configuration is correct and inform you when the process is complete.

Next steps

Now that SSO is configured for your email domain(s), you can invite your users to start creating their individual Identity accounts.

If you encounter any issues or have questions, please contact your Customer Success Manager (CSM) for assistance.