Configuring preauthentication

To configure preauthentication

1. Log in to BMC Helix SSO Admin Console.
2. In the left navigation panel of the Add Realm or Edit Realm page, click Authentication.
3. From the Authentication Type list, select PREAUTH.
4. In the User ID Claim Name field, enter the name of the JWT entry to be used for user identification.
   Info

   Because a JWT is generated and provided by a third-party system, the name of the claim containing the User ID is arbitrary. Refer to the documentation of your third-party product to find out the actual JWT claim name containing the User ID value used for integration

5. Select a process to validate JWTs:
   • To use a certificate, in the Certificate field, copy the certificate of the server that signs the JWT. The certificate must be in Privacy Enhanced Mail (PEM) format. 
   • To use a JWKS URI, in the JWKS URI field, copy the set of public keys issued by a trusted third party. The URI must use HTTP or HTTPS protocols; for example, https://login.microsoftonline.com/common/discovery/v2.0/keys 
     Info

     These two options cannot be used simultaneously. If do you need to combine these validation methods, configure an authentication chain with two authentication types: preauthentication with JWKS URI verification and (if the first fails) preauthentication with certificate validation.

6. (Optional) In the Validation expression field, enter the SpEL validation expression, which amplifies the basic check of JWT claims. Use this expression to provide an additional layer of security, specifically when JWT claims are issued by third-party providers. For more details, see the How the test SpEL pattern works section.
7. (Optional) Test the SpEL validation expression with expected JWTs. To do so, as an administrator, navigate to Service > SpEL Test. In the Expression field, enter the expression. In the Value field, enter a test value (JWT). Click Test to confirm that your JWT is valid before BMC Helix SSO creates a session
8. (Optional) To allow an originating application to open a target application through iframe, in the ALLOW-FROM Domain(s) field, enter the name of the originating application. 
9. Specify the target server as follows:
   • * - wildcard. Allowed for all domains.
   • hostname - Allowed for specified domain, ignoring port.
   • hostname:port - Allowed for exact match host:port.
   • proto://hostname:port - Allowed for exact match host:port.
10. Click Save.

How the test SpEL pattern works 

A validation expression is a SpEL expression where #jwt is a keyword that means JWT, which is used for logging in. By using this keyword, you can obtain two objects: header (#jwt.header()) and claims (#jwt.claims()), which are Map<String, Object> Java objects.

For example, you need to validate the following JWT:

The decoded header and payload of this JWT is as follows:

Header

Payload

Let's say that you want to add extra checks for this JWT:

• It has an email claim.
• The email domain is example.com.
• The type of JWT is "JWT".

To implement these conditions, you need to customize the expression as follows:

After you click Test, True is returned, meaning that the expression is valid for the test JWT.

If False, your expression does not correspond to the JWT content and needs to be revisited.