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" />