Configure storefront SSO

Setting up storefront SSO involves the following steps:

Configure Commerce storefront SSO settings.
Download the service provider entity descriptor from Commerce.
Upload the service provider entity descriptor to the identity provider, then download the corresponding identity provider entity descriptor.
Upload the identity provider entity descriptor to Commerce.
Configure CORS to enable the identity provider to access Commerce resources.
Modify the storefront so that the links for logging in and accessing an account direct the shopper to either the storefront or the identity provider, as appropriate.
If your Commerce environment is running multiple sites, repeat this process for each new site you create.

These steps are described in the sections that follow.

Note that if you configure your storefront to use SSO exclusively and your identity provider allows multiple accounts to share the same email address, you should enable sharing of email addresses in Commerce as well. See Allow profiles to share an email address for information about how to do this. If you configure your storefront to support both SSO and standard logins, neither your identity provider nor Commerce should support sharing of email addresses.

Configure Commerce storefront SSO settings

Use the PUT /ccadmin/v1/merchant/samlSettings endpoint in the Admin API to configure Commerce to use storefront SSO. The endpoint request body includes the following properties that are used to create the service provider entity descriptor:

enabled – If true, support for SSO is enabled. Default is false.
nameIdPolicyFormat – The SAML name ID policy to use. Default is urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

In addition, the request body can include several properties that control the SAML security policies that Commerce enforces. The values of these properties are used to create settings in the service provider entity descriptor:

signAuthnRequest – If true, the SAML request message will be signed. Default is true.
nameIdPolicyAllowCreate – If true, Commerce allows the identity provider to create persistent name identifiers for sessions. Default is true.
requireEncryptedAssertions – If true, Commerce accepts SAML assertions from the identity provider only if they are encrypted. Default is true. For security reasons, this should be set to true in your production environment.
requireSignedResponse – If true, Commerce accepts authorization responses from the identity provider only if they include a signature. Default is true. For security reasons, this should be set to true in your production environment.

The following call enables and configures SSO on a Commerce instance:

PUT /ccadmin/v1/merchant/samlSettings  HTTP/1.1
Authorization: Bearer <access_token>

{
  "enabled": true,
  "nameIdPolicyFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
  "requireEncryptedAssertions": true,
  "requireSignedResponse": true,
  "signAuthnRequest": true,
  "nameIdPolicyAllowCreate": true
}

Note that it may take several minutes for the changes to propagate to the storefront server.

Download the service provider entity descriptors

Once you have configured SSO on your Commerce instance, you can use the GET /ccstore/v1/merchant/samlSettings endpoint in the Store API to return service provider entity descriptors. For example, if you send the following request:

GET /ccstore/v1/merchant/samlSettings  HTTP/1.1
Authorization: Bearer <access_token>

The response will be similar to this:

{
  "spEntityDescriptor": "<service provider entity descriptor>",
  "links": [
    {
      "rel": "self",
      "href": "http://myserver.example.com:7002/ccstore/v1/merchant/samlSettings"
    }
  ]
}

The entity descriptor is returned as the value of the spEntityDescriptor property. This value is an XML document using a standard SAML 2.0 format for describing the configuration of the service provider.

To return the entity descriptor in Base64 encoding, call the endpoint with the encode query parameter set to true:

GET /ccstore/v1/merchant/samlSettings?encode=true  HTTP/1.1
Authorization: Bearer <access_token>

Save the value of spEntityDescriptor as a standalone document. Note that you need to create separate service provider entity descriptors for the preview context and the live context, as they will need to be registered with the identity provider as separate service providers.

Register the two service providers (the preview context and the live context) with the identity provider. (Register both service providers with the same identity provider; do not create multiple identity providers.) Depending on the API or other tools the identity provider supplies for this purpose, you register the service providers either by uploading the service provider entity descriptor documents that you downloaded from Commerce, or by manually configuring the identity provider with the data from the documents.

Once you have registered the service providers, download the identity provider entity descriptor. There should be only one identity provider entity descriptor, which applies to both the preview context and the live context. The identity provider entity descriptor should be a Base64-encoded XML file. If the generated file is not Base64-encoded, encode it before you upload it to Commerce.

Upload the identity provider entity descriptor to Commerce

Use the PUT /ccadmin/v1/samlIdentityProviders/default endpoint to upload the identity provider entity descriptor to Commerce, and to map assertion attributes to profile properties. This mapping enables automatic creation of shopper profiles in Commerce.

The request body includes the following properties:

encodedIdpMetadata -- The Base64-encoded identity provider entity descriptor.
loginAttributeName – The identity provider attribute that stores the shopper’s login name.
emailAttributeName -- The identity provider attribute that stores the shopper’s email address.
requiredAttributeToPropertyMap – A map in which the keys are identify provider attributes and the values are the names of the corresponding required Commerce profile properties.
optionalAttributeToPropertyMap – A map in which the keys are identify provider attributes and the values are the names of additional (non-required) Commerce profile properties. (Optional.)

For example:

PUT /ccadmin/v1/samlIdentityProviders/default  HTTP/1.1
Authorization: Bearer <access_token>

{
  "loginAttributeName": "uid",
  "emailAttributeName": "email",
  "encodedIdpMetadata": "<identity provider entity descriptor>",
  "requiredAttributeToPropertyMap": {
    "uid": "login",
    "email": "email"
  },
  "optionalAttributeToPropertyMap": {
    "fName": "firstName",
    "lName": "lastName"
  }
}

Configure CORS

To allow the identity provider to make POST requests to a site running on your Commerce instance, you must add the identity provider’s domain to the list of domains for which the site supports CORS. To do this, add the domain to the allowedOriginMethods property of the corresponding site object. For example:

PUT /ccadmin/v1/sites/siteUS  HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en

{
    "properties": {
        "allowedOriginMethods": {
            "http://www.myIdentityProvider.com": "POST"
         }
    }
}

See CORS support for more information about CORS.

Modify the storefront

To enable shoppers to access SSO on your storefront, you must modify any widgets that handle login or registration. The necessary modifications depend on whether your storefront supports SSO exclusively or supports both SSO and standard logins:

If your storefront supports SSO exclusively, provide login and registration links that redirect the shopper to the identity provider.
If your storefront supports both standard logins and SSO, provide two sets of links, one set that directs the shopper to the standard login and registration and one set that directs the shopper to the identity provider.

By default, the Header Widget in Commerce includes a Login/Registration element with links to the standard login and registration. In addition, Commerce provides an SSO-specific SAML Login/Registration element. If your storefront supports SSO exclusively, you can replace the standard Login/Registration element with the SAML Login/Registration element. If your storefront supports both standard logins and SSO, you can include both login/registration elements in the widget. Note that the text and styling are identical in both elements, so if you do include both, you should modify one or both of them to make it clear which kind of login each supports.

Implement storefront SSO for multiple sites

If your Commerce environment is running multiple sites, all sites must be configured with the same identity provider. However, in the identity provider, each site should be registered as a separate service provider. (There should actually be two service providers registered for each site, one for the preview context and one for the live context.)

For each site, follow the instructions above to generate service provider entity descriptors for the preview context and live context. If your site URLs are differentiated by context root, pass the site ID in the x-ccsite header when calling the GET /ccstore/v1/merchant/samlSettings endpoint:

GET /ccstore/v1/merchant/samlSettings  HTTP/1.1
Authorization: Bearer <access_token>
x-ccsite: <siteId>

If your site URLs are differentiated by domain or subdomain, you do not need to pass the site ID in the header. Specifying the domain in the URL when calling the GET /ccstore/v1/merchant/samlSettings endpoint will identify the site.

The entity ID and assertion consumer POST location in each site’s service provider entity descriptor should match the site's base URL. Register the service providers either by uploading the service provider entity descriptor documents that you downloaded from Commerce, or by manually configuring the identity provider with the data from the documents. Note that only a single identity provider is currently supported, so all service providers must be configured in the same identify provider.

After registering the service providers, download the identity provider entity descriptor, and then use the PUT /ccadmin/v1/samlIdentityProviders/default endpoint to upload it to Commerce. (There should be only one identity provider entity descriptor for a Commerce instance, regardless of the number of sites. If you have already performed this step for one site, you can skip it for other sites you add.) The identity provider entity descriptor should be a Base64-encoded XML file. If the generated file is not Base64-encoded, encode it before you upload it to Commerce.

In addition to adding each site as a service provider, you must update the CORS allowedOriginMethods property for each site to include the identity provider.