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.

Before you begin

Before you start configuring JWT authentication, you need to know:
  • The name of the issuer who is generating and signing the JWT with private key. The issuer name might be needed for some configurations.
  • The public key corresponding to the private key used to sign the JWT. This public key is used to verify the signature of JWT.
  • The data present in JWT and the field that is used to map to an OMS user.

Procedure

  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. For more information about the property description and example, see xapirest.properties.
  2. Based on the decision to use a specific type of key loader, set the appropriate configurations. Key loader is used to obtain the public key to verify the incoming JWT.
    By default, Sterling™ Order Management System Software provides the following types of key loaders:
    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>
    For more information about the property description and example, see Security yfs.properties.
    Truststore key loader It reads the public key from the truststore that is specified in the JVM startup arguments. It reads the public key from the truststore based on the alias, which is the value of “kid” (key ID) obtained from the JWT header. The public key must be manually added to the Java truststore JKS file and the same JKS truststore file needs to be included in the JVM startup arguments. The following property needs to be configured in the customer_overrides.properties file to use the truststore key loader:
    yfs.yfs.jwt.verify.keyloader=jkstruststore

    The issuer-specific key loader can be configured as: yfs.yfs.jwt.<issuer name>.verify.keyloader=jkstruststore

    For more information about the property description and example, see Security yfs.properties.
    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 Software 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>

    For more information about the property description and example, see Security yfs.properties.
    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>

    For more information about the property description and example, see Security yfs.properties.
  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>

    For more information about the property description and example, see Security yfs.properties.

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 the user email path, set the property to:
yfs.yfs.jwt.defclaimparser.user.email.path=otherinfo.email

Here, the dot (.) in the path is used to traverse to a child object in the JSON structure, namely, 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.