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
- 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 that is present in the JWT and which field can be used to map to an OMS user.
Procedure
- 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
. - 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. - 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 objectotherinfo
.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 theyfs.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 inpath relative to the JWT body JSON to read the user
orpath 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:
Becauseyfs.yfs.jwt.defclaimparser.path.delim=$
$
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 objectemail
is child of the objectwww.foo.com/otherinfo
. - OMS User Path -