This framework needs at least:

• PHP 8.3+,

• Extensions:

  • MBString

  • JSON

Depending on the algorithms you using, other PHP extensions may be required (e.g. OpenSSL, Sodium).

Please note that cypher operation may be really slow, especially RSA functions. It is highly recommended to enable GMP or BCMath.

The JWT Framework is the main package and contains all features and components described in this documentation. It is split in several sub-packages depending on your needs.

• web-token/jwt-library: The library and all its components

• web-token/jwt-bundle: The Symfony bundle

• web-token/jwt-experimental: All experimental features

Signed or Encrypted Tokens are not just the next trendy/popular way to authenticate users. They provide great features but when used incorrectly they can expose your application to major security issues.

Please read the following recommendations carefully.

Algorithms

Algorithm Choice

If all parties are able to protect their keys (e.g. private applications), symmetric algorithms are a good choice as they are faster in general. If you use public clients, you should prefer asymmetric algorithms.

Available Algorithms

This framework provides dozen of signature and encryption algorithms, but you do not need all of them. Most applications only support 1 or 2 algorithms.

You should only use necessary algorithms. For example, HS384 algorithm may be avoided if you already have HS256 and HS512.

Avoid Weak Algorithms

Some algorithms are not recommended as there are known security issues:

• none: this algorithm is not a real algorithm. It should only be used when other security means exist. An encrypted connection is certainly not enough!

• RSA1_5: there are known attacks using this algorithm. If you can avoid its use, then do it.

Keys And Key Sets

Key Size

A small key size is as secured as a password like 123456789. You should use at least 256 bits symmetric keys and at lease 2048 bits RSA keys.

In any case, you MUST use a true random number generator.

Additional Information

It is highly recommended to set the following parameters to your key:

• kid: A unique key ID,

• use: indicates the usage of the key. Either sig (signature/verification) or enc (encryption/decryption).

• alg: the algorithm allowed to be used with this key.

Key Rotation

A key is fine but may be cracked e.g. by bruteforce. Changing your keys after several days or weeks is encouraged.

Token Creation

Header Parameters

Broadly speaking, you should set your header parameter in the protected header. The use of the unprotected header should be limited to specific use cases.

When using encrypted tokens, the claims iss and aud should be duplicated into the header. This will avoid unwanted decryption when tokens are sent to a wrong audience.

Payload And Claims

There is no size constraint for the payload, but when tokens are used in a web context, it should be as small as possible. When used, claims should be limited to the minimum.

Does your application really need to get all the information about a user? For each context, you should choose carefully the claims you want to use.

Token Unique ID

A unique token ID should be set to all tokens you create. The associated claim is jti.

This claim is highly recommended as it can prevent replay attacks.

Time Indicators

The JWT specification introduces several claims to limit the period of validity of the tokens:

• exp: expiration time,

• iat: issuance time,

• nbf: validity point in time.

These claims are not mandatory, but it is recommended to define a period of time for the token validity. When used, the expiration time should be appropriate to its context in your application. A security token with 2 weeks lifetime is something you should avoid.

Issuer And Audience

The claims iss (issuer) and aud (audience) should always be set. When duplicated in the header, their values MUST be identical.

Application Communication

Secured Connection

Unless you use encrypted tokens, you should use a secured connection when transmitting tokens between parties. A secured communication is not only needed when transmitting tokens, but also when you exchange keys and key sets with other applications.

Loading Process

When you receive a token, the following steps should be followed in this order. If one failed, you must reject the whole token.

1. Unserialize the token

2. For each signature/recipient (may be possible when using the Json General Serialization Mode):

   1. Check the complete header (protected and unprotected)

   2. Verify the signature (JWS) or decrypt the token (JWE)

   3. Check the claims in the payload (if any)

Unserialize The Token

You should only use the serialization mode(s) you need. If you intend to use your tokens in a web context, then use only the Compact Serialization. If an error occurred during this process, you should consider the token as invalid.

Check The Header

It is strongly recommended that all header parameters are checked before the cryptographic operations (signature verification or content decryption)

Please note that unknown header parameters must be ignored. If your token is verified, those parameters should not be used.

When used, unprotected header parameters should be handled with care.

Signature Verification / Payload Decryption

Let the component do its job. The most important step for developers is to ensure that the right key/ket set is used.

Check The Claims

This step is only required if the payload contains claims. When present, you should always check the exp, iat, nbf, iss and aud claims. Application specific claims should also always checked.

The whole token should be rejected in case of failure. Unknown claims should be ignored.

Stay Tuned

You should subscribe to security forums of similar websites and have a continuous technological watch. The tokens may be compromised because of malicious attacks on the algorithms, keys or other components related to the JWT (directly or indirectly).

The Security group on Stack Exchange is a good start.

This project is a framework that provides an implementation of:

• JWS JSON Web Signature (RFC 7515),

• JWE JSON Web Encryption (RFC 7516),

• JWK JSON Web Key (RFC 7517).

• JWA JSON Web Algorithms (RFC 7518).

• JWT JSON Web Token (RFC 7519),

• JSON Web Key Thumbprint (RFC 7638).

• Unencoded Payload Option (RFC7797).

It also provides:

• a Symfony bundle

• a standalone console application

Licence

This project is release under MIT licence.

Supported Input Types:

JWS or JWE objects support every input that can be encoded into JSON:

• string, array, integer, float...

• Objects that implement the \JsonSerializable interface such as JWK or JWKSet

The detached payload is supported.

Supported Serialization Modes

Supported Compression Methods

Supported Key Types (JWK)

JWK objects support JSON Web Key Thumbprint (RFC 7638).

Key Sets (JWKSet)

JWKSet is fully supported.

Supported Signature Algorithms

Supported Key Encryption Algorithms

Supported Content Encryption Algorithms

To perform cryptographic operations (signature/verification and encryption/decryption), you will need cryptographic keys.

JWK

A JWK object represents a key. It contains all parameters needed by the algorithm and may also provide information parameters.

This framework is able to create private and public keys easily. It can also generate those keys from external resources such as binary key files or certificates.

JWKSet

The keys can be grouped in key sets. A JWKSet object represents a key set. It can contain as many keys as you need.

Requests for new features, bug fixed and all other ideas to make this framework useful are welcome. If you feel comfortable writing code, you could try to fix or .

Do not forget to .

If you think you have found a security issue, DO NOT open an issue. .

For each cryptographic operation, you will need at least one algorithm and one key.

The algorithm list depends on the cypher operation to be performed (signature or encryption).

These algorithms are managed by an Algorithm Manager. In the following example, we will create an algorithm manager that will handle two algorithms: PS256 and ES512. See or algorithm pages for more information.

Algorithm Manager Factory

Your application may need several algorithm managers for several use cases. For example you application may use JWT for:

• signed events,

• authentication tokens.

To avoid mixing algorithms in one algorithm manager or instantiate several times the same algorithms, this framework provides an Algorithm Manager Factory.

This factory will create algorithm managers on demand. It allows the same algorithm to be instantiated multiple times but with different configuration options.

Each algorithm is identified using an alias.

The first argument of the method add is the alias for the algorithm. It must be unique. In general, this alias corresponds to the algorithm name.

As you can see in the example, we added the algorithm PBES2-HS512+A256KW twice:

• with the default configuration,

• with custom arguments.

Now our algorithm manager factory is ready. We can create several algorithm managers by passing a list of aliases to the method create:

A very large number of signature algorithms is provided by the library. Please refer to this signature algorithm table to know what algorithms are available.

Then, you will find an example to create a signed token here and another example to load and verify incoming tokens.

JSON Web Tokens can be used to transport any kind of data. They are mainly used to transport claims. When you receive a tokens that contains claims, it is important to check the values of these claims.

Claim Checker Manager

In the following example, we will create a manager able to check the aud (Audience), iat (Issued At), nbf (Not Before) and exp (Expiration) claims.

<?php

use Jose\Component\Checker\ClaimCheckerManager;
use Jose\Component\Checker;

$clock = // PSR-20

$claimCheckerManager = new ClaimCheckerManager(
    [
        new Checker\IssuedAtChecker($clock),
        new Checker\NotBeforeChecker($clock),
        new Checker\ExpirationTimeChecker($clock),
        new Checker\AudienceChecker('Audience'),
    ]
);

When instantiated, call the method check to check the claims of a JWT object. This method only accept an associative array. You have to retrieve this array by converting the JWT payload.

$claims = json_decode($jwt->getPayload(), true);
$claimCheckerManager->check($claims);

In some cases, it could be interesting to reject tokens that do not contain some mandatory claims. A list of mandatory claims can be set as second argument. If one of those claims is missing an exception is thrown, even if the claim have not been checked.

In the following example, an exception will be thrown if the iss, sub or aud claim is missing.

$claimCheckerManager->check($claims, ['iss', 'sub', 'aud']);

Custom Claim Checker

Your application may use other claims that you will have to check therefore custom claim checkers have to be created.

In this example, we will create a class that will check the claim foo. The claim accept only a string with the value bar or bat. All claim checker have to implement the interface Jose\Component\Checker\ClaimChecker;

<?php

declare(strict_types=1);

namespace Acme\Checker;

use Jose\Component\Checker\ClaimChecker;
use Jose\Component\Checker\InvalidClaimException;

/**
 * Class FooChecker.
 */
final class FooChecker implements ClaimChecker
{
    /**
     * {@inheritdoc}
     */
    public function checkClaim($value)
    {
        if (!is_string($value)) { // If the value is not a string, then we throw an exception
            throw new InvalidClaimException('The claim "foo" must be a string.', 'foo', $value);
        }
        if (!in_array($value, ['bar', 'bat'])) { // Check if the value is allowed
            throw new InvalidClaimException('The claim "foo" must be "bar" or "bat".', 'foo', $value);
        }
    }

    /**
     * {@inheritdoc}
     */
    public function supportedClaim(): string
    {
        return 'foo'; //The claim to check.
    }
}

All done! Now you can instantiate your class and add it to your Claim Checker Manager.

Replicating Claims as Header Parameters

The RFC7516 section 5.3 allows to replicate some claims in the header. This behaviour is very useful with encrypted tokens as it helps to reject invalid tokens without decryption of the payload.

The Claim Checker Manager cannot check those replicated claims, you have to create a custom header checker. However, to avoid duplicated classes, your claim checker can implement the Jose\Component\Checker\HeaderChecker interface.

Have a look at the IssuedAtChecker or the NotBeforeChecker classes. These checkers can be used for claim and header checks.

Claim Checker Manager Factory

Your application may use JSON Web Tokens in different contexts and thus the meaning of a claim may be different. You will need several Claim Checker Managers with dedicated claim checkers.

This framework provides an Claim Checker Manager Factory. This factory is able to accept as many claim checkers as you need. Each claim checker you add to this factory is associated to an alias. You will then be able to create a claim checker manager using those aliases.

<?php

use Jose\Component\Checker\ClaimCheckerManagerFactory;
use Jose\Component\Checker;

$claimCheckerManagerFactory = new ClaimCheckerManagerFactory();
$claimCheckerManagerFactory->add('iat', new Checker\IssuedAtChecker());
$claimCheckerManagerFactory->add('nbf', new Checker\NotBeforeChecker());
$claimCheckerManagerFactory->add('exp', new Checker\ExpirationTimeChecker());
$claimCheckerManagerFactory->add('aud1', new Checker\AudienceChecker('Audience for service #1'));
$claimCheckerManagerFactory->add('aud2', new Checker\AudienceChecker('Audience for service #2'));

$claimCheckerManager1 = $claimCheckerManagerFactory->create(['iat', 'exp', 'aud2']);
$claimCheckerManager2 = $claimCheckerManagerFactory->create(['aud1', 'exp']);

You can create a JWK object using two static methods:

• new JWK(array $values): creates a JWK using direct values.

• JWK::createFromJson(string $json): creates a JWK using a JSON object.

Hereafter all methods available for a JWK object. The variable $jwk is a valid JWK object.

<?php
// Check if the key has a parameter.
$jwk->has('kty');

// Retrieve the key parameter.
$jwk->get('kty');

// Retrieve all key parameters.
$jwk->all();

// Calculate the thumbprint of the key. Acceptable hash algorithms are those returned by the PHP function "hash_algos".
$jwk->thumbprint('sha256');

// If the key is a private key (RSA, EC, OKP), it can be converted into public:
$public_key = $jwk->toPublic();

// The JWK object can be serialized into JSON
json_encode($jwk);

Generate A New Key

This framework is able to create private and public keys on the fly using the JWKFactory. 4 types of keys are supported:

• Symmetric Key:

  • oct: octet string

• Asymmetric Key:

  • RSA: RSA key pair

  • EC : Elliptic Curve key pair

  • OKP: Octet key pair

Octet String

The following example will show you how to create an oct key.

Additional parameters will be set to limit the scope of this key (e.g. signature/verification only with the HS256 algorithm).

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createOctKey(
    1024, // Size in bits of the key. Should be at least of the same size as the hashing algorithm.
    [
        'alg' => 'HS256', // This key must only be used with the HS256 algorithm
        'use' => 'sig'    // This key is used for signature/verification operations only
    ]
);

If you already have a shared secret, you can use it to create an oct key:

<?php

use Jose\Component\KeyManagement\JWKFactory;

$jwk = JWKFactory::createFromSecret(
    'My Secret Key',       // The shared secret
    [                      // Optional additional members
        'alg' => 'HS256',
        'use' => 'sig'
    ]
);

RSA Key Pair

The following example will show you how to create a RSA key.

The key size must be of 384 bits at least, but nowadays the recommended size is 2048 bits.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$private_key = JWKFactory::createRSAKey(
    4096, // Size in bits of the key. We recommend at least 2048 bits.
    [
        'alg' => 'RSA-OAEP-256', // This key must only be used with the RSA-OAEP-256 algorithm
        'use' => 'enc'    // This key is used for encryption/decryption operations only
    ]);

Elliptic Curve Key Pair

The following example will show you how to create a EC key.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createECKey('P-256');

The supported curves are:

• P-256

• P-384

• P-521 (note that this is 521 and not 512)

Octet Key Pair

The following example will show you how to create a OKP key.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createOKPKey('X25519');

The supported curves are:

• Ed25519 for signature/verification only

• X25519 for encryption/decryption only

None Key

The none key type is a special type used only for the none algorithm.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createNoneKey();

Create Key From External Sources

From Values

In case you already have key values, you can create a key by passing those values as an argument:

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createFromValues([
    'kid' => '71ee230371d19630bc17fb90ccf20ae632ad8cf8',
    'kty' => 'RSA',
    'alg' => 'RS256',
    'use' => 'sig',
    'n' => 'vnMTRCMvsS04M1yaKR112aB8RxOkWHFixZO68wCRlVLxK4ugckXVD_Ebcq-kms1T2XpoWntVfBuX40r2GvcD9UsTFt_MZlgd1xyGwGV6U_tfQUll5mKxCPjr60h83LXKJ_zmLXIqkV8tAoIg78a5VRWoms_0Bn09DKT3-RBWFjk=',
    'e' => 'AQAB',
]);

From A Key File

You can convert a PKCS#1 or PKCS#8 key file into a JWK. The following method supports PEM and DER formats. Encrypted keys are also supported.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createFromKeyFile(
    '/path/to/my/key/file.pem', // The filename
    'Secret',                   // Secret if the key is encrypted, otherwise null
    [
        'use' => 'sig',         // Additional parameters
    ]
);

From A PKCS#12 Certificate

You can convert a PKCS#12 Certificate into a JWK. Encrypted certificates are also supported.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createFromPKCS12CertificateFile(
    '/path/to/my/key/file.p12', // The filename
    'Secret',                   // Secret if the key is encrypted
    [
        'use' => 'sig',         // Additional parameters
    ]
);

From A X.509 Certificate

You can convert a X.509 Certificate into a JWK.

<?php

use Jose\Component\KeyManagement\JWKFactory;

$key = JWKFactory::createFromCertificateFile(
    '/path/to/my/key/file.crt', // The filename
    [
        'use' => 'sig',         // Additional parameters
    ]
);

You can create a JWKSet object using three static methods:

• new JWKSet(array $keys): creates a JWKSet using a list of JWK objects.

• JWKSet::createFromJson(string $json): creates a JWKSet using a JSON object.

• JWKSet::createFromKeyData(array $values): creates a JWKSet using a decoded JSON object.

Hereafter all methods available for a JWKSet object. The variable $jwkset is a valid JWKSet object.

<?php
// Returns all keys
$jwkset->all();

// Check if the key set has the key with the key ID 'KEY ID'.
$jwkset->has('KEY ID');

// Retreive the key with the key ID 'KEY ID'.
$jwkset->get('KEY ID');

// Counts the keys in the key set.
$jwkset->count(); // The method count($jwkset) has the same behaviour.

// Adds a key to the key set.
// /!\ As the JWKSet object is immutable, this method will create a new key set. The previous key set is unchanged.
$newJwkset = $jwkset->with($jwk);

// Removes a key to the key set.
// /!\ As the JWKSet object is immutable, this method will create a new key set. The previous key set is unchanged.
$newJwkset = $jwkset->without('KEY ID');

// Selects a key according to the requirements.
// The first argument is the key usage ("sig" of "enc")
// The second argument is the algorithm to be used (optional)
// The third argument is an associative array this constraints (optional)
$key = $jwkset->selectKey('sig', $algorithm, ['kid' => 'KEY ID']);

// You can iterate on a key set
foreach($jwkset as $kid => $jwk) {
    // Action with the key done here
}

// The JWKSet object can be serialized into JSON
json_encode($jwkset);

When you receive a JWT (JWS or JWE), it is important to check ALL headers parameters BEFORE any other action. In case something went wrong, the token should be rejected.

The header parameters are checked by a Header Checker Manager. This manager can contain several header checkers.

Header Checker Manager

To create a header checker manager, you will need to add header checkers and at least one token type.

In the following example, we want to check the alg header parameter for the signed tokens (JWS) received by our application.

<?php

use Jose\Component\Checker\HeaderCheckerManager;
use Jose\Component\Checker\AlgorithmChecker;
use Jose\Component\Signature\JWSTokenSupport;

$headerCheckerManager = new HeaderCheckerManager(
    [
        new AlgorithmChecker(['HS256']),
        // We want to verify that the header "alg" (algorithm)
        // is present and contains "HS256"
    ],
    [
        new JWSTokenSupport(), // Adds JWS token type support
    ]
);

You can then call the check method.

• The first parameter is the JWT to check,

• The second one is the index of the signature/recipient. It could be ignored if you are not using the Flattened or General JSON Serialization Modes.

$headerCheckerManager->check($jwt, 0);

In some cases, it could be interesting to reject tokens that do not contain some mandatory header parameters. A list of mandatory parameters can be set as third argument. If one of those parameters is missing an exception is thrown, even if that header parameter have not been checked.

In the following example, an exception will be thrown if the alg, enc or crit parameters is missing.

$headerCheckerManager->check($jwt, 0, ['alg', 'enc', 'crit']);

Provided Header Checker Objects

The library provides several header checker classes you can instantiate and use at will. They are all located in the namespace Jose\Component\Checker.

Header Checker Manager Factory

The Header Checker Manager Factory will help you to create as many Header Checker Manager as you want to fit on your application requirements.

<?php

use Jose\Component\Checker\HeaderCheckerManagerFactory;
use Jose\Component\Checker\AlgorithmChecker;
use Jose\Component\Encryption\JWETokenSupport;
use Jose\Component\Signature\JWSTokenSupport;

$headerCheckerManagerFactory = new HeaderCheckerManagerFactory();
$headerCheckerManagerFactory->add('signature_alg', new AlgorithmChecker(['HS256']));
$headerCheckerManagerFactory->add('key_encryption_alg', new AlgorithmChecker(['RSA1_5']));
$headerCheckerManagerFactory->addTokenTypeSupport(new JWSTokenSupport());
$headerCheckerManagerFactory->addTokenTypeSupport(new JWETokenSupport());

$headerCheckerManagerForSignatures = $headerCheckerManagerFactory->create(['signature_alg']);
$headerCheckerManagerForEncryption = $headerCheckerManagerFactory->create(['key_encryption_alg']);

Custom Header Checker

With the previous examples, we will only check the alg (algorithm) header parameter. But your application may use other header parameters e.g. cty, typ...

If you need, you can create you own header checker. It must implement the interface Jose\Component\Checker\HeaderChecker. In the following example, we will check that the protected header parameter custom is an array with value foo or bar.

<?php

namespace Acme\Checker;

use Jose\Component\Checker\HeaderChecker;
use Jose\Component\Checker\InvalidHeaderException;

final class CustomChecker implements HeaderChecker
{
    public function checkHeader($value)
    {
        if (!is_array($value) || !in_array($value, ['foo', 'bar'], true)) {
            throw new InvalidHeaderException('Invalid header "custom".', 'custom', $value);
        }
    }

    // This header parameter name.
    public function supportedHeader(): string
    {
        return 'custom';
    }

    // This method indicates if this parameter must be in the protected header or not.
    public function protectedHeaderOnly(): bool
    {
        return true;
    }
}

A very large number of key and content encryption algorithms is provided by the library. Please refer to to know what algorithms are available.

Then, you will find an and another incoming tokens.

Signed tokens are loaded by a serializer or the serializer manager and verified by the JWSVerifier object. This JWSVerifier object just requires an algorithm manager.

Serializer And Verifier

In the following example, we will try to load a signed token. We will only use the HS256 algorithm.

Now we can deserialize the input we receive and check the signature using our key. We will continue with the data we got in the JWS creation section.

The method verifyWithKey returns a boolean. If true, then your token signature is valid. You can then check the claims (if any) using the claim checker manager.

JWSLoader Object

To avoid duplication of code lines, you can create a JWSLoader object. This object contains a serializer, a verifier and an optional header checker (highly recommended).

In the following example, the JWSLoader object will try to unserialize the token $token, check the header parameters and verify the signature with the key $jwk. The variable $payload corresponds to the detached payload (null by default).

If the verification succeeded, the variable $signature will be set with the signature index and should be in case of multiple signatures. The method returns the JWS object.

In case you use a key set, you can use the method loadAndVerifyWithKeySet.

JWSLoaderFactory Object

This feature was introduced in version 1.1.

The JWSLoaderFactory object is able to create JWSLoader objects on demand. It requires the following factories:

• JWSSerializerManagerFactory

• JWSVerifierFactory

• HeaderCheckerManagerFactory (optional)

This framework comes with several signature algorithms. These algorithms are in the following namespace: Jose\Component\Signature\Algorithm.

Experimental Algorithms

The following signature algorithms are experimental and must not be used in production unless you know what you are doing. They are proposed for testing purpose only.

They are provided throught the package web-token/jwt-experimental.

How To Use

These algorithms have to be used with the . They do not need any arguments.

Example:

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

With Symfony Flex

The bundle is automatically detected when Flex is available.

Without Symfony Flex

If you don't use Symfony Flex, you must register the bundle manually.

Bundle Features

The bundle capabilities will depend on the components installed in your application.

Now that you have an algorithm manager and a key, it is time to create your first signed token.

The computation is done by the JWSBuilder object. This object only requires the algorithm manager.

Now let's create our first JWS object.

Great! If everything is fine you will get a JWS object with one signature. We want to send it to the audience. Before that, it must be serialized.

We will use the compact serialization mode. This is the most common mode as it is URL safe and very compact. Perfect for a use in a web context!

All good! The variable $token now contains a string that should be something like this:

Other serialization modes exist. We will see them in the Advanced Topics section.

We recommend you to load these objects through environment variables. With Symfony, 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.

• 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:
    my.custom.PBES2HS256A128KW.algorithm:
        class: 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']);

Checker Manager Factory Services

The Symfony Bundle provides Header and Claim Checker Manager Factory services.

<?php

use Jose\Component\Checker\HeaderCheckerManagerFactory;
use Jose\Component\Checker\ClaimCheckerManagerFactory;

$headerCheckerManagerFactory = $container->get(HeaderCheckerManagerFactory::class);
$headerCheckerManager = $headerCheckerManagerFactory->create([...]);

$claimCheckerManagerFactory = $container->get(ClaimCheckerManagerFactory::class);
$claimCheckerManager = $claimCheckerManagerFactory->create([...]);

Checker Manager Services

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

jose:
    checkers:
        claims:
            checker1:
                is_public: true
                claims: [...]
        headers:
            checker1:
                is_public: true
                headers: [...]

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.

services
    Acme\Checker\CustomHeaderChecker:
        public: false
        tags:
            - { name: 'jose.checker.header', alias: 'foo' }
    Acme\Checker\CustomClaimChecker:
        public: false
        tags:
            - { name: 'jose.checker.claim', alias: 'bar' }

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

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

jose:
    checkers:
        claims:
            checker1:
                claims: [...]
                tags:
                    tag_name1: ~
                    tag_name2: {attribute1: 'foo'}

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 Symfony Http Client.

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

jose:
    jku_factory:
        enabled: true
        client: 'http_client' # The Symfony Http Client

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 Key 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 can enable these routes by adding the following configuration to your routing file.

# config/routes.yaml
jwkset_endpoints:
    resource: "@JoseFrameworkBundle/Resources/config/routing/jwkset_controller.php"

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

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

Custom Tags

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'}

JWS Serializer Manager Factory Service

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

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

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.

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

Custom Tags

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

JWE Decrypter Factory Service

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

<?php
use Jose\Component\Encryption\JWEDecrypterFactory;

$jweDecrypterFactory = $container->get(JWEDecrypterFactory::class);

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

$jweDecrypter = $jweDecrypterFactory->create(['HS256']);

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

JWE Decrypter As Service

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

jose:
    jwe:
        decrypters:
            decrypter1:
                key_encryption_algorithms: ['A256GCMKW']
                content_encryption_algorithms: ['A256CBC-HS256']
                is_public: true

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

<?php
$jweDecrypter = $container->get('jose.jwe_decrypter.decrypter1');

Custom Tags

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

jose:
    jwe:
        decrypters:
            decrypter1:
                key_encryption_algorithms: ['A256GCMKW']
                content_encryption_algorithms: ['A256CBC-HS256']
                tags:
                    tag_name1: ~
                    tag_name2: {attribute1: 'foo'}

JWE Loader Service

The JWELoaderFactory is available as a public service. You can retrieve it using the container or inject it into your services. It will help you to create JWELoader objects on demand.

<?php
use Jose\Component\Encryption\JWELoaderFactory;

$jweLoaderFactory = $container->get(JWELoaderFactory::class);

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

jose:
    jwe:
        loaders:
            jwe_loader1:
                key_encryption_algorithms: ['A256GCMKW']
                content_encryption_algorithms: ['A256CBC-HS256']
                header_checkers: ['alg', 'enc']
                is_public: true

Or using the ConfigurationHelper.

<?php
use Jose\Bundle\JoseFramework\Helper\ConfigurationHelper;

...
ConfigurationHelper::addJWELoader($container, 'jwe_loader1', ['jwe_compact'], ['A256GCMKW'], ['A256CBC-HS256'], ['alg', 'enc'], true);

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).

<?php

declare(strict_types=1);

namespace AcmeBundle\DependencyInjection;

use Jose\Bundle\JoseFramework\Helper\ConfigurationHelper;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
use Symfony\Component\HttpKernel\DependencyInjection\Extension;

final class AcmeExtension extends Extension implements PrependExtensionInterface
{
    ...

    /**
     * {@inheritdoc}
     */
    public function prepend(ContainerBuilder $container)
    {
        ... // The Helper will be called here
    }
}

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

ConfigurationHelper::addKey(
    $container,
    'acme_my_key',
    'jwk', [
        'value' => '{"kty":"oct","k":"dzI6nbW4OcNF-AtfxGAmuyz7IpHRudBI0WgGjZWgaRJt6prBn3DARXgUR8NVwKhfL43QBIU2Un3AvCGCHRgY4TbEqhOi8-i98xxmCggNjde4oaW6wkJ2NgM3Ss9SOX9zS3lcVzdCMdum-RwVJ301kbin4UtGztuzJBeg5oVN00MGxjC2xWwyI0tgXVs-zJs5WlafCuGfX1HrVkIf5bvpE0MQCSjdJpSeVao6-RSTYDajZf7T88a2eVjeW31mMAg-jzAWfUrii61T_bYPJFOXW8kkRWoa1InLRdG6bKB9wQs9-VdXZP60Q4Yuj_WZ-lO7qV9AEFrUkkjpaDgZT86w2g"}',
        'is_public' => true,
    ],
    [
        'tag_name1' => [],
        'tag_name2' => ['attribute1' => 'foo'],
    ]
);

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:

jose:
    keys:
        acme_my_key:
            jwk:
                value: '{"kty":"oct","k":"dzI6nbW4OcNF-AtfxGAmuyz7IpHRudBI0WgGjZWgaRJt6prBn3DARXgUR8NVwKhfL43QBIU2Un3AvCGCHRgY4TbEqhOi8-i98xxmCggNjde4oaW6wkJ2NgM3Ss9SOX9zS3lcVzdCMdum-RwVJ301kbin4UtGztuzJBeg5oVN00MGxjC2xWwyI0tgXVs-zJs5WlafCuGfX1HrVkIf5bvpE0MQCSjdJpSeVao6-RSTYDajZf7T88a2eVjeW31mMAg-jzAWfUrii61T_bYPJFOXW8kkRWoa1InLRdG6bKB9wQs9-VdXZP60Q4Yuj_WZ-lO7qV9AEFrUkkjpaDgZT86w2g"}'
                is_public: true
                tags:
                    tag_name1: ~
                    tag_name2: {attribute1: 'foo'}

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, bool $is_public = true, array $tags = [])

  • public static function addJWEDecrypter(ContainerBuilder $container, string $name, array $keyEncryptionAlgorithm, array $contentEncryptionAlgorithms, 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 = [])

Have a look at the spomky-labs/lexik-jose-bridge extension to see how we configure the Jose Bundle without dedicated configuration

JWE Serializer Manager Factory Service

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

<?php
use Jose\Component\Encryption\JWESerializerManagerFactory;

$jweSerializerManagerFactory = $container->get(JWESerializerManagerFactory::class);

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

$jweSerializerManager = $jweSerializerManagerFactory->create(['jwe_compact']);

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.

jose:
    jwe:
        serializers:
            serializer1:
                serializers: ['jwe_compact']
                is_public: true

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

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

Custom Tags

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

jose:
    jwe:
        serializers:
            serializer1:
                serializers: ['jwe_compact']
                tags:
                    tag_name1: ~
                    tag_name2: {attribute1: 'foo'}

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

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'}

The project comes with console commands. They are available:

Available Commands

In the following example, we will call commands using ./jose.phar. If you need more information about a command, call the command with the option --help.

You can save the output in a file e.g. when you want to store a key or keyset in your local filesystem.

Key Management Commands

Private Key To Public Key Converter

This command will convert a private key into a public key. It has no effect on shared keys (e.g. oct keys).

Key Analyze

The following command will analyze the key passed as argument and find issues.

PKCS#1 Key Converter

This command will convert a RSA or EC key into PKCS#1 key.

Key Generators

The key generator commands will generate a private or shared key. The following options are available:

• -u or --use: indicates the usage of the key (sig or enc): --use enc. This option is highly recommended.

• -a or --alg: indicates the algorithm to be used with the key: --alg RSA-OAEP-256. This option is highly recommended.

Elliptic Curve Key

This command will generate an Elliptic Curve key (EC). The supported curves are P-256, P-384 and P-521.

RSA Key

This command will generate a RSA key. The key size must be at least 384 bits. Recommended size is 2048 bits or more.

Octet Key

This command will generate a octet key (oct). Recommended size is 128 bits or more.

Octet Key Pair Key

This command will generate a octet key pair key (OKP). Supported curves are X25519 (for encryption only) and Ed25519 (signature only).

None Key

This command will generate a none key. This key type is only used by the none algorithm. Key parameters alg and use are automatically set.

From An Existing Secret

If you already have a secret, you can use it to create an octet key (oct).

In case your secret is binary string, you will have to encode it first (Base64) and indicate it is encoded.

Key Loaders

The key loader commands will loader keys from various sources. The following options are available:

• -u or --use: indicates the usage of the key (sig or enc): --use enc. This option is highly recommended.

• -a or --alg: indicates the algorithm to be used with the key: --alg RSA-OAEP-256. This option is highly recommended.

Convert From PEM/DER Keys

This command can load and convert a DER/PEM key file into a JWK. It supports encrypted keys as well as PKCS#1 and PKCS#8 encodings or public/private keys.

Convert From PKCS#12 Keys

This command can load and convert a PKCS#12 key file into a JWK. It supports encrypted keys.

Convert From A X.509 Certificate

This command can load and convert a X.509 key file into a JWK.

RSA Key Optimization

This command optimizes a RSA key by calculating additional primes (CRT). The following option is available:

RSA keys generated by this framework are already optimized. This command may be needed when you import RSA keys from external sources. The optimization is not mandatory but highly recommended. cryptographic operations are up to 10 times faster.

Key Thumbprint

Keyset Management Commands

Private Keys To Public Keys Converter

This command has the same affect as key:convert:public except that it will convert all keys in the keyset. It has no effect on shared keys (e.g. oct keys).

Key Analyze

This command has the same behaviour as key:analyze except that it will analize all keys in the keyset.

Keyset Generators

The key set generator commands will generate key sets with random keys of the same type.

These commands have the same options as the key generator commands. The only difference is that you have to indicate the number of keys you want in the key set.

Examples:

The result of these commands is a JWKSet object.

Key Set Modification

• keyset:add:key: Add a key into a key set.

• keyset:merge: Merge several key sets into one.

• keyset:rotate: Rotate a key set.

Distant Key Set Loading

• keyset:load:jku: Loads a key set from an url.

• keyset:load:x5u: Loads a key set from an url.

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:

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

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

Installation

To install the application, you just have to download the PHAR file attached to the .

You are free to distribute the file within your project or use it locally (e.g. /usr/local/bin).

To use it, just execute the following line:

Installation

To install the standalone application, you have to clone the repository and install the dependencies. We consider that git and composer are correctly installed.

You will find the standalone console command in the bin folder.