Oracle Commerce Cloud - Storefront SSO with IDCS

Introduction

This article describes how to integrate customer logins to your Oracle Commerce Cloud (OCC) storefront with Oracle Identity Cloud Service (IDCS), it expands on the instructions that can be found here.  User provisioning is not covered.

Contents

• Prerequisites and Authentication

• Configuration

• Troubleshooting

• Using other Identity Providers

Prerequisites and Authentication

The OCC configuration is performed via REST requests to the OCC admin and store servers, the examples in this article use cURL to make these.

Note the hostnames of the admin server and the store server. You may come across different formats for the hosts, for example:

adminserver:     https://ccstore-stage-xxxx.yyy.com

storeserver:       https://ccadmin-stage-xxxx.yyy.com

or

adminserver      https://xxxx-adm.yyyyy.com

storeserver        https://xxxx-occ.yyyyy.com

The cURL examples use <adminserver> and <storeserver> to indicate the target host.

Before REST requests can be made, the client needs to be setup as a “Registered Application” in the Web API settings in the OCC admin console. Register the REST client and note its ID:

Authentication

The OCC REST requests are authenticated using a Bearer token obtained by a POST to the login endpoint of the admin server:

<adminserver>/ccadmin/v1/login

The request to the login endpoint uses the Registered Application ID (obtained above) as a Bearer token and the response includes an “access_token” that is used as the Bearer token in subsequent requests.

Example Login Request:

curl -X POST \nhttps://<adminserver>/ccadmin/v1/login \n-H 'Authorization: Bearer <Registered Application ID>' \n-H 'Content-Type: application/x-www-form-urlencoded' \n-d grant_type=client_credentials

Example response:

{
  "access_token": "<access_token>",
  "links": [
    {
      "rel": "self",
      "href": "https://<adminserver>/ccadmin/v1/login"
    }
  ],
  "token_type": "bearer",
  "expires_in": 300
}

Note – the access token has a short life, so once expired, a new token must be obtained by making further requests to the login service. Where subsequent steps in this article require an access token, the above method is used to obtain one.

Configuration

The high level configuration steps are:

• Configure Commerce Cloud storefront SSO settings.

• Download the Service Provider (SP) Metadata from Commerce Cloud

• Create a SAML Application in IDCS, using settings taken from the Commerce Cloud SP Metadata

• Upload the IDCS IdP metadata to Commerce Cloud

• Configure CORS to enable the IDCS to access Commerce Cloud resources

• Modify the OCC storefront to use the SAML Login/Registration widget

Configure Commerce Cloud storefront SSO settings.

This step enables Storefront SSO and sets properties that are used to create the SP metadata.

Obtain an access token, and then make the following request:

curl -X PUT \nhttps://<adminserver>/ccadmin/v1/merchant/samlSettings \n-H 'Authorization: Bearer <access_token>' \n-H 'Content-Type: application/json' \n-d '{
"enabled": true,
"nameIdPolicyFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
"requireEncryptedAssertions": false,
"requireSignedResponse": true,
"signAuthnRequest": true,
"nameIdPolicyAllowCreate": true
}'

Note, while setting up, set requireEncryptedAssertions to false – in the event of problems, this makes debugging easier. Once the setup is complete, repeat the above request with requireEncryptedAssertions set to true, remembering to change IDCS too (see later).

Download the Service Provider (SP) Metadata from Commerce Cloud

In this step, the OCC SP metadata is downloaded. The metadata contains information that is used when setting up IDCS.

Obtain an access token, and then make the following request:

curl -X GET \n'https://<storeserver>/ccstore/v1/merchant/samlSettings?encode=true' \n-H 'Authorization: Bearer <access_token>' \n-H 'x-ccsite: <site_id>' \n-H 'Content-Type: application/json' \n

Note – in the above the host is the store server, not the admin server. Also, <site_id> is the id of the OCC site that SSO is being set up for.

The response will contain the Base64 encoded SP metadata.

Example response:

{
	"spEntityDescriptor": "<sp metadata>",
	"links": [
	  {
		"rel": "self",
		"href": "<storeserver>/ccstore/v1/merchant/samlSettings?encode=true"
	  }
	]
}

Decode the Base64 encoded spEntityDescriptor and note the following values from the decoded file:

EntityDescriptor -> entityID

This should be of the form https://<storehost>/<site>

AssertionConsumerService -> Location

This should be of the form https://<storehost>/<site>/SAML/post

​The response will also contain two X509 certificates, one for encryption and the other for signing (they may be the same). Copy both certificates, format them with BEGIN/END CERTIFICATE, and save them.

For example, if the decoded OCC response contains:

<dsig:X509Certificate>ASIwDQYJKoZIhvcNAQEPADCCAQoCggEBAJSF</dsig:X509Certificate>

Copy the text between <dsig:X509Certificate> and </dsig:X509Certificate> then “top and tail” as below:

-----BEGIN CERTIFICATE-----

ASIwDQYJKoZIhvcNAQEPADCCAQoCggEBAJSF

-----END CERTIFICATE-----

Save the formatted certificates as occ-signing.cer and occ-encryption.cer. They will be required when setting up IDCS.

Create a SAML Application in IDCS, using settings taken from the OCC SP Metadata

In IDCS, navigate to Applications, press Add, then press “SAML Application”

Give the Application a meaningful name, then press Next

Fill in the fields as illustrated below and upload the OCC Signing Certificate (saved in the previous step).

Note – do not select Encrypt Assertion yet. Once the setup is complete and working, this can be selected and the OCC encryption certificate uploaded. If selected, update the Storefront SSO setting requireEncryptedAssertions to true (see first step).

Expand the Attribute Configuration and enter the Attributes as illustrated below:

The above attribute configuration assumes that a user's Primary Email is also their username, and adds the above attributes to the SAML assertion that will be passed to OCC. These IDCS attributes will be mapped to properties in the OCC profile (see next step).

Press Finish, then Activate the application.

Select the SSO Configuration tab, then press Download Identity Provider Metadata.

Add the user that will be used for testing to the IDCS application via the Users or Groups tab. 

Upload the IDCS IdP metadata to Commerce Cloud.

In this step, the downloaded IDCS IdP metadata (from the previous step) is Base64 encoded and uploaded to OCC, and the mappings from the IDCS SAML attributes to the OCC profile are defined.

Encode the IDCS IdP metadata to Base64. Obtain an access token, and then make the following request:

curl -X PUT \nhttps://<adminserver>/ccadmin/v1/samlIdentityProviders/default \n-H 'Authorization: Bearer <access_token>' \n-H 'Content-Type: application/json' \n-d '{
     "loginAttributeName": "idpEmail", 
     "emailAttributeName": "idpEmail", 
     "encodedIdpMetadata": "<Base64 encoded IdP Metadata>”, 
     "requiredAttributeToPropertyMap": {
         "idpEmail": "email"
      },
     "optionalAttributeToPropertyMap": {
          "idpLastName": "lastName",
          "idpFirstName": "firstName"
      }
}'

The above request contains the mappings for the SAML attributes to OCC profile properties. Note - while first name and last name are optional, they are required to create an OCC shopper profile if self service registration is used. 

Configure CORS to enable the IDCS to access Commerce Cloud resources.

This step enables IDCS to make requests to OCC.

Obtain an access token, and then make the following request:

curl -X PUT \nhttps://<adminserver>/ccadmin/v1/sites/<site_id> \n-H 'Authorization: Bearer <access_token>' \n-H 'Content-Type: application/json' \n-H 'x-ccasset-language: en' \n-d '{
  "properties":
  {
    "allowedOriginMethods": {
        "https://<idcs_hostname>": "POST"
    }
  }
}'

The value of <site_id> should be the id of the default site, for example siteUS. New sites will inherit the allowed origins of the default site. Note - if the SSO setup is being done retrospectively, in addition to adding IDCS to the default site, repeat the above request using the id of site being configured.   

Modify the OCC storefront to use the SAML Login/Registration widget

The detailed steps required to modify and publish the storefront are not covered in this article. Note the guidance given in the documentation.

The final step before testing is to create a user in both IDCS and OCC, ensuring that the username is the same in both. 

Troubleshooting

The expected flow is:

• User navigates to the OCC site (unauthenticated)

• Press the "Log In" link

• Browser navigates to the IDCS login page

• User enters IDCS credentials

• Browser returns to OCC - login widget will display something like:

  • Welcome <firstname>  My Account | Log Out | Wish List

Below are some of the common problems that may be encountered:

1. Pressing OCC Log In link navigates to IDCS, with an error:

Check that the Issuer in the SAML AuthnRequest from OCC matches the Entity in the IDCS application:

<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">This must match IDCS Entity ID</saml:Issuer>

2. User logs into IDCS but gets an authorization error:

Make sure that the user, or a group that the user is a member of, is added to the IDCS application.

3. The user logs into IDCS and is redirected back to OCC with the following error:

This could be a CORS problem. Make sure that the IDCS host is added to the allowed origins of the site to which access has been denied - this should be the default site. Note - changes to the allowed origins in OCC must be published using the OCC admin console.

4. The user logs into IDCS and the page redirects to OCC, but the Log In widget is still displayed. The browser console shows a 401 error on the request to the OCC store login service:

 This could be caused by:

• OCC is expecting encrypted assertions, but IDCS is not encrypting them.

  • See the first step in the configuration process.

• The attribute mapping for loginAttributeName or emailAttributeName is incorrect.

  • Verify that the AttributeStatement in the SAML assertion from IDCS contains the user's email in the attribute that was defined in IDCS and check step "Upload the IDCS IdP metadata to Commerce Cloud.". For example:

<saml:AttributeStatement>
	<saml:Attribute 
        ......
	</saml:Attribute>
    <saml:Attribute 
        ...............
    </saml:Attribute>
    <saml:Attribute 
        Name="idpEmail" 
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue 
            xmlns:xs="http://www.w3.org/2001/XMLSchema" 
            xsi:type="xs:string">useremail@test.com
        </saml:AttributeValue>
    </saml:Attribute>
</saml:AttributeStatement>

Using other Identity Providers

When configuring other identity providers the main difference is the definition of the user attribute mapping. For example, consider the following attribute statement from another identity provider:

<AttributeStatement>
    <Attribute 
		...........
    </Attribute>
	<Attribute 
		...........
    </Attribute>
    <Attribute 
        Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
        <AttributeValue>test3user3@yyy.com</AttributeValue>
    </Attribute>
    <Attribute 
        Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
        <AttributeValue>test3user3_yyy.com#EXT#@xxx.yyyyyyy.com</AttributeValue>
    </Attribute>
</AttributeStatement>

In order to map the above to OCC, the following mapping would be used:

{
"loginAttributeName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
"emailAttributeName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
"encodedIdpMetadata": "<Base64Encoded idpMetadata>",
  "requiredAttributeToPropertyMap": {
            "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress": "email"
  },
  "optionalAttributeToPropertyMap": {
         <idp firstname/lastname mappings>
    }
}

Note the identity provider attribute is http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, not simply emailaddress.

If you are using Active Directory Federation Services (ADFS), please note that ADFS has CRL validation enabled by default and it expects to find the CRL on the internet for the signing certificate associated with the SAML profile created on ADFS. The error is recorded in the ADFS Event Viewer and will be:

Exception details:
Microsoft.IdentityServer.Service.SecurityTokenService.RevocationValidationException: MSIS7098: The certificate identified by thumbprint '<VALUE>' is not valid. It might indicate that the certificate has been revoked, has expired, or that the certificate chain is not trusted.
at Microsoft.IdentityServer.Web.Protocols.Saml.SamlProtocolManager.ValidateRevocationSetting(RevocationSetting revocationSetting, ReceiverX509SigningCredentials receiverSigningCredentials, String partnerId, ServiceCertificateType certificateType)
at Microsoft.IdentityServer.Web.Protocols.Saml.SamlProtocolManager.ValidateSignatureRequirements(SamlMessage samlMessage)

The SAMLAssertion returned from ADFS will have saml status <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder" /> instead of Success:

To resolve the issue, disable CRL check for corresponding SAML profile on ADFS by running the command:

Get-AdfsRelyingPartyTrust -Identifier 'https://profile.url' | Set-AdfsRelyingPartyTrust -SigningCertificateRevocationCheck None -EncryptionCertificateRevocationCheck None

Also, in the ADFS SAML profile, in the relying party trust advanced tab,  set SHA-1 instead of SHA256.