How can I authenticate in the Element-Manager Public API?
Oracle Service Cloud, all supported versions
I am unable to authenticate in the Element-Manager API
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:
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. This is a hidden configuration setting and a ticket needs to be submitted with technical support in order to have this enabled.
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
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:
"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 1000 -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
- 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