Configuring a JSON Web Token as a Single-Sign-On cookie

With the jwtSso-1.0 feature, you can configure a Liberty server to use a JSON Web Token (JWT) as a Single-Sign-On (SSO) cookie. You can optionally customize the behavior of the feature and change how the JWT is built.

About this task

The JWT SSO cookie is configured by enabling the jwtSso-1.0 feature. When a user is authenticated, Liberty creates a signed JWT as an SSO cookie and returns it to the browser. The browser can then include the JWT cookie in subsequent requests to the Liberty server.

Important: The JWT cookie contains information about the authenticated user and groups. The contents are signed, but not encrypted. To avoid disclosing user and group IDs, use secured (HTTPS) communication with this feature.

The JWT is signed by using the private key of the server with the RS256 signature method and has a lifetime of 120 minutes.

You can customize the JWT SSO cookie. For more information about customizing the JWT cookie, see the jwtSso feature.

Procedure

Add the jwtSso-1.0 feature to the feature manifest.

 
<featureManager>                                                            
<feature>jwtSso-1.0</feature>
...     
</featureManager>

Optional: Customize the behavior of the feature by configuring the jwtSso element in the server.xml file by replacing the sample values in the example with your values.
```
<jwtSso cookieName="myjwt" jwtBuilderRef="myBuilder"/>
```
Optional: Change how the JWT is built by configuring the jwtBuilderRef attribute.
The jwtBuilderRef attribute refers to a jwtBuilder element that must exist in the server configuration. The jwtBuilder configuration controls how the JWT is built. For example, you can configure the expiresInSeconds attribute to change the token expiration time.
```
<jwtBuilder id="myBuilder" expiresInSeconds="1800"/>
```
Change the JWT signing key by editing the keyStoreRef and keyAlias attributes as shown.
```
<jwtBuilder id="myBuilder" keyStoreRef="mykeyStore" 
        keyAlias="myJwtSigner"/>
```
The ability to specify a signing key is important when two or more servers are issuing and sharing JWT cookies. Each server must be able to verify cookies that might originate on a different server.
Change the JWT issuer by specifying the issuer attribute. By default, the issuer is https://<hostname>:<port>/jwt/defaultJwtSso. An example follows:
```
<jwtBuilder id="myBuilder" issuer="http://server.example.com" />
```
For more information about jwtBuilder attributes that you can configure, see JWT Builder.
Optional: Change JWT validation criteria by adding an mpJwt element to the server.xml file.
If the jwtSso feature is present, it automatically uses the mpJwt element. Only one mpJwt element can exist in the server.xml file. The following example uses a jwtBuilder reference to customize creation of the tokens and an mpJwt element to customize validation and consumption of the tokens.
```
<jwtSso includeLtpaCookie="true" jwtBuilderRef="myBuilder">            
<jwtBuilder id="myBuilder" issuer="http://server.example.com" />       
<mpJwt id="myMpJwt" issuer="http://server.example.com"                  
keyName="myJwtSigner"/>
```
For more information about mpJwt attributes that you can configure, see MicroProfile JWT.
Optional: Use the JSON Web Key (JWK) endpoint to validate JWTs.
When Liberty creates JWTs, the issuer signs them. The consumer that uses the issuer's public key later verifies the signature. When you use multiple servers, you must store the issuer public key in the truststore file of the consumer. As a convenient alternative to storing the issuer public key in a truststore file, the key can be retrieved from the issuer's JWK endpoint.

The default JWK endpoint is http(s)://<host>:<port>/jwt/ibm/api/defaultJWT/jwk.
To use a JWK endpoint for consuming JWTs, add the jwksUri attribute to the mpJwt configuration element:
```
<mpJwt id="myMpJwt" jwksUri="https://localhost:19443/jwt/ibm/api/defaultJWT/jwk" />
```
If you specified a different builder, its JWK endpoint is http(s)://<host>:<port>/jwt/ibm/api/(builderId)/jwk. For example, the following jwtSso element has a JWK endpoint of http(s)://<host>:<port>/jwt/ibm/api/myBuilder/jwk.
```
<jwtSso jwtBuilderRef="myBuilder"/> <jwtBuilder id="myBuilder" />
```