Configuring JWT authentication

Use the following information to configure the JWT authentication according to your business requirements. You can set up JWT authentication for various endpoints. For example, REST APIs.

1. Enable JWT authentication for the appropriate endpoint.
   If the endpoint is REST API, enable JWT authentication by setting the value of servlet.jwt.auth.enabled property to true in the customer_overrides.properties file. For example, xapirest.servlet.jwt.auth.enabled=true.
2. Based on the decision to use a specific type of key loader, you need to set the appropriate configurations. Key loader is used to obtain the public key to verify the incoming JWT. Sterling Order Management System, by default, provides following types of key loaders.
   Important: If you are using IBM Sterling Order Management System on IBM Cloud (SaaS), do not modify default properties. Use the issuer-specific property. For example, do not modify the yfs.yfs.jwt.verify.keyloader key loader. Instead, add a new issuer-specific key loader, yfs.yfs.jwt.<issuer_name>.verify.keyloader.

   Table 1. Application-provided key loaders

   Key loader type	Description	Configurations
   Properties key loader	It reads specific property from yfs properties to get the key. The property contains the “kid” (key ID) obtained from the JWT header. Based on the kid it tries to read the value of the key from the properties. The value of the key is expected to be a Base64 encoded PEM format.	The following properties need to be configured in the customer_overrides.properties file to use the properties key loader: yfs.yfs.jwt.verify.keyloader=properties The issuer-specific key loader can be configured as: yfs.yfs.jwt.issuer name.verify.keyloader=properties yfs.yfs.jwt.verify.propkeyloader.kid=base64 encoded public key
   Https URI public key loader	It provides a way to download the public key or certificate from an https URI at the time of JWT verification. If an https URI is used, the certificate of this https URI must be added to the JVM or application server truststore so that the application can successfully connect to the URI.	The following properties need to be configured in the customer_overrides.properties file to use the https URI public key loader. By default, Sterling Order Management System provides following https URI key loaders. You can use any one of these URI key loader options. httpsjwks - The following properties needs to be configured in the customer_overrides.properties file to use the httpsjwks key loader: yfs.yfs.jwt.verify.keyloader=httpsjwks The issuer-specific key loader can be configured as: yfs.yfs.jwt.issuer name.verify.keyloader=httpsjwks yfs.yfs.jwt.verify.keyloader.httpsuri=URI to get the key in JWKS format The issuer-specific key loader can be configured as: yfs.yfs.jwt.issuer name.verify.keyloader.httpsuri=URI to get the key in JWKS format httpsjwk - The following properties needs to be configured in the customer_overrides.properties file to use the httpsjwk key loader: yfs.yfs.jwt.verify.keyloader=httpsjwk The issuer-specific key loader can be configured as: yfs.yfs.jwt.issuer name.verify.keyloader=httpsjwk yfs.yfs.jwt.verify.keyloader.httpsuri=URI to get the key in JWK format The issuer-specific key loader can be configured as: yfs.yfs.jwt.issuer name.verify.keyloader.httpsuri=URI to get the key in JWK format httpsbase64 - The following properties needs to be configured in the customer_overrides.properties file to use the httpsbase64 key loader: yfs.yfs.jwt.verify.keyloader=httpsbase64 The issuer-specific key loader can be configured as: yfs.yfs.jwt.issuer name.verify.keyloader=httpsbase64 yfs.yfs.jwt.verify.keyloader.httpsuri=URI to get the key in Base64 encoded format The issuer-specific key loader can be configured as: yfs.yfs.jwt.issuer name.verify.keyloader.httpsuri=URI to get the key in Base64 encoded format
   Custom key loader	It provides a way to load the verification key from a vault or from custom storage. The custom implementation must implement the IPLTJWTVerificationKeyLoader interface. This interface provides method to give back a key. This key is used to verify the signature of the JWS. If needed, you can configure separate custom key loader for each issuer.	The following property needs to be configured in the customer_overrides.properties file to use a custom key loader: yfs.yfs.jwt.verify.keyloader=class name implementing IPLTJWTVerificationKeyLoader interface The issuer-specific key loader can be configured as: yfs.yfs.jwt.<issuer name>.verify.keyloader=class name implementing IPLTJWTVerificationKeyLoader interface

   Note: If you are using a third-party provider for your JWT, you can use the httpsjwks keyloader configuration for the JWT authentication. If the provider does not support a JSON Web Key Set (JWKS) endpoint, you can use the other options that are listed in the Table 1 table.
3. Identify the OMS user from the incoming JWT payload claims. The OMS user details can be provided by configuring any one of the following properties in the customer_overrides.properties file:
   • OMS User Path - yfs.yfs.jwt.defclaimparser.user.path=<path relative to the JWT body JSON to read the user>

     The issuer-specific OMS user path can be configured as: yfs.yfs.jwt.issuer name.defclaimparser.user.path=path relative to the JWT body JSON to read the user

   • OMS User Email Path - yfs.yfs.jwt.defclaimparser.user.email.path=path relative to the JWT body JSON to read the user email

     The issuer-specific OMS user email path can be configured as: yfs.yfs.jwt.issuer name.defclaimparser.user.email.path=path relative to the JWT body json to read the user email

   Example

   If the JWT payload has the following JSON structure:

   {
     "iat": 1516239022,
     "exp": 1531762065,
     "userid" : "testuser",
     "otherinfo" : { "email": "test@foo.com", "usergroup":"testGroup"}
   }

   Then, to specify the user path, set the property to:

   yfs.yfs.jwt.defclaimparser.user.path=userid

   To specify user email path, set the property to:

   yfs.yfs.jwt.defclaimparser.user.email.path=otherinfo.email

   Namely, here, the dot (.) in the path is used to traverse to a child object in the JSON structure, to denote that the object email is child of the object otherinfo.

   Note: If the values of <path relative to the JWT body JSON to read the user> or <path relative to the JWT body JSON to read the user email> contain a dot (.) character, then you must set the yfs.yfs.jwt.defclaimparser.path.delim property to use a different delimiter other than dot (.). This is because dot is a special character that is used as delimiter by default.

   yfs.yfs.jwt.defclaimparser.path.delim=<value>

   Where, value is a character that is not present in path relative to the JWT body JSON to read the user or path relative to the JWT body JSON to read the user email.

   When the paths contain dots (.), you can use the yfs.yfs.jwt.defclaimparser.path.delim property to set another delimiter to specify the path.

   For example, if the JWT payload has the following JSON structure, where the user path and user email path have the dot character:

   {
     "iat": 1516239022,
     "exp": 1531762065,
     "www.foo.com/userid" : "testuser",
     "www.foo.com/otherinfo" : { "email": "test@foo.com", "usergroup":"testGroup"}
   }

   Then, to change the delimiter, set the following property:

   yfs.yfs.jwt.defclaimparser.path.delim=$

   Because $ is not present in the path, it can be used as an alternative delimiter.

   Now, the user path and user email path can be specified as follows:

   yfs.yfs.jwt.defclaimparser.user.path=www.foo.com/userid
   yfs.yfs.jwt.defclaimparser.user.email.path=www.foo.com/otherinfo$email

   Here, the $ in the path indicates that the object email is child of the object www.foo.com/otherinfo.