Creating a JWT issuer secret by using a public key

The OMS Gateway can also be optionally configured to skip the authentication layer by using the skipAuthentication parameter. This section is applicable only if you intend to enable the authentication by using JSON Web Token verification and skipAuthentication is configured to false.

When skipAuthentication is false, the OMS Gateway requires the JWT issuers to be configured in <issuers_config>. It uses the issuer and its public key to verify the tokens on incoming API calls. This service requires only the public key (and not private key) to be configured for the verification purpose. You can use tools such as openssl to generate the public-private key pair in PEM format.

Before you begin

You must have a public key from the public-private key pair that is generated with any of the supported algorithms, RS256, RS384, RS512. For more information about creating the public-private key pair, see Step 1 - create the public-private key pair.

About this task

Whenever IBM® Sterling Order Management System Software or any other external system communicates with IBM Sterling Intelligent Promising, the calls originating from these applications must be authenticated via OMS Gateway. Therefore, you must configure the external applications as JWT issuers in the OMS Gateway. For more information about OMS Gateway, see IBM OMS Gateway Operator overview.

Procedure

Create the public-private key pair by completing following steps.
1. Use OpenSSL to create a private key, where <user> is the name for your key identity.
```
openssl genrsa -out <user>Private.pem
```
2. Create a public key.
```
openssl rsa -in <user>Private.pem -pubout -out <user>Pub.pem
```
3. View the keys by listing the keys to ensure that they are created.
```
ls -l
```

Create a JSON schema, jwt-issuer-config.json to create a JWT secret by running the following commands.

For Red Hat® OpenShift® Container Platform:

oc create secret generic <JWT_Secret_name> --from-file=jwt-issuer-config.json=<Path_to_file>\jwt-issuer-config.json -n <sip_installation_namespace>

For Kubernetes:

kubectl create secret generic <JWT_Secret_name> --from-file=jwt-issuer-config.json=<Path_to_file>\jwt-issuer-config.json -n <sip_installation_namespace>

The following example is a schema for the jwt-issuer-config.json.

{
   "jwtConfiguration":[
      {
         "iss":"oms",
         "serviceRoles": ["BUSINESS"],
         "keys":[
            {
               "jwtAlgo":"RS256",
               "publicKey":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAri9QNusRxGP6KN20UUpV\nFJlWerDa1nLg9gyRrbJk9R1n6Uqws7rtXplkGRk9CMPCU/tj7dMQuMcgzXOCIE2Q\nSPjYnn/xnvtdKqqnh9JGJyl9nZ0ApesUZ23ab0Kv7E6fkiOCs/+KhM90oYK6xSno\ntjCtl+3lGOJwcNjhFFG/5Yk1J4lS5Nhsy27O8ju/uPa8/szH1QLyIeop/kYNARXw\nzHsYsNoSfp4zGVIEg5LPuKZcO+oC6hNmg+57cRN5ThYf8rpuyiOU1tbqiqg+ZtPa\nP2aKks13A/MSZyaIqp25d21MMTE0cQzX34weoqNPz+18b4sxHTMmYWcOIq69k/Ul\nywIDAQAB\n-----END PUBLIC KEY-----",
               "kid":"kid-value"
            }
         ]
      }
   ]
}

Review the JWT properties listed in Table 1 and configure the JSON schema.

Provide the name of the secret in OMS Gateway Service environment.

Table 1. JWT properties
Property	Required	Description
iss	Yes	Specify the token issuer name as configured in the issuer configuration. It can be any external application that issued the token. For example, if IBM Sterling Order Management System Software is issuing the token, then `iss=oms`.
serviceRoles	No	Specify the role to access APIs based on the specific nature of the job functions within your business. Available options for serviceRole are BUSINESS, OPERATIONS, and ADMINISTRATION. If the serviceRole is not defined, the system does not enforce validation, allowing access to all the APIs. For more information about the service roles, see Role based access for accessing APIs.
keys	Yes	Specify the public keys which validates the JSON Web Token from the incoming requests that originates from the issuer. You can configure multiple keys for an issuer.
jwtAlgo	Yes	Specify the algorithm with which the keys are generated at JWT issuer. Supported algorithms are RS256, RS384, RS512.
publicKey	Yes	Specify the public key for JWT issuer in PEM format. Ensure that the public key begins with `-----BEGIN PUBLIC KEY---—` and ends with `-----END PUBLIC KEY-----` and new lines are replaced by '\n'.
kid	No	Specifying a KID in the `jwtConfiguration` is optional and is generally useful when you have multiple keys to validate the tokens and need to look up the right one to verify the signature. The JWT token originating from the external application (issuer), may or may not have a KID in it. If the token contains the KID, then the corresponding public key entry in the `jwtConfiguration` is considered for verification.

Important:

Expected claims: The OMS Gateway application expects iss (issuer name) and exp (expiry) claims in the token verification process.

Note: Whenever you add, modify, or delete a JWT secret, ensure that you restart the OMS Gateway deployment, for the changes to take effect.