How can I authenticate in the Element Manager Public API?

Environment:

Oracle B2C Service, all supported versions

Issue:

I am unable to authenticate in the Element Manager API

Resolution:

All Element Manager APIs are now exposed as public REST endpoints so that users can invoke them in a sequence to achieve the export/import functionality. To invoke EM public REST endpoints, a user should first generate a public API token using an authentication endpoint provided by Element Manager:

POST /api/elementmanager/authentication/authToken

The authToken endpoint requires an interface URL and a bearer token as request headers:

Authorization: Bearer <<jwtToken>>

interfaceUrl: <<interfaceUrl>> (eg. http://<my-site>.custhelp.com/cgi-bin/<interface_name>.cfg)

Configuring CX Site to support JWT based authentication

1. Navigate to Configurations > Single Sign-On Configurations.

Note: To access Single Sign-On Configurations, the config SSO_ENABLE_EXTERNAL_IDP should be enabled. If your organization has already purchased this license, please log into the Configuration Assistant to enable the feature by following the steps provided in the Configuration Assistant documentation below that is found in our knowledgebase answer Oracle B2C Service Configuration Assistant on Oracle Cloud Portal

           Single Sign-On Configuration (oracle.com)

SSO_ENABLE_EXTERNAL_IDP: Enables the use of an external application as the Identity Provider for the site. Default value is false, which indicates that the native Service Cloud application is the Identity Provider. If set to true, it will be possible to configure an external Identity Provider on the site. Once this IDP is configured and enabled, the site will depend on the external IDP for authentication services. 

2. Click on OAUTH tab

3. Add a new Identity Provider

• EntityID: <<entityProviderId>> (eg. emPublicApi)
• Active Checkbox: Checked
• Enforce Audience Restriction: Checked
• Custom Audience URL: <<audienceUrl>> (eg. /authToken)
• Label: <<ProviderLabel>> (eg. emPublicApi)
• Import Certificate: Upload public certificate

4. Save

Now a public API user can generate JWT Token with private certificate corresponding to the public certificate associated with the Identity Provider.

Generating JWT Token

Generation of JWT token requires an Agent account with Profile > Permissions > SSO Login (SAML 2.0) enabled. Assume there is an SSO Login enabled user-account: ssouser in the site, then the user can generate JWT Token with the following template:

Header:

{

  "alg": "RS256",

  "typ": "JWT"

}

Payload:

{

  "sub": "ssouser", //SSO Login enabled account

  "iss": "emPublicApi", //Identity Provider Entity ID

  "exp": 1608480892, //Expiry

  "jti": "s1608480892", //Unique id which identified current session

  "aud": "/authToken" //Audience URL

}

With the above template, the required JWT token can be generated using RS256 algorithm:

base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + RSASHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), privateCertificate)

There are both offline and online utilities available for the JWT token generation process (eg. https://jwt.io/).

Adding Trusted Root Certificates

If CX is not aware of the Certificate Authority which signed the public certificate (for example in case of self-signing the certificate), then the CA certificate should be uploaded to File Manager > Additional Root Certificates.

Generating self-signed certificates

1. Create a CA root certificate:

• openssl genrsa -out myCustomCA-key.pem 2048
• openssl req -new -key myCustomCA-key.pem -x509 -days 800 -out myCustomCA-cert.pem

2. Create RSA public Certificate Sign Request (CSR) and private key certificate:

• openssl req -new -newkey rsa:2048 -nodes -out myCustomPublic.csr -keyout myCustomPrivate.key

3. Sign CSR with CA root certificate

• openssl x509 -req -days 365 -in myCustomPublic.csr -CA myCustomCA-cert.pem -CAkey myCustomCA-key.pem -CAcreateserial -out myCustomPublic.crt

  Note:

• myCustomCA-cert.pem should be uploaded to File Manager > Additional Root Certificate
• myCustomPublic.crt should be associated with the Identity Provider (emPublicApi)
• myCustomPrivate.key should be used to generate JWT token using RS256 algorithm