1 of 13

Advanced Topics

Serialization
Nested Tokens
Custom Algorithm
Signed tokens and
Encrypted tokens and

Nested Tokens

JWT can be signed or encrypted and both. A nested token is a signed token enclosed in an encrypted one. This order is very important: signed then encrypted.

The NestedTokenLoader and NestedTokenBuilder classes will help you to create nested tokens with ease. They are provided by the web-token/jwt-encryption component. However, you must also install the following component to use it:

web-token/jwt-checker
web-token/jwt-signature

Nested Token Loading

To instantiate the NestedTokenLoader, you need a JWSLoader and a JWELoader.

Its use is very straightforward, you just have to call the method load using the token, the encryption and signature key sets.

The last argument ($signature in the following example) will represents the signature index of the verified signature. This is only useful when multiple signature support is used.

Nested Token Building

To instantiate the NestedTokenBuilderder, you will need the following components:

a JWSBuilder,
a JWEBuilder,
a JWESerializerManager

Its use is a bit more complicated than the loading as the nested token may be designed for several recipients or may have several signatures.

As a reminder, if one of the following parameter is set, the compact serialization mode cannot be used:

signature unprotected header,
JWE shared unprotected header,
recipient unprotected header,

Symfony Bundle

Configuration

Hereafter an example of a Symfony application configuration:

This configuration will create two public services:

jose.nested_token_loader.loader_1
jose.nested_token_builder.builder_1

These services can be called from the container (unless private) or injected in your services.

Configuration Helper

As any other services, you can create a nested token loader or builder from another bundle extension. The following bundle extension class will create the same configuration and services as above.

Serialization

The RFC7515 (JWS) and RFC7516 (JWE) introduce several serialization modes.

Compact
JSON Flattened
JSON General

The Compact mode is most know and commonly used as it is compact and URL safe i.e. it is designed for web context. JSON Flattened and General are not URL safe, but provides features that may fit on your application context.

JWS Serialization

To use the JWS serializers, you have to install the jwt-signature component.

JWS Compact

This serialization mode is probably the one you know the most. It it a string composed of three parts encoded in Base64 Url Safe and separated by a dot (.).

The serializer class is Jose\Component\Signature\Serializer\CompactSerializer. The associated name is jws_compact.

Example:

There are some limitations when you use this serialization mode:

Unprotected header not supported.
Unencoded payload must contain characters within the following range of ASCII characters: 0x20-0x2d and 0x2f-0x7e

JWS JSON Flattened

This serialization mode is useful when you need to use the unprotected header. It it a simple JSON object.

The serializer class is Jose\Component\Signature\Serializer\JSONFlattenedSerializer. The associated name is jws_json_flattened.

Example:

JWS JSON General

This serialization mode is similar to the JWS JSON Flattened, but may contain more than one signature. It it a JSON object.

The serializer class is Jose\Component\Signature\Serializer\JSONGeneralSerializer. The associated name is jws_json_general.

Example:

JWS Serializer Manager

The serializer manager can be helpful when your application deals more than one serialization mode.

JWE Serialization

To use the JWE serializers, you have to install the jwt-encryption component.

JWE Compact

This serialization mode is probably the one you know the most. It it a string composed of five parts encoded in Base64 Url Safe and separated by a dot (.).

The serializer class is Jose\Component\Encryption\Serializer\CompactSerializer. The associated name is jwe_compact.

Example:

There are some limitations when you use this serialization mode:

No Additional Authentication Data can be used.
No shared unprotected header or per-recipient header can be used.

JWE JSON Flattened

This serialization mode is useful when you need to use the unprotected header. It it a simple JSON object.

The serializer class is Jose\Component\Encryption\Serializer\JSONFlattenedSerializer. The associated name is jwe_json_flattened.

Example:

JWE JSON General

This serialization mode is similar to the JWE JSON Flattened, but may contain more than one recipient. It it a JSON object.

The serializer class is Jose\Component\Encryption\Serializer\JSONGeneralSerializer. The associated name is jwe_json_general.

Example:

JWE Serializer Manager

The serializer manager can be helpful when your application deals more than one serialization mode.

Custom Algorithm

This framework provides dozens of signature or encryption algorithms. If your application uses a custom algorithm or if another algorithm has been recently approved in the JWT context, it may be interesting to use it with this framework.

Hopefully, this is very easy. In the following example, we will create a class to use the ChaCha20 + Poly 1305 (IETF variant) encryption algorithm as a Key Encryption Algorithm.

Signed tokens and

Unprotected Header

You may want to set data in a token header that are not important for your application (e.g. general information). The integrity protection of the data is therefore not needed at all.

The RFC7515 introduces an unprotected header. This header is supported by this framework.

With the example below, we will create a signed token with some unprotected header parameters:

$jws = $jwsBuilder
    ->create()
    ->withPayload('...')
    ->addSignature($jwk, ['alg' => 'HS256'], ['description' => 'Small description here', 'author' => 'John Doe'])
    ->build();

The variable $jws will be a valid JWS object with one signature and both headers.

Note: when an unprotected header is set, the Compact Serialization mode is not available.

Multiple Signatures

When you need to sign the same payload for several audiences, you may want to do it at once. The JWS Builder supports multiple signatures.

With the example below, we will create three signatures using three different algorithms (and signature keys):

The variable $jws will be a valid JWS object with all computed signatures. Next step is the serialization of these signatures.

Detached Payload

As per the RFC7519,the payload of a JWS may be detached. This framework supports this feature.

JWS Creation

There is not much difference between the creation of a JWS with or without detached payload. The following example comes from the JWS Creation page. There is only one argument that will change during the call of withPayload.

And voilà! When you will serialize this token, the payload will not be present.

JWS Loading

The loading of a signed token with a detached payload is as easy as when the payload is attached. The only difference is that you have to pass the payload to the JWS Verifier when you want to check the signature.

Unencoded Payload

The RFC7797 allows the use of an unencoded payload for the signed tokens. This behaviour is interesting when your tokens have a detached payload and may reduce the token computation.

Please note that when the Compact Serialization mode is used, the characters of the payload must be limited to the following ASCII ranges:

From 0x20 to 0x2d
From 0x2f to 0x7e

This feature is built in the framework and is enabled when the b64 header parameter is set to false. As per the RFC, this header MUST be protected and also listed as a critical (crit) header parameter.

Example:

As a remainder, both b64 and crit parameters MUST be in the protected header.

Encrypted tokens and

Unprotected Headers

As well as the signed tokens, the encrypted tokens also have unprotected header. But with one difference: there are two unprotected headers:

Shared unprotected header applicable to all recipients.
Per-recipient unprotected header.

With the example below, we will create an encrypted token for two recipient and some unprotected header parameters:

The variable $jwe will be a valid JWE object built for two recipients. The unprotected header parameter author is applicable to the whole token while message and description are available only for the first and second recipient respectively.

Note: when an unprotected header is set, the Compact Serialization mode is not available.

Multiple Recipients

When you need to encrypt the same payload for several audiences, you may want to do it at once. The JWE Builder supports multiple recipients.

With the example below, we will create an encrypted token for three different recipients using three different key encryption algorithms.

Important notes:

The content encryption algorithm MUST be the same for all recipients.
The Key Management Modes of the key encryption algorithms MUST be compatible (see table below).

Note: when an unprotected header is set, the Compact Serialization mode is not available.

Key Management Modes

Each Key Encryption Algorithm has its own Key Management Mode.

Key Encryption Algorithms And Associated Key Management Mode.

Compatibility table between Key Management Modes:

Additional Authentication Data (AAD)

The Additional Authenticated Data (AAD) is an input to an Authenticated Encryption operation. The AAD is integrity protected but not encrypted.

Its value can be any string you want that is needed by your application. With the example below, we will add a dummy AAD:

$jwe = $jweBuilder
    ->create()
    ->withPayload('...')
    ->withSharedProtectedHeader([
        'enc' => 'A256CBC-HS512',
        'alg' => 'RSA-OAEP-256',
        'zip' => 'DEF',
    ])
    ->addRecipient($recipient_key)
    ->withAAD('A,B,C,D')
    ->build();

Note: when the AAD is set, the Compact Serialization mode is not available.

Serialization

The RFC7515 (JWS) and RFC7516 (JWE) introduce several serialization modes.

Compact
JSON Flattened
JSON General

JWS Serialization

To use the JWS serializers, you have to install the jwt-signature component.

JWS Compact

This serialization mode is probably the one you know the most. It it a string composed of three parts encoded in Base64 Url Safe and separated by a dot (.).

The serializer class is Jose\Component\Signature\Serializer\CompactSerializer. The associated name is jws_compact.

Example:

There are some limitations when you use this serialization mode:

Unprotected header not supported.
Unencoded payload must contain characters within the following range of ASCII characters: 0x20-0x2d and 0x2f-0x7e

JWS JSON Flattened

This serialization mode is useful when you need to use the unprotected header. It it a simple JSON object.

The serializer class is Jose\Component\Signature\Serializer\JSONFlattenedSerializer. The associated name is jws_json_flattened.

Example:

JWS JSON General

This serialization mode is similar to the JWS JSON Flattened, but may contain more than one signature. It it a JSON object.

The serializer class is Jose\Component\Signature\Serializer\JSONGeneralSerializer. The associated name is jws_json_general.

Example:

JWS Serializer Manager

The serializer manager can be helpful when your application deals more than one serialization mode.

JWE Serialization

To use the JWE serializers, you have to install the jwt-encryption component.

JWE Compact

This serialization mode is probably the one you know the most. It it a string composed of five parts encoded in Base64 Url Safe and separated by a dot (.).

The serializer class is Jose\Component\Encryption\Serializer\CompactSerializer. The associated name is jwe_compact.

Example:

There are some limitations when you use this serialization mode:

No Additional Authentication Data can be used.
No shared unprotected header or per-recipient header can be used.

JWE JSON Flattened

This serialization mode is useful when you need to use the unprotected header. It it a simple JSON object.

The serializer class is Jose\Component\Encryption\Serializer\JSONFlattenedSerializer. The associated name is jwe_json_flattened.

Example:

JWE JSON General

This serialization mode is similar to the JWE JSON Flattened, but may contain more than one recipient. It it a JSON object.

The serializer class is Jose\Component\Encryption\Serializer\JSONGeneralSerializer. The associated name is jwe_json_general.

Example:

JWE Serializer Manager

The serializer manager can be helpful when your application deals more than one serialization mode.

Nested Tokens

JWT can be signed or encrypted and both. A nested token is a signed token enclosed in an encrypted one. This order is very important: signed then encrypted.

web-token/jwt-checker
web-token/jwt-signature

Nested Token Loading

To instantiate the NestedTokenLoader, you need a JWSLoader and a JWELoader.

Its use is very straightforward, you just have to call the method load using the token, the encryption and signature key sets.

The last argument ($signature in the following example) will represents the signature index of the verified signature. This is only useful when multiple signature support is used.

Nested Token Building

To instantiate the NestedTokenBuilderder, you will need the following components:

a JWSBuilder,
a JWEBuilder,
a JWESerializerManager

Its use is a bit more complicated than the loading as the nested token may be designed for several recipients or may have several signatures.

As a reminder, if one of the following parameter is set, the compact serialization mode cannot be used:

signature unprotected header,
JWE shared unprotected header,
recipient unprotected header,

Symfony Bundle

Configuration

Hereafter an example of a Symfony application configuration:

This configuration will create two public services:

jose.nested_token_loader.loader_1
jose.nested_token_builder.builder_1

These services can be called from the container (unless private) or injected in your services.

Configuration Helper

As any other services, you can create a nested token loader or builder from another bundle extension. The following bundle extension class will create the same configuration and services as above.

Advanced Topics

Nested Tokens

hashtagNested Token Loading

hashtagNested Token Building

hashtagSymfony Bundle

hashtagConfiguration

hashtagConfiguration Helper

Serialization

hashtagJWS Serialization

hashtagJWS Compact

hashtagJWS JSON Flattened

hashtagJWS JSON General

hashtagJWS Serializer Manager

hashtagJWE Serialization

hashtagJWE Compact

hashtagJWE JSON Flattened

hashtagJWE JSON General

hashtagJWE Serializer Manager

Custom Algorithm

Signed tokens and

Unprotected Header

Multiple Signatures

Detached Payload

hashtagJWS Creation

hashtagJWS Loading

Unencoded Payload

Encrypted tokens and

Unprotected Headers

Multiple Recipients

hashtagKey Management Modes

hashtagKey Encryption Algorithms And Associated Key Management Mode.

hashtagCompatibility table between Key Management Modes:

Additional Authentication Data (AAD)

Signed tokens and

Serialization

hashtagJWS Serialization

hashtagJWS Compact

hashtagJWS JSON Flattened

hashtagJWS JSON General

hashtagJWS Serializer Manager

hashtagJWE Serialization

hashtagJWE Compact

hashtagJWE JSON Flattened

hashtagJWE JSON General

hashtagJWE Serializer Manager

Encrypted tokens and

Custom Algorithm

Additional Authentication Data (AAD)

Unprotected Header

Unencoded Payload

Multiple Signatures

Unprotected Headers

Detached Payload

hashtagJWS Creation

hashtagJWS Loading

Multiple Recipients

hashtagKey Management Modes

hashtagKey Encryption Algorithms And Associated Key Management Mode.

hashtagCompatibility table between Key Management Modes:

Nested Tokens

hashtagNested Token Loading

hashtagNested Token Building

hashtagSymfony Bundle

hashtagConfiguration

hashtagConfiguration Helper

Advanced Topics

Nested Token Loading

Nested Token Building

Symfony Bundle

Configuration

Configuration Helper

JWS Serialization

JWS Compact

JWS JSON Flattened

JWS JSON General

JWS Serializer Manager

JWE Serialization

JWE Compact

JWE JSON Flattened

JWE JSON General

JWE Serializer Manager

JWS Creation

JWS Loading

Key Management Modes

Key Encryption Algorithms And Associated Key Management Mode.

Compatibility table between Key Management Modes:

JWS Serialization

JWS Compact

JWS JSON Flattened

JWS JSON General

JWS Serializer Manager

JWE Serialization

JWE Compact

JWE JSON Flattened

JWE JSON General

JWE Serializer Manager

JWS Creation

JWS Loading

Key Management Modes

Key Encryption Algorithms And Associated Key Management Mode.

Compatibility table between Key Management Modes:

Nested Token Loading

Nested Token Building

Symfony Bundle

Configuration

Configuration Helper