1. Service Cloud REST APIREST API for Service Usage Metrics in B2C Service
  2. Reference
  3. Use JSON Web Token for Authorization

Use JSON Web Token for Authorization

Oracle B2C Service: Service Usage Metrics REST APIs uses JSON Web Token (JWT token), which is a compact token format that lets you authorize yourself.

Using JWT token for authorization involves:

Configuring the CX Site to Support JWT-based Authentication

  1. Log in to your Oracle CX site.
  2. Navigate to Configurations, and then Single Sign-On Configurations.
  3. Enable the SSO_ENABLE_EXTERNAL_IDP configuration.

    Note:

    To access Single Sign-On Configurations, you need to enable the SSO_ENABLE_EXTERNAL_IDP configuration. If your organization has already purchased this license, log in to the Configuration Assistant to enable the feature. For more information, refer Single Sign-On Configuration.

    The SSO_ENABLE_EXTERNAL_IDP configuration 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.

  4. Click the OAUTH tab.
  5. Add a new Identity Provider using the following details:
    1. Enter a name for the Entity ID. For example, sumPublicApi.
    2. Select the Active check box.
    3. Select the Enforce Audience Restriction check box.
    4. Enter a value for the Custom Audience URL. For example, /authToken
    5. Enter a provider Label. For example, sumPublicApi.
    6. Under Certificates, upload the public certificate.
  6. Click Save.

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

Generating a JWT Token

First you need to enable SSO login for the required Agent account, using these steps:

  1. Log in to your Oracle CX site.
  2. Navigate to Staff Management, and then Staff Accounts by Profile.
  3. Edit the profile for the required Agent account.
  4. In the Profile section, click Permissions.
  5. Select the SSO Login (SAML 2.0) check box.

Once you have enabled SSO login for a user account (for example ssouser), the user can generate JWT token using the following template:

Header:

{
 "alg": "RS256",
 "typ": "JWT"
}

Payload:

{
 "sub": "ssouser", //SSO Login enabled account
 "iss": "sumPublicApi", //Identity Provider Entity ID
 "exp": 1608480892, //Expiry
 "jti": "s1608480892", //Unique id which identified current session
 "aud": "/authToken" //Audience URL
}

With the above template, you can generate the required JWT token using RS256 algorithm:base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + RSASHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), privateCertificate)

You can use any of the offline or online utilities to generate a JWT token. For more information, refer to JSON Web Tokens.

Adding Trusted Root Certificates

If your Oracle CX application is not aware of the Certificate Authority which signed the public certificate (for example, in case of self-signing the certificate), then you need to upload the CA certificate.

To upload the CA certificate:

  1. Log in to your Oracle CX site.
  2. Navigate to File Manager.
  3. From the Switch to drop-down, select the Additional Root Certificates option.
  4. Click Browse and select the required certificate file.
  5. Click Go.

Generating Self-signed Certificates

To generate self-signed certificates:

  1. Open a command prompt.
  2. Create a CA root certificate by entering the following commands:
    openssl genrsa -out myCustomCA-key.pem 2048
openssl req -new -key myCustomCA-key.pem -x509 -days 800 -out myCustomCA-cert.pem
  3. Create RSA public Certificate Sign Request (CSR) and private key certificate by entering the following command:
    openssl req -new -newkey rsa:2048 -nodes -out myCustomPublic.csr -keyout myCustomPrivate.key
  4. Sign CSR with CA root certificate by entering the following command:
    openssl x509 -req -days 365 -in myCustomPublic.csr -CA myCustomCA-cert.pem -CAkey myCustomCA-key.pem -CAcreateserial -out myCustomPublic.crt

The certificate files are generated.

Note:

  • myCustomCA-cert.pem should be uploaded to File Manager, and then 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