Configuring JSON Web Token authentication for OpenID Connect

You can configure a Liberty server to accept a JSON Web Token (JWT) token as an authentication token from a trusted authentication proxy, a trusted service client, or an OAuth authorization server.

{
	"iss":"https://idp.acme.com:8020/jwt",
	"sub":"marissa@acme.com",
	"exp":1385066178,
	"aud":"https://resource.acme.com/services",
	"iat":1385062578,
	"groupIds": [
	    "group1", "group2"
	 ]
}

1. 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 transportSecurity-1.0 feature. Add the following element declaration inside the featureManager element in your server.xml file:

   <feature>openidConnectClient-1.0</feature>
   <feature>transportSecurity-1.0</feature>

2. 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>

3. 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 clientSecret attribute.

   For information about truststores or keystores, see Enabling SSL communication in Liberty.

4. 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".

5. 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.

6. 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.

7. 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.

8. 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.
9. 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.
10. 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.
    • Send the token in the Authorization request header field.

      GET /resource HTTP/1.1
      Host: server.example.com
      Authorization: Bearer mF_9.B5f-4.1JqM
      

    • Send the token in the request entity-body as a form-encoded body parameter.

      POST /resource HTTP/1.1
      Host: server.example.com
      Content-Type: application/x-www-form-urlencoded
      access_token=mF_9.B5f-4.1JqM
      

    • Send the token on a customized request header field by configuring a trusted header name in Liberty.

      To configure the trusted header name, set headerName="<myJwtHeaderName>" on the openidConnectClient element. For example, if you set headerName="jwt", you can send the token on the jwt header field as shown in the following example:

      GET /resource HTTP/1.1
      Host: server.example.com
      jwt: mF_9.B5f-4.1JqM

11. 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
12. 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 or in the Java documentation that is provided with the product in the ${wlp.install.dir}/dev/spi/ibm/ directory.