Skip to main content

The most recent patch for this version is 1.0.2.  Learn more  

JWT Parser configuration

The JSON Web Tokens (JWT) Parser Attribute Connector is a tool that can extract the values of claims in JSON Web Token format. It has the ability to parse and decode the tokens, verify their cryptographic signatures, and extract specific claim values from them. Its configuration is in XML format with the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<configuration
    xmlns="http://www.axiomatics.com/attributeconnector/parser/jwt/configuration"
    identifier="my-jwt-ac-id">
    <source>
      <!-- configuration specifying the JWT source -->
    </source>
    <signature>
        <!-- JWT signature verification configuration -->
    </signature>
    <assertions>
        <!-- checks that must pass, besides signature verification, for the token to be considered valid -->
    </assertions>    
    <mapping>
        <!-- one or more mappings associating values from the JWT source with attributes to be provided by this connector -->
        <xacmlAttribute AttributeId="jwt-subject" 
                        Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject" 
                        DataType="http://www.w3.org/2001/XMLSchema#string"/>
        <claim>sub</claim>
    </mapping>    
</configuration>

A configuration starts with a root element named <configuration> and must contain an identifier and four sections:

  • The identifier is defined using the identifier attribute and must be globally unique, like a UUID. It serves two purposes. First, it helps identify the source of attribute values in host logs. Second, it generates unique identifiers for each attribute mapping within the configuration, used for runtime cache strategy configuration within the host engine.

  • The source section (<source>) specifies the source of the JWT to be processed. It can be:

    • the value of an XACML attribute provided by the connector host

    • the contents of a file present in the environment of the host

    • a literal token value embedded in the configuration

  • The <signature> section configures how token signatures are validated. It specifies the source of the cryptographic key used for verification the signature. Currently, keys can be sourced from either a file within the host's environment or directly embedded within the connector configuration. Optionally, you can configure the JWT Parser to skip signature validation.
  • The <assertions> section configures additional checks on token claims for validity. These checks may include verifying that the token is not expired, it hasn't been activated prematurely, it was issued by a specific authority, or that it is intended for a specific audience.
  • The mapping section contains multiple <mapping> elements, each associating an XACML attribute with a JWT claim. These mappings define the attributes the connector can provide to the host.

Source section​

The source section is mandatory in every configuration and specifies the source of the JWT value to be processed. The sources can be:

  • The value of an XACML attribute

    The value is dynamically provided by the connector host for each policy evaluation. For example:

    <source>
      <xacmlAttribute AttributeId="pip.payload" 
                      Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject" 
                      DataType="http://www.w3.org/2001/XMLSchema#string"/>
    </source>

  • The contents of a file within the environment of the connector host

    The value will be read from the file during connector configuration time only, and will remain the same across all policy evaluations during lifetime of the connector instance. For example:

    <source>
      <token src="/secret/global-static-claims.txt"/>
    </source>

  • A literal token value embedded in the configuration

    The value is embedded within the configuration and remains constant for all policy evaluations during the connector's lifetime. For example:

    <source>
      <token>
          eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJuYW1lIjoiTWF2ZXJpY2UifQ.Ygyk5kKTaGGsiogtXi4Y58yRK38Jes3BsikbJ3sxtrSyozmBcZ72-5P2OLDccc4vTLumM4u1phHAMLWjl9wCkgPkc_4dPPokigkMTp3zRsF7Mbage23D13idTc55O9gSy1xKWiMaa4w1OHzseYEg2I1SWvmJAvTiYfnX_RZQYMaPBN5NXeSpfDkpH_8Rp2hcVP8AgL0HncHBP6t8IxkMR_FTmRYIXEzAWiku6NQdFBXmdFjPZeExx7G96_bDbIh_JDqQED9f2vxw1UtajhNuelUfUaFT1RohJgZ8vZtWIS0u1dJk-ydhRZAz-2WU53C71R0qBHswVRm13EdaFaObgA
      </token>
    </source>
    Important

    The token must not be broken into multiple lines.

Signature section​

The signature section configures how token signatures are validated and specifies the source of a cryptographic key used for verification.

Currently, cryptographic keys can be sourced from:

  • The contents of a file within the environment of the connector host

    The cryptographic key is read from a file during configuration and remains constant for all policy evaluations during the connector's lifetime. For example:

    <signature>
      <signatureKey src="/secret/jwk.json"/>
    </signature>

  • A literal key embedded in the configuration

    The cryptographic key in JWK or PEM format is embedded within the configuration and remains constant for all policy evaluations during the connector's lifetime. For example:

    JWK format

    <signature>
      <signatureKey>
        {
          "kty": "RSA",
          "n": "6S7asUuzq5Q_3U9rbs-PkDVIdjgmtgWreG5qWPsC9xXZKiMV1AiV9LXyqQsAYpCqEDM3XbfmZqGb48yLhb_XqZaKgSYaC_h2DjM7lgrIQAp9902Rr8fUmLN2ivr5tnLxUUOnMOc2SQtr9dgzTONYW5Zu3PwyvAWk5D6ueIUhLtYzpcB-etoNdL3Ir2746KIy_VUsDwAM7dhrqSK8U2xFCGlau4ikOTtvzDownAMHMrfE7q1B6WZQDAQlBmxRQsyKln5DIsKv6xauNsHRgBAKctUxZG8M4QJIx3S6Aughd3RZC4Ca5Ae9fd8L8mlNYBCrQhOZ7dS0f4at4arlLcajtw",
          "e": "AQAB",
          "kid": "test-rsa"
          }
      </signatureKey>
    </signature>

    PEM format

    <signature>
      <signatureKey>
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAERqVXn+o+6zEOpWEsGw5CsB+wd8zO
        jxu0uASGpiGP+wYfcc1unyMxcStbDzUjRuObY8DalaCJ9/J6UrkQkZBtZw==
        -----END PUBLIC KEY-----
      </signatureKey>
    </signature>

Additionally, the connector also supports accepting unsecured tokens for development and testing purposes only. These tokens lack a digital signature and have a signature algorithm (alg) value set to none, making them unsuitable for secure production environments. Learn more in the JSON Web Signature (JWS)Opens in a new tab specification. Furthermore, you can also configure the connector to skip signature validation completely.

note

Unsecured tokens are rejected by default, unless explicitly enabled.

The following examples show how to configure the connector to accept:

  • both signed and unsecured tokens

    <signature allowUnsecured="true">
      <signatureKey>
        {"kty":"oct","k":"NTk2MjhFNUNBNjk1RDc4NjY3RTZCRUIyQzU5MTdFNkU2NjdBQTA2N0I2QjZCRTg5RUI3MUMwQTZDRjYzNTA0MQ"}
      </signatureKey>
    </signature>

  • only unsecured tokens

    <signature allowUnsecured="true"/>

  • all signatures by skipping signature validation

    <signature allowAny="true"/>

Assertions section​

The assertions section configures additional checks on token claims to verify their validity. Currently, the following assertions are available:

Each assertion targets a specific claim. If the corresponding claim is missing, the token is considered invalid. Mark an assertion as optional if you want it checked only when its corresponding claim is present, and ignored otherwise.

Time assertion (expiration)​

This example demonstrates how to require a non-expired token.

<assertions>
  <notExpired/>
</assertions>

The following example demonstrates how to require a non-expired token, but only when an expiration time claim is present:

<assertions>
  <notExpired optional="true"/>
</assertions>

When validating token expiration, it's common practice to account for potential time differences between servers, known as "clock drift." This tolerance is called the "allowed clock skew," which can be configured. The default is 30 seconds.

For example, to require a token to be unexpired while allowing a 5-second clock skew, you would use the following configuration:

<assertions>
  <notExpired skewInSeconds="5"/>
</assertions>

Time assertion (not-before)​

The following example shows how to specify that the token must not be accepted if the current time is before its "not-before" time:

<assertions>
  <notBefore/>
</assertions>

The "not-before" assertion can also be made optional and it can specify a custom clock skew:

<assertions>
  <notBefore optional="true" skewInSeconds="10"/>
</assertions>

Issuer assertion​

This example demonstrates how to require a token issued by a trusted issuer:

<assertions>
  <issuer value="trusted-iss"/>
</assertions>

There can be more than one trusted issuer:

<assertions>
  <issuer value="trusted-iss">
    <value>another-trusted-iss</value>
    <value>yet-another-trusted-iss</value>
  </issuer>
</assertions>

If multiple issuers are trusted, the value element becomes unnecessary. The previous example can change to:

<assertions>
  <issuer>
    <value>trusted-iss</value>
    <value>another-trusted-iss</value>
    <value>yet-another-trusted-iss</value>
  </issuer>
</assertions>

Audience assertion​

The following example shows how to specify that the token must be issued for a specific audience:

<assertions>
  <audience value="accepted-aud"/>
</assertions>

There can be more than one accepted audience:

<assertions>
  <audience value="accepted-aud">
    <value>another-accepted-aud</value>
    <value>yet-another-accepted-aud</value>
  </audience>
</assertions>

If multiple audiences are accepted, the value element becomes unnecessary. The previous example can change to:

<assertions>
  <audience>
    <value>accepted-aud</value>
    <value>another-accepted-aud</value>
    <value>yet-another-accepted-aud</value>
  </audience>
</assertions>

Mappings section​

The mappings section consists of one or more <mapping> elements, each associating an XACML attribute with a JWT claim. This mapping defines the attributes the configured connector can provide to the connector host.

The following example shows a mapping for the sub claim:

<mapping>
  <xacmlAttribute AttributeId="subjectId"
                  Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject"
                  DataType="http://www.w3.org/2001/XMLSchema#string"/>
  <claim>sub</claim>
</mapping>