Configuring JWT authentication

Before you begin

When you configure the Open Liberty application server to use JWT authentication, i2 Analyze detects the setting and issues JWT tokens in cookies to authenticated users. When those users make requests to components like Connector Designer, the client includes the cookie, and the JWT token is used to authenticate the user.

About this task

Open Liberty provides full support for JWT authentication, but in order for i2 Analyze to take advantage, you need to configure it in the server.extensions.xml file. The following procedure describes how to:

• Add the jwt-1.0 feature to i2 Analyze

• Add a trust association interceptor that handles the cookies

• Create a keystore and a truststore for the certificates that sign the JWT tokens

• Configure the JWT builder and JWT consumer that manage the tokens

Procedure

Perform these steps to configure JSON Web Token authentication in your i2 Analyze deployment:

1. If you haven't already done so, stop the Liberty server:

   setup -t stopLiberty

2. Navigate to the configuration\liberty\server.extensions.xml file, and open it in an XML editor.

3. If the file already contains a <featureManager> element, add a new <feature> to it. Otherwise, add one just before the closing </server> element:

   <featureManager>
     <feature>jwt-1.0</feature>
   </featureManager>

   This element enables the jwt-1.0 feature that provides access to JAVA API classes for creating, reading, and verifying JWT tokens.

4. Outside the <featureManager> element, add the trust association interceptor to the server.extensions.xml file:

   <trustAssociation invokeForUnprotectedURI="false"
                     id="JwtTAI" disableLtpaCookie="true">
     <interceptors invokeBeforeSSO="true"
                   className="com.i2group.disco.container.security.internal.JwtTAI"
                   id="JwtTAI" invokeAfterSSO="false" enabled="true">
       <library id="JwtTAILib">
         <fileset dir="${shared.resource.dir}/security/tai"/>
       </library>
     </interceptors>
   </trustAssociation>

5. After the <trustAssociation> element, add definitions of the JWT keystore and truststore to the file:

   <keyStore id="jwtKeyStore" location="<JWT_KEYSTORE_LOCATION>" type="PKCS12" password="<JWT_KEYSTORE_PASSWORD>" />
   <keyStore id="jwtTrustStore" location="<JWT_TRUSTSTORE_LOCATION>" type="PKCS12" password="<JWT_TRUSTSTORE_PASSWORD>" />

   The keystore will contain the private key for signing JWT tokens, while the truststore will contain the public key for verifying JWT tokens.

   For information about creating certificates for development using Java keytool, see Creating keystores, truststores, and certificates for development.

   The certificates that the Java keytool generates are self-signed and they should not be used in production deployments. When you are deploying into production, you must use certificates that are provided and signed by a trusted certificate authority.

6. Finally, add definitions of the JWT builder and consumer to the file:

   <jwtBuilder id="i2-analyze-jwt-claims" audiences="i2-analyze"
               issuer="<i2-analyze-url>" signatureAlgorithm="RS256"
               keyStoreRef="jwtKeyStore" expiresInSeconds="120m" />
   
   <jwtConsumer id="i2-analyze-jwt-claims" audiences="i2-analyze"
                issuer="<i2-analyze-url>" signatureAlgorithm="RS256"
                trustStoreRef="jwtTrustStore" clockSkew="5m" />

   These settings must be the same on all Liberty servers in the i2 Analyze deployment. In particular:

   • The id, audiences, and signatureAlgorithm attributes must be set as above.

   • Set issuer to the URL of the i2 Analyze deployment. For example, https://i2-analyze:9443.

   • Set keyStoreRef and trustStoreRef to the identifiers of the keystore and truststore that you created earlier.

   • i2 suggests the expiresInSeconds and clockSkew values as reasonable starting points.

   For more information about the attributes and their values, see the Open Liberty documentation.

   If you do change the expiresInSeconds setting, bear in mind that smaller values cause users to re-authenticate more frequently, while larger values increase the risk from stolen tokens, which remain valid for longer.

7. Save and close server.extensions.xml, and then redeploy and restart the Liberty server:

   setup -t deployLiberty
   setup -t startLiberty