JSON Web Token Single Sign-On1.0
This feature allows the runtime to produce and consume MP-JWT cookies for authentication.
Enabling this feature
To enable the JSON Web Token Single Sign-On 1.0 feature, add the following element declaration into your server.xml
file, inside the featureManager
element:
<feature>jwtSso-1.0</feature>
Examples
With the JSON Web Token Single Sign-On feature, you can configure JSON Web Tokens (JWT) as an authentication mechanism for single-sign-on (SSO) authentication.
When this feature is enabled and a user is authenticated, Open 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 Open Liberty server.
Change the token expiration time
To customize the expiration time of a JWT, configure the jwtBuilder
element, as shown in the following example:
<jwtSso cookieName="myjwt" jwtBuilderRef="myBuilder"/>
<jwtBuilder id="myBuilder" expiresInSeconds="1800"/>
The jwtBuilderRef
attribute refers to the jwtBuilder
element with the myBuilder
ID.
The expiresInSeconds
attribute sets the token expiration time to 1800 seconds for newly generated tokens.
Disable JWT cookies
By default, when a client is authenticated with Open Liberty through the JWT SSO feature, a JWT cookie is created and sent to the HTTP servlet. In the following example, the JWT cookies are disabled by specifying the disableJwtCookie
attribute with a value of true
in the server.xml
file.
<jwtSso id="sample" disableJwtCookie="true" />
You can then use a mechanism other than JWT cookies for authentication.
Configure JWT SSO authentication for a subset of requests
You can configure an authentication filter to specify whether certain requests for protected resources are authenticated with JWT SSO. If the request meets the criteria that are specified in the authentication filter, then the request can authenticate with a JWT to access the protected resource. Conversely, if the request does not meet the criteria that are configured in the JWT SSO authentication filter, then the user is prompted to provide login credentials. If the JSON Web Token Single Sign-On feature is enabled but no authentication filter is configured, all requests that include a JWT cookie are processed by JWT SSO authentication.
<jwtSso cookieName="myjwt" jwtBuilderRef="myBuilder" authFilterRef="myAuthFilter"/>
<authFilter id="myAuthFilter">
<requestUrl id="myRequestUrl" urlPattern="/SimpleServlet" matchType="contains"/>
</authFilter>
In the example, request URLs that contain the /SimpleServlet
pattern are authenticated by using JWT SSO authentication. For more information, see Authentication filters.
Change JWT validation criteria
You can specify the mpJwt
element to configure how incoming JWTs are validated and consumed by the server. Only one mpJwt
element can exist in the server.xml
file. In the following example, the jwtBuilder
element specifies the issuer claim for JWTs that the server creates. The mpJwt
element specifies the issuer claim and key alias for incoming JWTs that the server receives:
<jwtSso includeLtpaCookie="true" jwtBuilderRef="myBuilder">
<jwtBuilder id="myBuilder" issuer="http://server.example.com" />
<mpJwt id="myMpJwt" issuer="http://server.example.com"
keyName="myJwtSigner"/>
Retrieve a JWT issuer public key from a JWK endpoint
The JWTs created by Open Liberty are signed by the issuer and verified by the consumer. The consumer that uses the public key of the issuer later verifies the signature. If you use multiple servers, you must store the public key of the issuer in the truststore
file of the consumer. Alternatively, you can also retrieve the key from the JWK endpoint of the issuer.
The default JWK endpoint is http(s)://<host>:<port>/jwt/ibm/api/defaultJWT/jwk
.
To retrieve the JWT issuer public key from a JWK endpoint, specify the endpoint in the jwksUri
attribute for the mpJwt
element in your sever.xml
file:
<mpJwt id="myMpJwt" jwksUri="https://localhost:19443/jwt/ibm/api/defaultJWT/jwk"/>
If you specify a non-default JWT builder, the JWK endpoint is http(s)://<host>:<port>/jwt/ibm/api/(builderId)/jwk
, where (builderId)
is the value of the id
attribute for the jwtBuilderelement
. In the following example, the configured jwtSso
element results in a JWK endpoint of http(s)://<host>:<port>/jwt/ibm/api/myBuilder/jwk
.
<jwtSso jwtBuilderRef="myBuilder"/> <jwtBuilder id="myBuilder"/>
Stable API packages provided by this feature
org.eclipse.microprofile.auth
org.eclipse.microprofile.jwt