Issue mode

In issue mode, the JWT Module creates a binary security token, which has the attribute type urn:com:ibm:JWT.

When the module creates a JWT, the following operations are performed:

1. The keys are resolved.
2. The claims are populated from the STSUU.
3. The static claims are populated, if they were configured and are not already set from the STSUU.
4. The JWT is signed if signing is set.
5. The JWT is encrypted. If it is signed, the signed JWT will be encrypted and the claim “cty”:”jwt” will be added to the header.
6. The binary security token is issued.

The following table shows the configuration properties.

Configuration property	Description	Can be provided by STSUU Context Attributes
signing.alg	The algorithm with which the JWT is signed.	TRUE
signing.symmetricKey	The symmetric key used to perform signature validation.	TRUE
signing.db	The keystore from which the certificate is sourced.	TRUE
signing.cert	Certificate label from which the public keys are sourced.	TRUE
signing.kid	The Key ID used for signing.	TRUE
encryption.jwksUri	The JWKS URI used for encryption.	TRUE
encryption.kid	The Key ID used for encryption.	TRUE
encryption.alg	The algorithm used by the JWT for key management.	TRUE
encryption.enc	The algorithm used by the JWT for content encryption.	TRUE
encryption.symmetricKey	The symmetric key used for key management.	TRUE
encryption.db	The keystore from which the private key is sourced.	TRUE
encryption.cert	The label of the certificate containing the private key to use for decrypting the encryption key.	TRUE
includeIat	A Boolean value that indicates whether the iat (issued at) claim is generated and included in the JWT. This value does not override an existing iat value if it is already present.	FALSE
iss	The static value with which the iss (issuer) claim is populated.	FALSE
aud	The static value with which the aud (audience) claim is populated.	FALSE
sub	The static value with which the sub (subject) claim is populated.	FALSE
jti	JWT ID, which is a unique identifier for the JWT. A value of 0 disables the claim.	FALSE
exp	Offset for the exp (expiration time) claim. A value of 0 disables the claim.	FALSE
nbf	Offset for the nbf (not before) claim. A value of -1 disables the claim.	FALSE

When the module runs in issue mode, it converts the STSUU into a JWT. The following examples show some sample input STSUU and the corresponding output JWT.

To add custom claims to a JWT header, add a custom context attribute with the type "urn:ibm:JWT:header:claim". This type is not case sensitive.

A snippet of an example attribute in XML is shown as follows:

<stsuuser:ContextAttributes>...
      <stsuuser:Attribute name="typ" type="urn:ibm:JWT:header:claim">
         <stsuuser:Value>JWT</stsuuser:Value>
      </stsuuser:Attribute>...</stsuuser:ContextAttributes>

Input example

<?xml version="1.0"?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:rst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
  xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
  <SOAP-ENV:Body>
      <rst:RequestSecurityToken>
        <wsp:AppliesTo>
          <wsa:EndpointReference>
            <wsa:Address>issue</wsa:Address>
          </wsa:EndpointReference>
        </wsp:AppliesTo>
        <wst:Issuer>
          <wsa:Address>issue</wsa:Address>
        </wst:Issuer>
        <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate
        </wst:RequestType>
        <wst:Base>
          <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">
            <stsuuser:Principal/>
            <stsuuser:AttributeList>
              <stsuuser:Attribute name="name" type="urn:ibm:jwt:claim">
                <stsuuser:Value>john</stsuuser:Value>
              </stsuuser:Attribute>
              <stsuuser:Attribute name="title" type="urn:ibm:jwt:claim">
                <stsuuser:Value>Mr</stsuuser:Value>
              </stsuuser:Attribute>
            </stsuuser:AttributeList>
            <stsuuser:ContextAttributes>

	    <!-- specify a HS256 JWT, with the key "superSecret" -->
              <stsuuser:Attribute name="signing.symmetricKey" type="">
                <stsuuser:Value>superSecret</stsuuser:Value>
              </stsuuser:Attribute>
              <stsuuser:Attribute name="signing.alg" type="">
                <stsuuser:Value>HS256</stsuuser:Value>
              </stsuuser:Attribute>
            </stsuuser:ContextAttributes>
            <stsuuser:AdditionalAttributeStatement id=""/>
          </stsuuser:STSUniversalUser> 
        </wst:Base>

      </rst:RequestSecurityToken>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Output example

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <wst:RequestSecurityTokenResponseCollection xmlns:wst="http://
    docs.oasis-open.org/ws-sx/ws-trust/200512">
      <wst:RequestSecurityTokenResponse xmlns:wsu="http://docs.oasis-open.org/
      wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id=
      "uuid8f2887f-0154-1671-a234-ebb7b0604011">
        <wsp:AppliesTo xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:
        wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
          <wsa:EndpointReference>
            <wsa:Address>issue</wsa:Address>
          </wsa:EndpointReference>
        </wsp:AppliesTo>
        <wst:RequestedSecurityToken>
          <wss:BinarySecurityToken xmlns:wss="http://docs.oasis-open.org/wss
          /2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" wss:EncodingType=
          "http://ibm.com/2004/01/itfim/base64encode" wss:ValueType="urn:com:ibm:JWT">
          eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiam9obiIsInRpdGxlIjoiTXIiLCJleHAiOjE0NjA0Mz
          kxNzN9.BNkZM38PygNYbPzGSsd1Za8HmgUkn0aT0ImaJmBmKtU</wss:BinarySecurityToken>
        </wst:RequestedSecurityToken>
        <wst:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Validate
        </wst:RequestType>
        <wst:Status>
          <wst:Code>http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid
          </wst:Code>
        </wst:Status>
      </wst:RequestSecurityTokenResponse>
    </wst:RequestSecurityTokenResponseCollection>
  </soap:Body>
</soap:Envelope>

Pre populating the JWT JSON

In some instances, a more complex and custom JSON format for the JWT might be necessary. This can be achieved by providing the context attribute “claim_json”. The value of this attribute will be parsed and used when initializing the JSON that will be the claims for the JWT. Any attributes that are present will be added to the JWT.

Attribute example:

<stsuuser:ContextAttributes>
...
   <stsuuser:Attribute name="claim_json" type="">
      <stsuuser:Value>
      { 
      “customObjectAttribute”  : {},
      “customBooleanAttribute” : true,
      “customIntegerAttribute” : 1
      }      </stsuuser:Value>
   </stsuuser:Attribute>
...
</stsuuser:ContextAttributes>

Parent topic: JSON Web Token (JWT)