Use case: Identity propagation configuration with JWT

The Airlock IAM supports identity propagation with JSON Web Tokens (JWT). This use case describes a setup using a signed JWT to propagate identity information in a cookie. As target application, it uses the Demo Application example of the demo configuration template.

Prerequisites

For this use case, we make use of the Demo configuration template.

Instruction

  1. In the Config Editor, load the Demo configuration and go to:
    Loginapp >> Applications and Authentication >> a target application >> Identity Propagation
  2. In the Identity Propagation list, select the Generic ID Propagator - REST Identity Propagation plugin. This generic plugin allows us to choose the JWT ticket encoder later on. To open the plugin details, .
  3. Plugin - Generic ID Propagator
    • Configure the following:
    • Select the type of ticket, that should be generated by Airlock IAM. For this use case, choose Ticket String Provider - JWT Ticket String Provider.
    • Ticket String Provider - JWT Ticket String Provider
    • Now it's time to set the way the JWT ticket is sent to our Demo Application. This could be e.g. via a request header or as a cookie. Choose Cookie Ticket Adder.
    • Ticket Adder - Cookie Ticket Adder
  4. To configure how the content of the cookie is determined, click on the Ticket String Provider.
    • Configure the following:
    • Select or add the Airlock IAM Value Providers that should work as the source of information. The list defines the pieces of information (attributes) that are available for identity propagation. To find out what attributes are made available by each Value Provider, check the value providers' documentation in the Config Editor. It also documents the keys and which information is available.
      • Configure the following:
      • -User Identity Map
      • -Roles Provider
      • -Context-Data Map
      Value Providers - User Identity Map_Roles Provider_Context-Data Map
    • Choose and configure Key-Value Pairs. They define the attributes available for the ticket encoder. In particular, they define what pieces of information (made available by the value providers above) are available under what key (or name).
      • Configure the following:
      • -Ticket Key Value - Ticket Key "username"
      • -Ticket Key Value - Ticket Key "roles"
      • -Create a new plugin of type Ticket Key Value and give it the identifier Ticket key "ZIP".
  5. To fill in the details of the new plugins, click on the Ticket Key Value - Ticket Key "ZIP_code".
    • Configure the following:
    • As Ticket Key, enter ZIP.
    • Enter the matching Value Selector – here, it is zipcode.
      When configuring Value Selectors entries, make sure the selector is provided by one of the previously selected Value Providers or configure a new one, as required.
    Ticket Key and Value Selector ZIP
  6. Select JWT Ticket Encoder - REST JWT Ticket Encoder. This will tell Airlock IAM to use the JWT ticket encoder to encode the key-value pairs, provided by the chosen value providers.
  7. Ticket Encoder - REST JWT Ticket Encoder
  8. Click on the JWT Ticket Encoder - REST JWT Ticket Encoder. Note that the values selected above in the Key-Value Pairs are stored as claims in JWTs. As a standardized ticket type, JWT offers a number of claims with predefined names, e.g., sub (for Subject). The standard claims are covered by all properties from Username Ticket Key to Enforce JWT ID.
    The Username Ticket Key selects the value stored in the sub claim of the JTW.
    • Configure the following (examples):
    • Add the value roles to the list Claims Stored As Array. This selects the Key-Value-Pair with key roles and stores it in the JWT as a JSON array. Further above, in the corresponding Key-Value-Pair you defined to select the attribute roles-list from the set of available values. It is provided by value provider Roles Provider.
      Note that roles is a standard JWT claim that should be understood by most target applications. However, the names of the roles are not standardized.
    • Add the value ZIP to the list of Claims Stored As JSON. This selects the Key-Value-Pair with the zip code and stores it in the JWT as JSON attribute.
      Note that ZIP is not a standard JWT claim.
       
    • Claims for JWT tickets
    • In the Security Settings property, keep JWT Ticket HMAC Settings - REST JWT Ticket Signer for a start. This will cause Airlock IAM to sign the JWT using the HMAC HS512 algorithm. The JWT can also be signed and/or encrypted with different cryptographic methods.
      Note that signature verification and decryption must be supported by the target application, otherwise, the JWT will not be readable or verifiable for the application.
    • When using a JWT Ticket RSA Signer Settings or a JWT Ticket EC Signer Settings plugin it is possible to include a key identifier (KID) in the header as specified in RFC 7517.
    • Security settings for JWT claims - Signer HMAC

Further information and links

  • For an external list of JWT claims, see JWT claims.
  • For the JWT specification, see RFC 7519.
  • For JWK (JSON Web Key) specification, see RFC 7517.