6024 wt2

modules/reference/pages/feature/jwt/examples.adoc

@@ -1,15 +1,61 @@
+
 == Examples
 
-The following example shows how to configure the server to construct a JSON Web Token (JWT) for an application:
+=== Construct JWT for an application
+The following example shows how to configure the server to construct a JSON Web Token (JWT) for an application.
 
 [source, xml]
 ----
 <keyStore id="defaultKeyStore" password="keyspass"/>
 
-<jwtBuilder expiresInSeconds="600" id="myBuilder" issuer="https://example.com" keyAlias="default"/>
+<jwtBuilder id="myBuilder" keyAlias="default" issuer="https://example.com" expiresInSeconds="600"/>
+----
+
+The `id` attribute for the `jwtBuilder` element named `myBuilder` identifies the JWT builder, and uses the default `keyAlias` attribute to locate the private key.
+The `issuer` attribute in the example is the `\http://example.com` URL that identifies who issued the JSON Web Token.
+
+The `expiresInSeconds` attribute indicates the token expiration time, which is 600 seconds.
+
+=== Configure the JWT consumer
+
+When the JSON Web Token feature is enabled, Open Liberty creates a default configuration with the following values.
+
+- The `alg` header of the consumed JWT is RS256. You can configure this value on the `signatureAlgorithm` attribute.
+- A JWT is considered to be valid within 5 minutes of the `exp`, `nbf`, and `iat` claims. You can configure this value on the `clockSkew` attribute.
+
+You can reconfigure these defaults by specifying a `jwtConsumer` element with an `id` value of `defaultJWTConsumer` and configuring attribute values. You can also create one or more other `jwtConsumer` elements. Each `jwtConsumer` element must have a unique, URL-safe string specified as the `id` attribute value. If the `id` value is missing, the `jwtConsumer` is not processed. For more information about the available configuration attributes, see config:jwtConsumer[display=JWT consumer].
+
+For JWT tokens that are signed with RS256 and an X.509 certificate, configure the `trustStoreRef` and `trustAliasName` attributes to locate the signature verification key.
+
+. Import the JWT issuer's X.509 certificate into the truststore. 
+. In the `jwtConsumer` element, specify the truststore ID and the certificate alias.
+
+[source, xml]
+----
+<jwtConsumer id="defaultJWTConsumer" trustStoreRef="truststore_id" trustAliasName="certificate_alias">
+</jwtConsumer>
+----
+
+=== Verify and parse JWT tokens in your application
+The following examples show how to programmatically verify and parse JWT tokens by implementing the `com.ibm.websphere.security.jwt.JwtConsumer` and `com.ibm.websphere.security.jwt.JwtToken` APIs in your application.
+
+. Create a `JwtConsumer` object. If you do not specify a configuration ID, the object is tied to the default `jwtConsumer` configuration.
+
+[source, java]
+----
+com.ibm.websphere.security.jwt.JwtConsumer jwtConsumer = JwtConsumer.create();
+----
+
+If you specify a configuration ID, the object is tied to the `jwtConsumer` configuration with the specified ID.
 
+[source, java]
+----
+com.ibm.websphere.security.jwt.JwtConsumer jwtConsumer = JwtConsumer.create("jwtConsumer_configuration_id");
 ----
 
-The `ID` attribute for the `jwtBuilder` element  named `myBuilder` identifies the JWT builder, and uses the default `keyAlias` attribute to locate the private key.
-The `issuer` attribute in the example is the  URL `http://example.com` that identifies who issued the JSON Web Token.
-The `expiry` attribute indicates the token expiration time, which is 600 seconds.
+2 . Verify and parse a JWT token by implementing the `com.ibm.websphere.security.jwt.JwtToken` API.
+
+[source, java]
+----
+JwtToken jwtToken = jwtConsumer.createJwt("Base64_encoded_JWT_token>");
+----