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
– Iftrue
, support for SSO is enabled. Default isfalse
.nameIdPolicyFormat
– The SAML name ID policy to use. Default isurn: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
– Iftrue
, the SAML request message will be signed. Default istrue
.nameIdPolicyAllowCreate
– Iftrue
, Commerce allows the identity provider to create persistent name identifiers for sessions. Default istrue
.requireEncryptedAssertions
– Iftrue
, Commerce accepts SAML assertions from the identity provider only if they are encrypted. Default istrue
. For security reasons, this should be set totrue
in your production environment.requireSignedResponse
– Iftrue
, Commerce accepts authorization responses from the identity provider only if they include a signature. Default istrue
. For security reasons, this should be set totrue
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 service providers with the identity provider
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.