About this task
To configure a Liberty server to accept a
JWT token as an authentication token, enable the openidConnectClient-1.0 feature,
set inboundPropagation="required", and configure a truststore and SSL. You can
optionally specify additional JWT configuration, such as user registries, authentication filters,
and claim-to-subject mapping. The configuration for using JWT as an authentication token is similar
to Configuring an OpenID Connect Client in Liberty.
Any trusted party in possession of a JWT token can use that token to get access to the associated
resources in
Liberty. The
Liberty resource server validates the JWT token
and creates the authenticated subject from the JWT token. To be accepted as an authentication token,
the JWT token must contain
iss,
sub, and
exp
claims and be signed with the RS256 or HS256 algorithm. Encrypted JWT is not supported. The
following example shows a decoded JWT
payload:
{
"iss":"https://idp.acme.com:8020/jwt",
"sub":"marissa@acme.com",
"exp":1385066178,
"aud":"https://resource.acme.com/services",
"iat":1385062578,
“groupIds”: [
“group1”, “group2”
]
}
- Add the openidConnectClient-1.0
Liberty feature and any other needed features
to the server.xml file. At a minimum, the
openidConnectClient-1.0 feature requires the ssl-1.0 feature. Add
the following element declaration inside the featureManager element in your
server.xml file:
<feature>openidConnectClient-1.0</feature>
<feature>ssl-1.0</feature>
- Configure an openidConnectClient element and set
inboundPropagation="required". For information about other
openidConnectClient attributes, see OpenID Connect Client.
The following sample configuration assumes that the JWT token issuer supports a JSON Web Key
(JWK) and is signed with the RS256 algorithm.
<openidConnectClient id="RS" inboundPropagation="required"
jwkEndpointUrl="https://acme.com/jwtserver/jwk" signatureAlgorithm="RS256"
issuerIdentifier="https://idp.acme.com:8020/jwt" >
</openidConnectClient>
- Configure a truststore to include the JWK endpoint certificate so that the Liberty server can make SSL connections to the
JWK endpoint. Truststores are configured on keyStore elements in the
server.xml file. After you configure SSL to reference this truststore, you can either set the SSL configuration
as the server default SSL configuration, or specify the truststore ID on the sslRef
attribute of the openidConnectClient element.
If the JWT issuer does not support
JWK and the JWT is instead signed with an X.509 certificate, import the issuer's X.509 certificate
into the truststore. In the openidConnectClient element, specify the truststore ID
on the trustStoreRef attribute, and reference the certificate on the
trustAliasName attribute.
If the JWT is signed by using a shared secret key
with the HMAC-SHA256 algorithm, define the shared secret key on the sharedKey or
clientSecret attributes.
For information about truststores or keystores, see Enabling SSL communication in Liberty.
- Configure the issuerIdentifier attribute of the
openidConnectClient element to match the JWT issuer iss
claim.
For example, if the JWT token contains "iss":"https://idp.acme.com:8020/jwt",
set issuerIdentifier="https://idp.acme.com:8020/jwt".
- Optional: Configure a user registry. By default, the verified JWT claims are used to create the caller's authenticated subject
directly, without mapping the JWT to a user, so no user registry is required.
However, if the
mapIdentityToRegistryUser attribute of the openidConnectClient
element is set to true, then a user entry for the appropriate identity must
be returned from the authorization server for authentication and authorization to succeed. For more
information about configuring a user registry, see Configuring a user registry in Liberty.
- Optional: Configure authentication filters as described in Authentication Filters.
If you configure an authentication filter, reference the authentication filter on the
authFilterRef attribute of the openidConnectClient element.
If the openidConnectClient element is not configured with an
authFilterRef attribute, any unauthenticated request attempt is authenticated by
this openidConnectClient element.
- Optional: Configure the Liberty resource server to
work with multiple JWT issuers or authentication proxy servers by configuring multiple
openidConnectClient elements and multiple authentication filters.
Each openidConnectClient element defines one trust relationship with one JWT
issuer or authentication proxy and references one authentication filter.
- Optional: Define rules for mapping JWT claims to authentication subjects.
The
Liberty resource server uses JWT
claims to create authentication subjects, and you can define how to map JWT claims to the subject on
the following
openidConnectClient element attributes:
- userIdentifier
- userUniqueIdentifier
- groupIdentifier
- realmName
- realmIdentifier
If both
realmName and
realmIdentifier are configured,
realmName takes precedence and
realmIdentifier is ignored.
If you do not define claim-to-subject mapping, the following default mapping rules apply:
- The subject (sub) claim is used as the principal name and unique security name
of the user.
- The issuer (iss) claim is the default realm and used as the subject realm. If a
realmName claim is included in the JWT token, the realmName claim
is used as the subject realm instead of the iss claim.
- Optional: Configure a single-sign-on cookie. The Liberty server expects each request
to provide a valid JWT token and does not create or use single-sign-on cookies for authentication.
To create single-sign-on cookies, set authnSessionDisabled="false" on the
openidConnectClient element.
- Optional: Configure the Liberty server to receive
JWT tokens. The web client can use one of the following methods to send JWT tokens in resource
requests to the Liberty resource server. If
the JWT token is sent in the Authorization field or in a form-encoded body
parameter, no additional server configuration is required.
Important: Clients must not use more than one method in each request to transmit the
token. If the headerName attribute is configured, tokens sent in the
Authorization header field or in a form-encoded body parameter are ignored. If the
headerName attribute is not configured, the Authorization header
is searched first, followed by the access_token parameter.
- Configure JWT audiences. To define a list of trusted audiences, configure the audiences attribute on
the openidConnectClient element.
A valid JWT token must satisfy one of the
following conditions:
- If the audiences attribute is configured, the audience (aud)
claim value must be one of the configured audiences. To ignore the audience check, set
audiences to ALL_AUDIENCES.
- If the audiences attribute is not configured, but the JWT token contains an
aud claim that is a valid URL, the resources service URL must have the
aud value as a prefix.
For example, the following audience is valid because the
resource URL begins with the
aud claim value:
- Audience claim:
"aud":"https://<server>:<port>/something"
- Resource URL:
https://<server>:<port>/something/specific
The following audience is not valid because the resource URL does not begin with the
aud claim value.
- Audience claim:
"aud":"https://<server>:<port>/something/specific"
- Resource URL:
https://<server>:<port>/something
- Optional: Programmatically map JWT tokens to subjects by implementing the
com.ibm.wsspi.security.oauth.UserCredentialResolver service programming interface
(SPI).
For information about the interface, see the
com.ibm.wsspi.security.oauth.UserCredentialResolver SPI information in Programming interfaces (Javadoc) or in the Java documentation that is provided with the product
in the ${wlp.install.dir}/dev/spi/ibm/ directory.
Results
You created the minimum configuration that is required to configure a
Liberty server to accept JWT tokens as
authentication tokens.