Configuration

The following information is required to configure the JWT support:

1. The label of the key that is used to sign the generated JWT. This key must exist within the keyfile that is used for communication with the junctioned servers (defined by either the ‘jct-cert-keyfile’ or ‘webseal-cert-keyfile’ configuration entries). The key identifier field (kid) in the JWT header contains this key label and identifies the key that must be used to verify the JWT.
2. The list of claims (or attributes) to be added to the JWT. The claim can either be a literal string or can be obtained from specified credential attributes. The following standard claims are automatically added to each generated JWT:
   1. nbf (not-before): This attribute is set to the current time, less 120 seconds.
   2. iat (issued-at): This attribute is set to the current time.
   3. exp (expiration-time): This attribute is set to the time at which the token expires, as defined by the lifetime configuration entry.
   4. jti (jwt-id): This attribute is set to a random UUID.
3. The name of the HTTP header that contains the generated JWT.
4. The lifetime of a generated JWT. A new JWT is automatically generated before the current JWT expires. If the lifetime configuration entry is set to 0 the JWT expiry is set to match the current session lifetime.
5. The format of the HTTP header that is added to the request.

An example configuration, for the ‘/app’ junction is:

#                                                                              
# The JWT stanza is used to control the generation of JSON Web Tokens.  It     
# contains the default JWT configuration entries - which are used when the      
# corresponding configuration entry is not present in the junction specific     
# stanza ([jwt:<jct-id>]).  The applies-to configuration entry is used to       
# determine which junctions make use of this stanza.                      
#                                                                                                                                                              
[jwt]

# The label associated with the server key which is used to sign the JWT.  This
# key must exist in the key file which is used to secure junction communication
# (i.e. defined by the jct-cert-keyfile or webseal-cert-keyfile configuration
# entries).
key-label = jwt

# The rules which define which junctions the configuration within this          
# stanza will be applied to.                                                    
#                                                                               
# [+|-]<jct-id>                                                                 
#                                                                               
# where:                                                                        
#     +:        indicates that the configuration will be used by the            
#               junction                                                        
#     -:        indicates that the configuration will not be used by            
#               the junction                                                    
#     <jct-id>: the identifier of the junction, which can also contain          
#               pattern-matching characters (i.e. * ?)                          
#                                                                               
# The junction identifier will be evaluated against each rule in sequence       
# until a match is found.  The corresponding code (+|-) will then be            
# used to determine whether the configuration is applied to the junction.       
# If the junction matches no configured rules the configuration will be         
# used by the junction.                                                         
#                                                                               
# This entry may be repeated multiple times, once for each rule which is to     
# be defined.                                                                   
applies-to = +/app                                                           
applies-to = -*


# A claim which is to be added to the generated JWT. The format for each
# configuration entry is: 
# [text|attr]{.<type>}{.array}::<value>{::<claim-name>}
#
# where:
#
#   text : Used to indicate that literal text is added as a claim.
#   attr : Used to indicate that the claim is obtained from a credential 
#        attribute.
#
#   <type>:
#          The source can be qualified with a 'type' (delimited by a dot). 
#          The valid types include:
#            bool:
#              The value is added as a boolean. 
#            int:
#              The value is added as an integer. 
#            string:
#              The value is added as a string.
#
#          If no type is specified, values are added as strings.
#   array:
#          If specified, the value is added as an array, regardless of how 
#          many values are present. If not specified, any single value 
#          attribute is added as a single element and any multi-valued 
#          attributes as an array.
#
#   <value> : 
#          For text:
#             The value that is added. An array of values can be specified 
#             by surrounding the string with square brackets ([]). A comma 
#             is used to delimit each individual value. The comma can be 
#             escaped with a backslash character if a literal comma is 
#             required in the value.
#          For attr:
#             The name of a credential attribute. The '*' and '?' 
#             pattern-matching characters can be used to match multiple 
#             attributes. Pattern-matching characters are ignored if the 
#             '<claim-name>' is specified.
#
#   <claim-name> : 
#          The name of the claim to be added to the JWT. Nested objects can 
#          be specified, separating the name of each object field with 
#          a . (dot). If the name of a field itself embeds a dot, it must be 
#          escaped with a backslash character (for example \.).
#
# The configuration entry can be specified multiple times, once for each
# claim which should be added to the JWT. Please note that if multiple
# claims are specified care should be taken to ensure that conflicts do
# not occur amongst the various claims. For example, a claim name should not 
# be specified more than once, and care should be taken to ensure
# that a claim value does not conflict with an existing nested claim object.
#
# For example:
#   claim = text::www.ibm.com::iss
#   claim = attr.int::BUSINESS_PHONE_NUMBER::phone.business
#   claim = attr::AZN_CRED_PRINCIPAL_NAME::sub
#   claim = attr.array::AZN_CRED_GROUPS::groupList
#   claim = attr.int.array::postCodes::postCodesList
#   claim = attr::AZN_*
#   claim = text.bool::true::is_jwt

claim = text::https://www.ibm.com::iss
claim = attr::AZN_CRED_PRINCIPAL_NAME::sub
claim = attr.array::AZN_CRED_GROUPS::groups

# Claims that correspond to attributes that are not present in the credential 
# are not added to the JWT. Use this configuration entry to specify that 
# missing attributes are still added as an empty string.
include-empty-claims = false

# The name of the HTTP header which will contain the generated JWT.
hdr-name = jwt

# The format of the HTTP header which will contain the JWT.  The
# ‘%TOKEN%’ string will be substituted with the value of the generated
# token.  
#
# For example: 
#    hdr-format = Bearer %TOKEN%
hdr-format = %TOKEN%

# The length of time, in seconds, that a JWT will remain valid.  A new JWT will
# be automatically created when the current JWT expires.  A value of 0
# indicates that the expiry time will be set to match the expiry time of
# the session.
lifetime = 0

# The length of time, in seconds, by which the expiry time of a JWT
# will be reduced.  This entry is used to make allowances for differences in
# system times and transmission times for the JWT.
renewal-window = 15

#                                                                               
# The JWT stanza is used to control the generation of JSON Web Tokens for the   
# specified junction.  The '{jct-id}' refers to the junction point for a        
# standard junction (include the leading '/'), or the virtual host label for a  
# virtual host junction.                                                        
#                                                                               
                                                                                
[jwt:/app]

# Only add the 'iss' and 'sub' claims to the JWT.
claim = text::https://www.ibm.com::iss
claim = attr::AZN_CRED_PRINCIPAL_NAME::sub