Security yfs.properties

Use the customer_overrides.properties file to override properties in the Security category of yfs.properties.

The following table contains the Security yfs.properties and descriptions.

Property Values Description
Security    
api.security.enabled Valid values = Y or N

Default = Y

 Set this property to secure access to APIs. If enabled, an authorization check is performed on a user's access to an API when the user calls that API.
api.security.mode Valid values = STRICT, LAX, or DEBUG

Default = STRICT

 STRICT - If any validation fails, throw an exception. This is appropriate for production systems, if all permissions are configured properly.

LAX - Filter out and log invalid input, but continue processing. The filtering allows the system to mostly work despite incorrect input or output, while the logging helps to identify places that need change. LAX can be useful during initial development and testing.

DEBUG - Log invalid input and output, but do not filter anything or throw exceptions. This is appropriate only during initial development, to identify the permissions required by various processes.

Note: If you do not specify a security mode, then the system defaults to STRICT.

Example:

api.security.override.createorder.mode=DEBUG

This example sets access for the CreateOrder API to DEBUG.
api.security.token.enabled Valid values = Y or N

Default = Y

 If api.security.token.enabled = Y, the login API returns a special UserToken security token attribute upon successful authentication.

The api.security.token.timeout property controls how long this token is active.
api.security.token.timeout <number of milliseconds>

Default = 100000 milliseconds

 Controls how long the token needs to be active. If a value is not specified, the default value, which is 100000 milliseconds is considered.
Note: There is a max limit the token can be active.
api.security.console.enabled Valid values = Y or N

Default = N

 If api.security.console.enabled = Y, API security, in addition to the built-in security, is used for the JSP console.

Note: Enabling this property may require that you relax other security settings or take extra steps that are described in the following article:

  • Go to the link Sterling Customer Center
  • Log in, and in the Search Knowledgebase, enter “HTG2798”.
  • The article will be displayed as a selectable item.
api.security.smc.enabled Valid values = Y or N

Default = N

 If api.security.smc.enabled = Y, API security, in addition to the built-in security, is used for the Applications Manager and the system monitor console.

Note: Enabling this property may require that you relax other security settings or take extra steps that are described in the following article:

  • Go to the link Sterling Customer Center
  • Log in, and in the Search Knowledgebase, enter “HTG2798”.
  • The article is displayed as a selectable item.
api.outputDBPasswords Valid values = Y or N

Default = N

 If api.outputDBPasswords = true, passwords are returned in the output of the getDBPoolLIst and getDBConnParams APIs.
yfs.dsg.api.disable Valid values = <api_name> Set this property to disable the new data access policy functionality for specific APIs.

Example:

yfs.dsg.api.disable=<api_name, api_name, api_name>
interopservlet.security.enabled Valid values = Y or N

Default = Y

 Enables application server to authenticate a user, by using token-based or container-based authentication.
interopservlet.auth.container.enabled Valid values = Y or N

Default = N

 Set this property to “true” if you want the application server to authenticate a user by checking whether the user ID matches the requested user ID. If this property is set to “false”, container-based authentication is disabled.

Example:

interopservlet.auth.container.enabled = false
interopservlet.auth.token.enabled Valid values = Y or N

Default = Y

 Setting this property to “true” validates the user token supplied as a parameter on the request. When enabled, this also allows access to the login API, which is what supplies the user token. If this property is set to “false”, token-based authentication is disabled.

Example:

interopservlet.auth.token.enabled = true
interopservlet.auth.userPassword.enabled Valid values = Y or N

Default = Y

 Set this property to “true” if you want the user ID and password to be passed as parameters to the servlet, instead of using the typical login API/token approach.

Example:

interopservlet.auth.userPassword.enabled = true
userauthfilter.enabled Valid values = yes or no

Default = Y

 Sets a servlet filter that ensures authenticated user access to everything under web root, except for login pages.
yfs.login.singlesignon.class <class name> The class that handles Single Signon. For the com.yantra.ycp.japi.util.YCPSSOManager interface for information about how to write your own implementation for this class, see Javadoc.
yfs.security.singlesignon.enabled Valid values = Y or N

Default = Y

 If this property is set to Y, the single sign-on class is called.
Note: If the CSRF validation is enabled and the single sign-on is implemented, then it is recommended that you exclude the single sign on the landing page URI from the CSRF validation.
yfs.login.singlesignon.checkuser Valid values = Y or N

Default = N

 If this property is set to Y, each request is validated against the singleSignOn Server for the user authentication. If the property is set to N, user authentication against the singleSignOn Server is done only when the session times out.
yfs.security.authenticator <class name>

Default is not set.

 The class that is invoked for user authentication. Uncomment and change this only if you do not want to use application authentication.

For the YFSAuthenticator interface for information about how to write your own implementation for this class, see Javadoc . If you want to use the default implementation for LDAP authentication, uncomment the property and set it to com.yantra.yfs.util.YFSLdapAuthenticator.

Example:

yfs.security.authenticator=
yfs.security.ldap.factory <class name> The LDAP context factory class name as specified in your LDAP Server configuration.

Example:

yfs.security.ldap.factory=com.sun.jndi.ldap.LdapCtxFactory
yfs.security.ldap.url <url> The URL for accessing your LDAP Server as specified in your LDAP Server configuration.

Example:

yfs.security.ldap.url=ldap://<ldapservername>:<portnum>
yfs.security.ldap.ou Default is not set. The value specified for the organizational unit in your LDAP Server configuration.

Example:

yfs.security.ldap.ou=
yfs.security.ldap.o Default is not set. The value specified for the organization in your LDAP Server configuration.

Example:

yfs.security.ldap.o=
yfs.encrypter.class <class name> The class that handles encryption and decryption of credit card numbers. For the YCPEncrypter interface for information about how to write your own encrypter class, see Javadoc. If this property is not specified, then no encryption is performed.
Note: The yfs.encrypter.class is deprecated and no longer used for property encryption. You can now use security.encrypter.class for property encryption.
security.encrypter.class Valid values = <your_property_encrypter_class>

Default is not set.

 The class that handles encryption and decryption of credit card numbers. For the YCPEncrypter interface for information about how to write your own encrypter class, see Javadoc. If this property is not specified, then no encryption will be performed.
yfs.propertyencrypter.class Valid values = <class name>

Default is not set.

 This class is used for encrypting and decrypting properties specified in yfs.properties, yiclient.properties, and management.properties files. All properties that end with ".encrypted" are automatically decrypted by using this class at runtime. Use this property to encrypt critical data like user/password.
Note: The yfs.propertyencrypter.class is deprecated and no longer used for property encryption. You can now use security.propertyencrypter.class for propertyencryption.

Example:

yfs.agent.override.auth.password=<password>

can be specified as:

yfs.agent.override.auth.password.encrypted=<encrypted password>
security.propertyencrypter.class Valid values = <your_property_encrypter_class>

Default is not set

 This class will be used for encrypting and decrypting any property (except for the security.propertyencrypter.class property in the yfs.properties file) mentioned in the runtime property files (including the sandbox.cfg file). Use this property to encrypt sensitive data, such as user IDs and passwords. Properties starting with “encrypted:” are automatically decrypted at run-time.

Example:

yfs.dblogin.datasource.name=encrypted:<encrypted value>
httpOnlyCookie Valid values = true or false

Default = true

 Set the value of this property to “true”, if you want to enable the httpOnly cookie at the application server level.

Example:

yfs.httpOnlyCookie=true
For JWT authentication The below configurations are used only when JWT authentication is enabled at the endpoints, which support JWT authentication. For example, REST APIs.
yfs.jwt.verify.keyloader
Issuer specific property: yfs.jwt.<issuer name>.verify.keyloader
Important: If you are using IBM Sterling Order Management System Software on IBM Cloud (SaaS), do not modify default properties. Use the issuer-specific property.
Valid values:
  • properties
  • jkstruststore
  • httpsjwks
  • httpsjwk
  • httpsbase64
  • <class name>

Default = jkstruststore
  • Set the value of this property to “properties”, if you want to use yfs property to read the public key, which is used to verify the JWT.
    Note: If this configuration is used, the value of the “kid” present in JWT header must be unique across JWT issuers or providers.
  • Set the value of this property to “jkstruststore”, if you want to use the JKS truststore file specified as JVM system property to read the public key, which is used to verify the JWT. The truststore location and its password must be specified in the JVM startup system properties as follows:
    -Dycp.jwt.auth.trustStore=<JKS_truststore_location> -Dycp.jwt.auth.trustStorePassword=<JKS_truststore_password>
    Note:
    • If the required system properties are not configured OR the key id is not found in the above JKS trust store file, the following Java default system properties are read as fallback mechanism:
      -Djavax.net.ssl.trustStore=<truststore_location> -Djavax.net.ssl.trustStorePassword=<truststore_password>
      The truststore location must contain a JKS truststore file, which has the public certificate imported into it.
    • The public certificate must be imported into the JKS truststore file by using the Java Keytool utility with the same alias name as expected in the “kid” header param in the JWT.
    • If this configuration is used, the value of the “kid” must be unique across JWT issuers or providers.

    For example,

    The content of a typical public certificate file is as follows.
    -----BEGIN CERTIFICATE-----
MIIDWzCCAkOgAwIBAgIEHvZmITANBgkqhkiG9w0BAQsFADBeMQswCQYDVQQGEwJJ
TjELMAkGA1UECBMCS0ExEjAQBgNVBAcTCUJhbmdhbG9yZTEMMAoGA1UEChMDSUJN
MQwwCgYDVQQLEwNJQk0xEjAQBgNVBAMTCWxvY2FsaG9zdDAeFw0xODA3MjMwOTE2
MjBaFw0xODEwMjEwOTE2MjBaMF4xCzAJBgNVBAYTAklOMQswCQYDVQQIEwJLQTES
MBAGA1UEBxMJQmFuZ2Fsb3JlMQwwCgYDVQQKEwNJQk0xDDAKBgNVBAsTA0lCTTES
MBAGA1UEAxMJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
AQEArgMAvjVwG+JzU9IXCsJq4xJBPfxOhuGfUgE31wBuxedQMODrOnlH2URlpqNB
NT9lSNutXC3FFEcOdd6SB1j0vOCz7659UBRI9JIiAdQbyHTkRTTThIFM6AywsvLw
0++eIuatRpLPZOpXzUA4EQEXm/iWvb507k/xtTeeISC13bocsfN5q7ixMkEnybg9
F43y41QPETPETj6PFGf6YaTByx6r9ECQE6SpIhz0+MKchf8kye94L8+9Yk0A64JZ
wDLpNL0KGtn6RKajJspGoKi5Ogh/vqHjXJgh5NiDr8KuLrkpdX64PiOo/C3RwL53
OQIzEI+zOsHBgo0OeGIEwAkrsQIDAQABoyEwHzAdBgNVHQ4EFgQUhKsRttb1te7d
snTwSrMZ6BAAGx4wDQYJKoZIhvcNAQELBQADggEBADKeWRUFDMRGY8obEPWwv8ub
WI9bUhrwv2Ro02PaoDWbQ/9g8/EL9SbV51lu2+C5bzAFXwAaD0jKue6JsKhrbBsO
JYhxvcWvJyV6bX5R0cVbCMLxiwAnswFBZaAIk3APzWaipIPXpb0iYY4Iqg9WHBt0
BgokEX3Uh/Q/BK+o4Xn8phLp5bAmqnIbBza9IF4LJhlC877DV/BwSpBTeqKEzcTe
FOHLxZMj7hfdHwQD/y9P4MYeeE7ENDy7H8BM7fIzahTalVEKmj0BgrTi2Wf4y2TL
/FVw6wKie4Ye4CFNRc0G27T8LoJtH8cT2Q2B8tEjgvq1Qhv/hjSGmp5mKY5Skq0=
-----END CERTIFICATE-----
    This public certificate file can be imported into the truststore file by using the Java Keytool utility. The public certificate file can be in any format, which is understood by the Java Keytool utility. The public certificate file can be imported as follows:
    keytool -import -alias <kid> -file <public certificate file> -keystore <truststore file location>  -storepass <truststore password>
    The public certificate is imported into the JKS truststore file by using the alias name, which is same as the <kid> that is part of the incoming JWT.
  • Set the value of this property to “httpsjwks”, if you want to download the public key or certificate from an https URI. The expected format of the URI response is a Json Web Key Set (JWKS) JSON.
  • Set the value of this property to “httpsjwk”, if you want to download the public key or certificate from an https URI. The expected format of the URI response is a Json Web Key (JWK) JSON.
  • Set the value of this property to “httpsbase64”, if you want to download the public key or certificate from an https URI. The expected format of the URI response is a JSON containing the “kid” attribute corresponding to the “kid” header param obtained in the JWT and a “key” attribute, which has the value as base64 encoded public key.
  • If the public key needs to be obtained from a custom store for verifying the JWT, set the value of this property to a custom class implementing IPLTJWTVerificationKeyLoader interface.
yfs.jwt.verify.propkeyloader.<kid> Valid values = <base64 encoded public key, which corresponds to the key id (“kid”)>.

Default is not set.

 When this property is set, the <kid> is matched with the “kid” obtained in the incoming JWT and based on that the public key is used for verification.
Note: This property is used only when the property, yfs.jwt.verify.keyloader, is set to “properties”.

For example,

A typical base64 encoded public key is as follows:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArgMAvjVwG+JzU9IXCsJq
4xJBPfxOhuGfUgE31wBuxedQMODrOnlH2URlpqNBNT9lSNutXC3FFEcOdd6SB1j0
vOCz7659UBRI9JIiAdQbyHTkRTTThIFM6AywsvLw0++eIuatRpLPZOpXzUA4EQEX
m/iWvb507k/xtTeeISC13bocsfN5q7ixMkEnybg9F43y41QPETPETj6PFGf6YaTB
yx6r9ECQE6SpIhz0+MKchf8kye94L8+9Yk0A64JZwDLpNL0KGtn6RKajJspGoKi5
Ogh/vqHjXJgh5NiDr8KuLrkpdX64PiOo/C3RwL53OQIzEI+zOsHBgo0OeGIEwAkr
sQIDAQAB
-----END PUBLIC KEY-----
For this public key, the property can be configured as below in a single line. The new line is replaced with “\n” character.
yfs.jwt.verify.propkeyloader.<kid>=-----BEGIN PUBLIC 
KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArgMAvjVwG+JzU9IXCsJq
\n4xJBPfxOhuGfUgE31wBuxedQMODrOnlH2URlpqNBNT9lSNutXC3FFEcOdd6SB1j0
\nvOCz7659UBRI9JIiAdQbyHTkRTTThIFM6AywsvLw0++eIuatRpLPZOpXzUA4EQEX
\nm/iWvb507k/xtTeeISC13bocsfN5q7ixMkEnybg9F43y41QPETPETj6PFGf6YaTB
\nyx6r9ECQE6SpIhz0+MKchf8kye94L8+9Yk0A64JZwDLpNL0KGtn6RKajJspGoKi5
\nOgh/vqHjXJgh5NiDr8KuLrkpdX64PiOo/C3RwL53OQIzEI+zOsHBgo0OeGIEwAkr\nsQIDAQAB
\n-----END PUBLIC KEY-----
yfs.jwt.verify.key.uri.cachefor Valid values = <number of minutes>

Default = 180

 Determines the duration (in minutes) for which to cache the key obtained in the https URI response, if the standard cache-control directives are not present in the response. The response is cached as per the standard “Cache-Control” directive sent by the URI. If no valid “Cache-Control” directives are found in the response, the default caching duration is used for caching the response.
Note: This property is used only when the property, yfs.jwt.verify.keyloader, is set to any of the following values: httpsjwks, or httpsjwk, or httpsbase64.
yfs.jwt.verify.keyloader.httpsuri
Issuer specific property: yfs.jwt.<issuer name>.verify.keyloader.httpsuri
Important: If you are using IBM Sterling Order Management System Software on IBM Cloud (SaaS), do not modify default properties. Use the issuer-specific property.
Valid values = <http(s) URL>

Default is not set.

 Determines the http(s) URL to obtain the public key for verification of the JWT.
Note:
  • This property is used only when the property, yfs.jwt.verify.keyloader, is set to any of the following values: httpsjwks, or httpsjwk, or httpsbase64. The response of the URL must match the format as specified in the property, yfs.jwt.verify.keyloader. For example, if httpsjwks is used, the response must be a JWKS json.
  • If the https URL is used, the certificate of this URL should be imported into the local truststore of the JVM or application server so that application can successfully connect to the https URL.

For example,

A typical JWKS response is as follows:
{
"keys": [
{
"kty": "RSA",
"kid": "a1",
"n": "rgMAvjVwG+JzU9IXCsJq4xJBPfxOhuGfUgE31wBuxedQMODrOnlH2URlpqNBNT9lSNutXC3
FFEcOdd6SB1j0vOCz7659UBRI9JIiAdQbyHTkRTTThIFM6AywsvLw0++eIuatRpLPZOpXzUA4
EQEXm/iWvb507k
/xtTeeISC13bocsfN5q7ixMkEnybg9F43y41QPETPETj6PFGf6YaTByx6r9ECQE6SpIhz0+MKchf
8kye94L8+9Yk0A64JZwDLpNL0KGtn6RKajJspGoKi5Ogh/vqHjXJgh5NiDr8KuLrkpdX64PiOo
/C3RwL53OQIzEI+zOsHBgo0OeGIEwAkrsQ==",
"e": "AQAB"
}
]
}
A typical JWK response is as follows:
{
"kty": "RSA",
"kid": "a1",
"n": "rgMAvjVwG+JzU9IXCsJq4xJBPfxOhuGfUgE31wBuxedQMODrOnlH2URlpqNBNT9lSNutXC3
FFEcOdd6SB1j0vOCz7659UBRI9JIiAdQbyHTkRTTThIFM6AywsvLw0++eIuatRpLPZOpXzUA4
EQEXm/iWvb507k
/xtTeeISC13bocsfN5q7ixMkEnybg9F43y41QPETPETj6PFGf6YaTByx6r9ECQE6SpIhz0+MKchf
8kye94L8+9Yk0A64JZwDLpNL0KGtn6RKajJspGoKi5Ogh/vqHjXJgh5NiDr8KuLrkpdX64PiOo
/C3RwL53OQIzEI+zOsHBgo0OeGIEwAkrsQ==",
"e": "AQAB"
}
A typical httpsbase64 response is as follows:
{
"kid" : "a1",
"key" : "-----BEGIN PUBLIC 
KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArgMAvjVwG+JzU9IXCsJq
\n4xJBPfxOhuGfUgE31wBuxedQMODrOnlH2URlpqNBNT9lSNutXC3FFEcOdd6SB1j0
\nvOCz7659UBRI9JIiAdQbyHTkRTTThIFM6AywsvLw0++eIuatRpLPZOpXzUA4EQEX
\nm/iWvb507k/xtTeeISC13bocsfN5q7ixMkEnybg9F43y41QPETPETj6PFGf6YaTB
\nyx6r9ECQE6SpIhz0+MKchf8kye94L8+9Yk0A64JZwDLpNL0KGtn6RKajJspGoKi5
\nOgh/vqHjXJgh5NiDr8KuLrkpdX64PiOo/C3RwL53OQIzEI+zOsHBgo0OeGIEwAkr
\nsQIDAQAB\n-----END PUBLIC KEY-----"
}
yfs.jwt.verify.key.uri.retry.count Valid values = <numbers of times to retry connecting to the keyloader URI>>

Default = 3

 Determines number of times to retry connecting to the URL that is configured in the property, yfs.jwt.verify.keyloader.httpsuri, if the original request to the URL fails with a reason, which might be recoverable.
Note: This property is used only when the property, yfs.jwt.verify.keyloader, is set to any of the following values: httpsjwks, or httpsjwk, or httpsbase64.
yfs.jwt.verify.keyloader.req.header.<index>
Issuer specific property: yfs.jwt.<issuer name>.verify.keyloader.req.header.<index>
Important: If you are using IBM Sterling Order Management System Software on IBM Cloud (SaaS), do not modify default properties. Use the issuer-specific property.
Valid values = <header name>:<header value>

Default is not set.

 Set this property if you want to add certain request headers in the request, which are sent to obtain the verification key from the https URI. The <index> is a sequence number starting with 1, <header name> is the name of the header to be added in the outgoing request, and <header value> is the value corresponding to the request header. If there are multiple headers to be added, the value of index must be sequential for the subsequent headers. For example, 
yfs.jwt.verify.keyloader.req.header.1=Content-Type: application/json
yfs.jwt.verify.keyloader.req.header.2=CustomHeader: <required value>
yfs.jwt.claimparser.class
Issuer specific property: yfs.jwt.<issuer name>.claimparser.class
Important: If you are using IBM Sterling Order Management System Software on IBM Cloud (SaaS), do not modify default properties. Use the issuer-specific property.
Valid values = <class name>

Default is not set.

 Set the value of this property to a custom class implementing IPLTJWTClaimsParser interface. After verification of JWT, this custom claim parser is invoked to fetch a valid OMS user based on the claims received in the JWT. If custom claim parser is not configured, the default claim parser is used.
yfs.jwt.defclaimparser.user.path
Issuer specific property: yfs.jwt.<issuer name>.defclaimparser.user.path
Important: If you are using IBM Sterling Order Management System Software on IBM Cloud (SaaS), do not modify default properties. Use the issuer-specific property.
Valid values = <relative path of OMS user in the JSON body>

Default is not set.

 Path used to identify the OMS user's login ID from the incoming JWT. For example, if the JWT has a JSON body as follows:
{

        "exp": 1532980932,

        "iss" : "myissuer",

        "userinfo" : "anOmsUser",

        "userdata" : {

               "userEmail" : "fun@xyz.com"

    }

    }
, the property must be configured as follows to read the OMS user:
yfs.jwt.defclaimparser.user.path=userinfo

In this example, the property reads the OMS user's login ID value from the JWT body as “anOmsUser”.

Note: This property is not used if a custom claim parser is configured in the property, yfs.jwt.claimparser.class.
yfs.jwt.defclaimparser.user.email.path
Issuer specific property: yfs.jwt.<issuer name>.defclaimparser.user.email.path
Important: If you are using IBM Sterling Order Management System Software on IBM Cloud (SaaS), do not modify default properties. Use the issuer-specific property.
Valid values = <relative path of email address in the JSON body>

Default is not set.

 Path used to read the email as configured in the contact address of an existing OMS user from the incoming JWT. This email must uniquely identify an OMS user. For example, if the JWT has a JSON body as follows:
{

        "exp": 1532980932,

        "iss" : "myissuer",

        "userinfo" : "anOmsUser",

        "userdata" : {

               "userEmail" : "myemail@xyz.com"

    }

    }
, the property must be configured as follows to read the OMS user:
yfs.jwt.defclaimparser.user.path=userdata.userEmail

In this example, the property reads the email as configured in the OMS user's contact address email from the JWT body as “myemail@xyz.com”.

Note:
  • This property is not used if a custom claim parser is configured in the property, yfs.jwt.claimparser.class.
  • The property, yfs.jwt.defclaimparser.user.path, if configured, is given higher preference over this property.
yfs.jwt.verify.audience Valid values = <comma separated string values>

Default = oms

 Determines the allowed audience names. If the incoming JWT contains “aud” claim, the value of the “aud” claim is validated against the list of configured audiences.
Note: This property value is used only when the incoming JWT contains a claim “aud”.
yfs.jwt.verify.block.users Valid values = <comma separated values of OMS users>

Default is not set.

 Determines the OMS users, which are not allowed to be used for JWT authentication. If the OMS user obtained after JWT authentication is specified in this property, the authentication fails.
yfs.jwt.verify.block.issuers Valid values = <comma separated values of JWT issuers>

Default is not set.

 Determines the JWT issuers, which are not allowed to be used for JWT authentication. If the JWT issuer obtained after JWT parsing is specified in this property, the authentication fails.
yfs.jwt.verify.block.kids Valid values = <comma separated values of key id>

Default is not set.

 Determines the key ID values, which are not allowed to be used for JWT authentication. If the kid value obtained after JWT parsing is specified in this property, the authentication fails.