Auth

Auth is a core module that is required in order to access ipf services. There are currently 3 types of authentication that are supported: Basic Auth, OAuth 2.0 and SAML.

The authentication methods can be enabled with the following commands:

ipf.business-operations.auth.basic-auth.enabled = true

ipf.business-operations.auth.saml2.enabled = true

ipf.business-operations.auth.oauth2.enabled = true

Configuration

For each type of authentication you will need to provide a configuration file. It is also necessary to change the default value of the max-age of the Strict Transport Security header for HTTP requests.

Basic Auth

Basic auth should not be used in production and is disabled by default. It is intended only for development and testing purposes.

For production environments, clients must use SSO authentication via Saml 2 or OAuth 2, which provide enhanced security and support for MFA.

For the basic auth you will need to provide a configuration similar to one in the example below, specifying the users and the mapping between the processing entities and the ipf roles.

users = [
  {
    username: "admin"
    password: "p4ssw0rd"
    roles: {
      BANK_ENTITY_1 = [ROLE_HTM_VIEWER, ROLE_HTM_EXECUTE, ROLE_HTM_APPROVER, ROLE_HTM_B_C, ROLE_HTM_B_R, ROLE_AUDIT, ROLE_METRICS, ROLE_PAYMENT, ROLE_PAYMENT_EXPORT, ROLE_DPS_P_R, ROLE_DPS_AS_R, ROLE_DPS_AS_C, ROLE_DPS_AS_A, ROLE_DPS_AS_U, ROLE_DPS_AS_D, ROLE_DPS_GP_R, ROLE_DPS_GP_C, ROLE_DPS_GP_A, ROLE_DPS_GP_U, ROLE_DPS_GP_D, ROLE_DPS_PE_R, ROLE_DPS_PE_C, ROLE_DPS_PE_A, ROLE_DPS_PE_D, ROLE_DPS_PE_U, ROLE_DPS_BF_R, ROLE_DPS_BF_C, ROLE_DPS_BF_A, ROLE_DPS_BF_D, ROLE_DPS_BF_U, ROLE_DPS_SO_R, ROLE_DPS_SO_C, ROLE_DPS_SO_U, ROLE_DPS_SO_A, ROLE_DPS_SO_D]
      BANK_ENTITY_2 = [ROLE_AUDIT, ROLE_METRICS, ROLE_PAYMENT, ROLE_DPS_P_R, ROLE_DPS_AS_R, ROLE_DPS_GP_R, ROLE_DPS_PE_R, ROLE_DPS_BF_R, ROLE_DPS_SO_R]
    }
  }, {
    username: "guest"
    password: "guest"
    roles: {
      BANK_ENTITY_1 = [ROLE_GUEST, ROLE_PAYMENT]
    }
  }
]
users = ${?env.users}

OAuth 2

If you are using OAuth 2, you will need to provide configuration similar to the example below.

oauth2 {
    enabled = false
    registration-id = "example-app-id"
    client-id = "login-app-client-id"
    client-secret = "secret"
    scopes = "openid, roles"
    authorization-uri = "http://example-url/auth"
    token-uri = "http://example-url/token"
    jwk-set-uri = "http://example-url/certs"
    userinfo-uri = "http://example-url/userinfo"
    return-url = "/"
    roles-attribute = "roles"
    roles-separator = ","
    roles-from-attributes = true
    username = "preferred_username"
    ipf-roles = false
    roles-mapping {
      BANK_ENTITY_1 {
        TECHNICAL_BANK_OPERATOR = [ROLE_PAYMENT, ROLE_PAYMENT_EXPORT, ROLE_DPS_P_R, ROLE_DPS_AS_R, ROLE_DPS_AS_C, ROLE_DPS_AS_A, ROLE_DPS_AS_U, ROLE_DPS_AS_D, ROLE_DPS_GP_R, ROLE_DPS_GP_C, ROLE_DPS_GP_A, ROLE_DPS_GP_U, ROLE_DPS_GP_D, ROLE_DPS_PE_R, ROLE_DPS_PE_C, ROLE_DPS_PE_A, ROLE_DPS_PE_D, ROLE_DPS_PE_U, ROLE_DPS_BF_R, ROLE_DPS_BF_C, ROLE_DPS_BF_A, ROLE_DPS_BF_D, ROLE_DPS_BF_U, ROLE_DPS_SO_R, ROLE_DPS_SO_C, ROLE_DPS_SO_U, ROLE_DPS_SO_A, ROLE_DPS_SO_D]
        BANK_ASSISTANT = [ROLE_METRICS, ROLE_PAYMENT_EXPORT, ROLE_PAYMENT, ROLE_DPS_P_R, ROLE_DPS_AS_R, ROLE_DPS_GP_R, ROLE_DPS_PE_R, ROLE_DPS_BF_R, ROLE_DPS_SO_R]
      },
      BANK_ENTITY_2 {
        CSM_BANK_OPERATOR = [ROLE_DPS_P_R, ROLE_DPS_AS_R, ROLE_DPS_AS_C, ROLE_DPS_AS_A, ROLE_DPS_AS_U, ROLE_DPS_AS_D, ROLE_DPS_GP_R, ROLE_DPS_GP_C, ROLE_DPS_GP_A, ROLE_DPS_GP_U, ROLE_DPS_GP_D, ROLE_DPS_PE_R, ROLE_DPS_PE_C, ROLE_DPS_PE_A, ROLE_DPS_PE_D, ROLE_DPS_PE_U, ROLE_DPS_BF_R, ROLE_DPS_BF_C, ROLE_DPS_BF_A, ROLE_DPS_BF_D, ROLE_DPS_BF_U, ROLE_DPS_SO_R, ROLE_DPS_SO_C, ROLE_DPS_SO_U, ROLE_DPS_SO_A, ROLE_DPS_SO_D]
        PAYMENTS_BANK_OPERATOR = [ROLE_PAYMENT, ROLE_PAYMENT_EXPORT]
        BANK_SUPPORT_OPERATOR = [ROLE_AUDIT, ROLE_METRICS, ROLE_DPS_P_R, ROLE_DPS_AS_R, ROLE_DPS_GP_R, ROLE_DPS_PE_R, ROLE_DPS_BF_R, ROLE_DPS_SO_R]
      }
    }
  }

The most important properties are roles-attributes, ipf-roles and roles-mapping.

roles-attribute refers to the token claim that holds the roles for the user. An attribute name that holds a delimited list of roles. Optional if attribute-to-roles-mappings are already specified.

ipf-roles is a flag which can take 2 properties: true or false. If it is set to true, it will signal the fact that the user has IPF roles (audit, metrics, etc) directly into the token and not bank roles. If it is set to false, it signals the fact that the client has bank roles into the token (roles unknown to the IPF that are present in the roles-mapping). This property helps us parse the roles mapping and assign the correct roles to the user.

roles-mapping represents the mapping between processing entities, bank roles and IPF roles. Each processing entity can contain multiple bank roles and each bank role can contain multiple IPF roles. When granting access, we are parsing the mapping provided by clients and assign the correct roles to the user based on this mapping. If clients use IPF roles in the token, the bank role key needs to be provided, but it will be completely ignored (it can be a random text). This structure must be followed for both cases.

A full list of OAuth configuration properties can be found here: OPS GUI Service Configuration OAuth 2 Properties

SAML 2

If you are using SAML 2, you will need to provide configuration similar to the example below.

  saml2 {
    enabled = false
    verification-certificate = "classpath:idp.crt"
    registration-id = "example-app-id"
    single-sign-on-service-location = "http://example-url/SingleSignOnService.php"
    single-log-out-service-location = "http://example-url/SingleLogoutService.php"
    identity-provider-entity-id = "http://example-url/metadata.php"
    service-provider-entity-id = "http://example-url/service-provider-metadata/"${ipf.business-operations.auth.saml2.registration-id}
    assertion-consumer-service-location = "<override for redirect URL>" //In the case of Gateway rewrite breaking the default for spring which is "{baseUrl}/login/saml2/sso/{registrationId}"
    want-authn-requests-signed = false
    uid-attribute = "uid"
    roles-attribute = "roles"
    roles-separator = ","
    return-url = "/"
    ipf-roles = true
  }

The most important properties are roles-attributes, ipf-roles and roles-mapping.

roles-attribute refers to the token claim that holds the roles for the user. An attribute name that holds a delimited list of roles.

ipf-roles is a flag which can take 2 properties: true or false. If it is set to true, it will signal the fact that the user has IPF roles (audit, metrics, etc) directly into the token and not bank roles. If it is set to false, it signals the fact that the client has bank roles into the token (roles unknown to the IPF that are present in the roles-mapping). This property helps us parse the roles mapping and assign the correct roles to the user.

roles-mapping represents the mapping between processing entities, bank roles and IPF roles. Each processing entity can contain multiple bank roles and each bank role can contain multiple IPF roles. When granting access, we are parsing the mapping provided by clients and assign the correct roles to the user based on this mapping. If clients use IPF roles in the token, the bank role key needs to be provided, but it will be completely ignored (it can be a random text). This structure must be followed for both cases.

A full list of SAML configuration properties can be found here: OPS GUI Service Configuration SAML2 Properties

HTTP

The Strict Transport Security header is configured to apply to all requests and subdomains, ensuring that all traffic is securely served over HTTPS.

The preload directive is enabled, allowing the domain to be added to the HSTS preload list for enhanced security. (Note: This attribute has no effect unless the domain is successfully added to the preload list.)

The max-age attribute of the header can be configured via the hsts-max-age setting:

  • ipf.business-operations.auth.http.hsts-max-age

The hsts-max-age Value Must Be Increased

  • By default, max-age is set to 300 seconds (5 minutes). The recommended minimum is 31536000 seconds (1 year), but it is advisable to increase this value incrementally during deployment.

  • A lower default value provides a grace period for testing. Once a browser enforces HSTS for a domain, it remembers the policy until the max-age expires. Increasing the max-age is simple, but reducing it can be challenging due to browser enforcement.

  • Best practice is to start with a low value, test thoroughly, and gradually increase to a long-term secure value. More information can be found here: hstspreload.org/

JSON Web Token Expiry Date

The duration for how long a token is valid can be configured via setting the jwt.expiry property, starting from the time of the token creation. The default configuration for this property is 1 hour.

The expiry date can be provided in the following units of time:

  • Milliseconds (ms). E.g. 60ms

  • Seconds (s). E.g. 60s

  • Minutes (m). E.g. 60m

  • Hours (h). E.g. 60h

  • Days (d). E.g. 7d There is a set lower and upper limit for expiry duration, which if it is not respected, the application will fail to start up. The minimum duration a token has to be valid for is 1 minute. The maximum duration a token can be valid for is 7 days.

jwt.expiry = 1h
The mentioned property is also used for setting the maxAge property of the cookie.

JSON Web Token Signature Algorithm

The type of signature algorithm used for signing and verifying JWT tokens is configurable. Supported algorithms are:

  • HS512 - Symmetric Algorithm.

  • ES512 - Asymmetric Algorithm.

Signature algorithm can be set via the jwt.signature-algorithm config property.

The default is jwt.signature-algorithm = 'HS512'.

Whichever algorithm you decide to use, precise configuration is vital.

  • For the default HS512 signature to work, jwt.secret has to be overriden.

  • For the ES512 signature to work, jwt.path-private-key and jwt.path-public-key config properties have to be defined pointing to the paths of the pem format key files respectively.

  • Example configuration of ES512

jwt.signatureAlgorithm = "ES512",

jwt.path-private-key = "classpath:keys/private-key.pem",

jwt.path-public-key = "classpath:keys/public-key.pem",