Checker Manager Factory Services

The Symfony Bundle provides Header and Claim Checker Manager Factory services. These services are available when the web-token/jwt-checker component is installed:

Checker Manager Services

You can create Header and Claim Checker Managers using the bundle configuration.

With the previous configuration, the bundle will create public Header and Claim Checker Managers named jose.header_checker.checker1 and jose.claim_checker.checker1 with selected checkers.

Custom Header Or Claim Checker

Some claim or header checkers are provided by this framework, but it is important to create custom checkers that fit on your application requirements.

In the following example, we will assume that the class exist and implement either Jose\Component\Checker\HeaderChecker or Jose\Component\Checker\ClaimChecker.

These checkers will be loaded by the factories and you will be able to create a header or a claim checker manager using the aliases foo or bar.

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the header and claim checker managers.

Key Set Management (JWKSet)

Key Sets As Services

All these methods have the following common option:

• is_public: set the service public or private.

The key set configuration will look like as follow:

jose: # Configuration of the JWT Framework
    key_sets: # Configuration of the keys
        keyset_name: # Unique key name
            method_name: # Name of the method
                ...
                is_public: true

The key set will be available as a container service with the ID jose.key_set.keyset_name where keyset_name is the unique name of your key set. Each key set service will be an instance of the Jose\Component\Core\JWKSet class.

As any other configuration values, you can use environment variables.

From A JWKSet Object

This method will directly get a JWKSet object.

jose:
    key_sets:
        key_name:
            jwkset: # Method
                value: '{"keys":[{"kty":"oct","k":"dzI6nbW4OcNF-AtfxGAmuyz7IpHRudBI0WgGjZWgaRJt6prBn3DARXgUR8NVwKhfL43QBIU2Un3AvCGCHRgY4TbEqhOi8-i98xxmCggNjde4oaW6wkJ2NgM3Ss9SOX9zS3lcVzdCMdum-RwVJ301kbin4UtGztuzJBeg5oVN00MGxjC2xWwyI0tgXVs-zJs5WlafCuGfX1HrVkIf5bvpE0MQCSjdJpSeVao6-RSTYDajZf7T88a2eVjeW31mMAg-jzAWfUrii61T_bYPJFOXW8kkRWoa1InLRdG6bKB9wQs9-VdXZP60Q4Yuj_WZ-lO7qV9AEFrUkkjpaDgZT86w2g"},{"kty":"oct","k":"bwIAv5Nn-fo8p4LCEvM4IR9eLXgzJRs8jXCLb3xR0tDJGiZ46KheO4ip6htFKyN2aqJqlNi9-7hB6I1aLLy1IRT9-vcBoCSGu977cNAUuRLkRp7vo8s6MsxhB8WvQBDRZghV7jIYaune-3vbE7iDU2AESr8BUtorckLoO9uW__fIabaa3hJMMQIHCzYQbJKZvlCRCKWMk2H_zuS4JeDFTvyZH1skJYF_TET1DrCZHMPicw-Yk3_m2P-ilC-yidPPoVzeU8Jj3tQ6gtX3975qiQW7pt2qbgjKAuq2wsz_9hxLBtMB5rQPafFoxop7O4BklvZ9-ECcK6dfI2CAx9_tjQ"}]}'

Distant Key Sets

You can load key sets shared by a distant service (e.g. Google, Microsoft, Okta...). You must install and enable the Httplug Bundle.

When done, you have to create a client and enable the JKU Factory service by indicating the request factory service to use:

httplug: # Example of client configuration
    plugins:
        cache: # We use the cache plugin
            cache_pool: 'cache.app' # We use the PSR-6 Cache service of the application
            config:
                default_ttl: 1800 # TTL set to 30 min
    clients:
        acme:
            factory: 'httplug.factory.guzzle6'
            plugins: ['httplug.plugin.cache'] # We enable the cache plugin for that client.

jose:
    jku_factory:
        enabled: true
        client: 'httplug.client.acme' # The Httplug client
        request_factory: 'httplug.message_factory' # In general, you will use the same message factory as the one used by Httplug

Important recommendations:

• It is highly recommended to use a cache plugin for your HTTP client and thus avoid unnecessary calls to the key set endpoint.

• The connection must be secured and certificate verification should not be disabled.

From A JKU (JWK Url)

The following example will allow you tu load a key set from a distant URI. The key set must be a JWKSet object.

jose:
    key_sets:
        key_name:
            jku: # Method
                url: 'https://login.microsoftonline.com/common/discovery/keys'

From A X5U (X509 Certificates Url)

The following example will allow you tu load a key set from a distant URI. The key set must be a list of X509 certificates.

jose:
    key_sets:
        key_name:
            x5u: # Method
                url: 'https://www.googleapis.com/oauth2/v1/certs'

Shared Ket Sets

It can be interesting to share your key sets through an Url. This can easily achieved by adding a dedicated controller. This controller is automatically created by the bundle.

You must add the following configuration to your routing file.

jwkset_endpoints:
    resource: "@JoseFrameworkBundle/Resources/config/routing/jwkset_controller.yml"

Then you can share your key set.

jose:
    key_sets:
        public_keyset: # The key set we want to share
            jwkset:
                value: '{"keys":[{"kty":"OKP","crv":"X25519","x":"ovuZiVcMXBN4r0VgCvJy_ChAsBv4YPJGC5w56PzndXY"},{"kty":"OKP","crv":"X25519","x":"4qyOJ4T9RkdciIn6LDxb2LdM1Ov-dtBSuj0jh6nCuyc"}]}'
    jwk_uris:
        shared_keyset:
            id: 'jose.key_set.public_keyset' # The key set service to share
            path: '/certs' # Path of the key set. Final path is hostname/route_prefix/path: https://www.foo.com/keys/certs
            max_age: 1000 # Set the HTTP cache max age of this key set

Now went you go to the URL http://128.0.0.1:8000/certs, you will get your key set.

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.

jose:
    key_sets:
        key_name:
            jku: # Method
                url: 'https://login.microsoftonline.com/common/discovery/keys'
                tags:
                    tag_name1: ~
                    tag_name2: {attribute1: 'foo'}

Key Management (JWK)

Keys As Services

When the component is installed, you will be able to define your keys in your application configuration and load your keys from several sources or formats. All these methods have the following option:

• is_public: set the service public or private.

The key configuration will look like as follow:

jose: # Configuration of the JWT Framework
    keys: # Configuration of the keys
        key_name: # Unique key name
            method_name: # Name of the method
                ...
                is_public: true

The key will be available as a container service with the ID jose.key.key_name where key_name is the unique name of your key. Each key service will be an instance of the Jose\Component\Core\JWK class.

As any other configuration values, you can use environment variables.

From A Shared Secret

This feature was introduced in version 1.1.

This method will directly get a shared secret.

jose:
    keys:
        key_name:
            secret: # Method
                secret: 'This is my shared secret'
                additional_values:
                    use: 'sig'
                    alg: 'RS512'

From A JWK Object

This method will directly load a JWK object.

jose:
    keys:
        key_name:
            jwk: # Method
                value: '{"kty":"oct","k":"dzI6nbW4OcNF-AtfxGAmuyz7IpHRudBI0WgGjZWgaRJt6prBn3DARXgUR8NVwKhfL43QBIU2Un3AvCGCHRgY4TbEqhOi8-i98xxmCggNjde4oaW6wkJ2NgM3Ss9SOX9zS3lcVzdCMdum-RwVJ301kbin4UtGztuzJBeg5oVN00MGxjC2xWwyI0tgXVs-zJs5WlafCuGfX1HrVkIf5bvpE0MQCSjdJpSeVao6-RSTYDajZf7T88a2eVjeW31mMAg-jzAWfUrii61T_bYPJFOXW8kkRWoa1InLRdG6bKB9wQs9-VdXZP60Q4Yuj_WZ-lO7qV9AEFrUkkjpaDgZT86w2g"}'

From A X509 Certificate File

This method will load a X509 Certificate file.

jose:
    keys:
        key_name:
            certificate: # Method
                path: '/path/to/your/X509/certificate'
                additional_values: # Optional values
                    use: 'sig'
                    alg: 'RS256'

From A X509 Certificate

This method will load a key from a X509 Certificate.

jose:
    keys:
        key_name:
            x5c: # Method
                value: '-----BEGIN CERTIFICATE----- ....'
                additional_values: # Optional values.
                    use: 'sig'
                    alg: 'RS256'

From A PKCS#1/PKCS#8 Key File

This method will load a key from a PKCS#1 or PKCS#8 key file.

jose:
    keys:
        key_name:
            file: # Method
                path: '/path/to/your/key/file'
                password: 'secret' # Optional. Only if the key is encrypted
                additional_values: # Optional values.
                    use: 'sig'
                    alg: 'RS256'

From A Key In A Key Set

This method will retrieve a key from a JWKSet service.

jose:
    keys:
        key_name:
            jwkset: # Method
                key_set: 'jose.key_set.my_key_set' # JWKSet service
                index: 0 # Use key at index 0

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.

jose:
    jwe:
        key_name:
            jwk: # Method
                value: '{"kty":"oct","k":"dzI6nbW4OcNF-AtfxGAmuyz7IpHRudBI0WgGjZWgaRJt6prBn3DARXgUR8NVwKhfL43QBIU2Un3AvCGCHRgY4TbEqhOi8-i98xxmCggNjde4oaW6wkJ2NgM3Ss9SOX9zS3lcVzdCMdum-RwVJ301kbin4UtGztuzJBeg5oVN00MGxjC2xWwyI0tgXVs-zJs5WlafCuGfX1HrVkIf5bvpE0MQCSjdJpSeVao6-RSTYDajZf7T88a2eVjeW31mMAg-jzAWfUrii61T_bYPJFOXW8kkRWoa1InLRdG6bKB9wQs9-VdXZP60Q4Yuj_WZ-lO7qV9AEFrUkkjpaDgZT86w2g"}'
                tags:
                    tag_name1: ~
                    tag_name2: {attribute1: 'foo'}

The JWK and JWKSet objects are provided by the web-token/jwt-core component. We recommend you to load these objects through environment variables.

With Symfony 3.4 or 4.0+, an environment variables processor is provided:

parameters:
    my_private_key: '%env(jwk:MY_PRIVATE_KEY)%'
    my_public_keyset: '%env(jwkset:MY_PUBLIC_KEYSET)%'

With the previous configuration, the environment variables MY_PRIVATE_KEY and MY_PUBLIC_KEYSET will be processed by Symfony and the container will contain the my_private_key and my_public_keyset with JWK and JWKSet objects respectively.

But it may not be sufficient for your project. You may need to load keys or key sets from other sources (e.g. key file) You may also want to use your keys as a container services you inject to other services.

This behaviour is possible by installing the web-token/jwt-key-mgmt component. To install it, just execute the following command line:

composer require web-token/jwt-key-mgmt

• Key Management (JWK)

• Key Set Management (JWKSet)

Algorithm Manager Factory Service

The Symfony Bundle provides an Algorithm Manager Factory service. The available algorithms depends on the components installed on your application.

<?php

use Jose\Component\Core\AlgorithmManagerFactory;

$algorithmManagerFactory = $container->get(AlgorithmManagerFactory::class);
$algorithmManager = $algorithmManagerFactory->create(['RS256', 'HS512']);

Custom Algorithm

This factory handles all algorithms services tagged with jose.algorithm.

Example:

services:
    Acme\Bundle\Algorithm\FooAlgorihtm:
        tags:
            - {'name': 'jose.algorithm', 'alias': 'FOO'}

Your algorithm will be available through the algorithm manager factory service and the alias FOO.

PBES2-* Algorithms

When installed, the PBES2-* algorithms available throught the algorithm manager factory. They have the default configuration i.e. salt size = 62 bits and count = 4096. If these values does not fit on your needs, you can create a new algorithm service with your own values:

services:
    Jose\Component\Encryption\Algorithm\KeyEncryption\PBES2HS256A128KW:
        arguments:
            - 128   # salt size
            - 10240 # counts
        tags:
            - {'name': 'jose.algorithm', 'alias': 'Ultra-Secured PBES2-HS256+A128KW'}

You can now use your custom alias:

$algorithmManager = $algorithmManagerFactory->create(['Ultra-Secured PBES2-HS256+A128KW']);

JWS Serializer Manager Factory Service

A JWSSerializerManagerFactory is available as a service in your application container:

<?php
use Jose\Component\Signature\JWSSerializerManagerFactory;

$jwsSerializerManagerFactory = $container->get(JWSSerializerManagerFactory::class);

With this factory, you will be able to create the JWSSerializerManager you need:

$jwsSerializerManager = $jwsSerializerManagerFactory->create(['jws_compact']);

You can now use the JWSSerializerManager as explained in the JWS Creation/Loading section.

Available JWS serialization modes are:

• jws_compact

• jws_json_general

• jws_json_flattened

JWS Serializer Manager As Service

There is also another way to create a JWSSerializerManager object: using the bundle configuration.

jose:
    jws:
        serializers:
            serializer1:
                serializers: ['jws_compact']
                is_public: true

With the previous configuration, the bundle will create a public JWS Serializer Manager service named jose.jws_serializer.serializer1 with selected serialization modes.

<?php
$jwsSerializerManager = $container->get('jose.jws_serializer.serializer1');

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.

jose:
    jws:
        serializers:
            serializer1:
                serializers: ['jws_compact']
                tags:
                    tag_name1: ~
                    tag_name2: {attribute1: 'foo'}

This framework provides a Symfony bundle that will help you to use the components within your Symfony application. The bundle is available

• when you just install the bundle (composer require web-token/jwt-bundle)

• when you install the whole framework (composer require web-token/jwt-framework)

If you just install the bundle on an application with Symfony Flex support, then there is nothing to do. Otherwise, you have to register the bundle:

/**
 * {@inheritdoc}
 */
public function registerBundles()
{
    $bundles = [
        ...
        new Jose\Bundle\JoseFramework\JoseFrameworkBundle(),
    ];

    return $bundles;
}

The bundle capabilities will depend on the components installed in your application. The core component is always available.

• Algorithm Management

• Header and Claim Checkers

• Keys and key sets

• Signed tokens

• Encrypted tokens

JWS Builder Factory Service

A JWSBuilderFactory is available as a service in your application container:

<?php
use Jose\Component\Signature\JWSBuilderFactory;

$jwsBuilderFactory = $container->get(JWSBuilderFactory::class);

With this factory, you will be able to create the JWSBuilder you need:

$jwsBuilder = $jwsBuilderFactory->create(['HS256']);

You can now use the JWSBuilder as explained in the JWS Creation section.

JWS Builder As Service

There is also another way to create a JWSBuilder object: using the bundle configuration.

jose:
    jws:
        builders:
            builder1:
                signature_algorithms: ['HS256', 'RS256', 'ES256']
                is_public: true

With the previous configuration, the bundle will create a public JWS Builder service named jose.jws_builder.builder1 with selected signature algorithms.

<?php
$jwsBuilder = $container->get('jose.jws_builder.builder1');

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.

jose:
    jws:
        builders:
            builder1:
                signature_algorithms: ['HS256', 'RS256', 'ES256']
                tags:
                    tag_name1: ~
                    tag_name2: {attribute1: 'foo'}

To use the signed tokens (JWS), you have to install the web-token/jwt-signature component.

composer require web-token/jwt-signature

When this component is installed, signature algorithms are automatically handles by the Algorithm Manager Factory.

• JWS serializers,

• JWS creation,

• JWS verification.

JWS Verifier Factory Service

A JWSVerifierFactory is available as a service in your application container:

With this factory, you will be able to create the JWSVerifier you need:

You can now use the JWSVerifier as explained in the JWS Creation section.

Reminder: it is important to check the token headers. See the checker section of this documentation.

JWS Verifier As Service

There is also another way to create a JWSVerifier object: using the bundle configuration.

With the previous configuration, the bundle will create a public JWS Verifier service named jose.jws_verifier.verifier1 with selected signature algorithms.

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.

JWS Loader Service

This feature was introduced in version 1.1.

You can also create JWSLoader objects as services using the configuration of the bundle.

To use the encrypted tokens (JWE), you have to install the .

When this component is installed, encryption algorithms are automatically handles by the Algorithm Manager Factory.

• ,

• ,

• .

JWE Decrypter Factory Service

A JWEDecrypterFactory is available as a service in your application container:

With this factory, you will be able to create the JWEDecrypter you need:

You can now use the JWEDecrypter as explained in the JWE Creation section.

Reminder: it is important to check the token headers. See the checker section of this documentation.

JWE Decrypter As Service

There is also another way to create a JWEDecrypter object: using the bundle configuration.

With the previous configuration, the bundle will create a public JWE Decrypter service named jose.jwe_decrypter.decrypter1 with selected encryption algorithms.

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.

JWE Loader Service

This feature was introduced in version 1.1.

You can also create JWELoader objects as services using the configuration of the bundle.

JWE Serializer Manager Factory Service

A JWESerializerManagerFactory is available as a service in your application container:

With this factory, you will be able to create the JWESerializerManager you need:

You can now use the JWESerializerManager as explained in the JWE Creation/Loading section.

Available JWE serialization modes are:

• jwe_compact

• jwe_json_general

• jwe_json_flattened

JWE Serializer Manager As Service

There is also another way to create a JWESerializerManager object: using the bundle configuration.

With the previous configuration, the bundle will create a public JWE Serializer Manager service named jose.jwe_serializer.serializer1 with selected serialization modes.

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.

JWE Builder Factory Service

A JWEBuilderFactory is available as a service in your application container:

With this factory, you will be able to create the JWEBuilder you need:

Available compression methods are:

• DEF: deflate (recommended)

• GZ: gzip

• ZLIB: zlib

You can now use the JWEBuilder as explained in the JWE Creation section.

JWE Builder As Service

There is also another way to create a JWEBuilder object: using the bundle configuration.

With the previous configuration, the bundle will create a public JWE Builder service named jose.jwe_builder.builder1 with selected encryption algorithms.

Custom Tags

This feature was introduced in version 1.1.

You can add custom tags and attributes to the services you create.

When you want to create keys/key sets, JWS loader/verifier... services, you have to create a dedicated jose section in your configuration. It may confuse your users to configure your bundle and the Jose Framework bundle. Sometimes, you may also want to be sure that the configuration is correctly defined. Lastly, the configuration size increases with numerous details, options or service IDs and it becomes difficult to read or modify.

Hopefully, the Symfony bundle provide a configuration helper: Jose\Bundle\JoseFramework\Helper\ConfigurationHelper. This helper will configure the jose section for you. This helper has to be called in your bundle extension during the prepend step (your extension has to implement Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface).

Let say you want to create a JWK as a service:

For the key configuration, the arguments are:

• The container

• The name of the service (acme_my_key)

• The key type (jwk)

• An array with the expected values

• An array with the custom tags (optional)

Now a key service named jose.key.acme_my_key will be created. This service is public so you will be able to get it from your container or inject it to your services.

This is exactly the same configuration as the following one:

Please note that the tags have been introduced in version 1.1.

Other methods are:

• For the jws section:

  • public static function addJWSBuilder(ContainerBuilder $container, string $name, array $signatureAlgorithms, bool $is_public = true, array $tags = [])

  • public static function addJWSVerifier(ContainerBuilder $container, string $name, array $signatureAlgorithms, bool $is_public = true, array $tags = [])

  • public static function addJWSSerializer(ContainerBuilder $container, string $name, array $serializers, bool $is_public = true, array $tags = [])

• For the jwe section:

  • public static function addJWEBuilder(ContainerBuilder $container, string $name, array $keyEncryptionAlgorithm, array $contentEncryptionAlgorithms, array $compressionMethods = ['DEF'], bool $is_public = true, array $tags = [])

  • public static function addJWEDecrypter(ContainerBuilder $container, string $name, array $keyEncryptionAlgorithm, array $contentEncryptionAlgorithms, array $compressionMethods = ['DEF'], bool $is_public = true, array $tags = [])

  • public static function addJWESerializer(ContainerBuilder $container, string $name, array $serializers, bool $is_public = true, array $tags = [])

• For the checker section:

  • public static function addClaimChecker(ContainerBuilder $container, string $name, array $claimCheckers, bool $is_public = true, array $tags = [])

  • public static function addHeaderChecker(ContainerBuilder $container, string $name, array $headerCheckers, bool $is_public = true, array $tags = [])

• For the keys section:

  • public static function addKey(ContainerBuilder $container, string $name, string $type, array $parameters, array $tags = [])

• For the key_sets section:

  • public static function addKeyset(ContainerBuilder $container, string $name, string $type, array $parameters, array $tags = [])

• For the jwk_uris section:

  • public static function addKeyUri(ContainerBuilder $container, string $name, array $parameters, array $tags = [])