Skip to content

JWT Bundle

Overview

Implements nbgrp/singlea-tokenization-contracts.

The JWT bundle makes able to generate user token as a JWT. Due to the Spomky's JWT Framework, in addition to mandatory signature, the generated JWT can be also encrypted.

Prerequisites

You need to install the Spomky's JWT Framework (which include JoseFrameworkBundle) before install the SingleA JWT bundle (or simultaneously). This is because the Spomky's bundle, like this one, use dedicated repository for Symfony Flex recipes, and you need to add it in your composer.json or enable the bundle manually.

Installation

Symfony Flex

If you use Symfony Flex, you can add an endpoint for access nb:group's recipes, which makes it possible to apply the default bundle configuration automatically when install the bundle:

composer config --json extra.symfony.endpoint '["https://api.github.com/repos/nbgrp/recipes/contents/index.json", "flex://defaults"]'

If you wish (or you already have some value of the extra.symfony.endpoint option), you can do the same by updating your composer.json directly:

composer.json
{
    "name": "acme/singlea",
    "description": "ACME SingleA",
    "extra": {
        "symfony": {
            "endpoint": [
                "https://api.github.com/repos/nbgrp/recipes/contents/index.json",
                "flex://defaults"
            ]
        }
    }
}

Then you can install the bundle using Composer:

composer require nbgrp/singlea-jwt-bundle

Enable the Bundle

If you use Symfony Flex, it enables the bundle automatically. Otherwise, to enable the bundle add the following code:

config/bundles.php
return [
    // ...
    SingleA\Bundles\Jwt\SingleaJwtBundle::class => ['all' => true],
];

Configuration

The bundle configuration includes the following settings:

  • config_default_ttl (default: 600) — a default JWT lifetime value for new clients who did not specify the token.ttl registration parameter explicitly.
  • issuer (required) — the iss JWT claim value, unless another value is explicitly specified in the payload.
config/packages/singlea_jwt.yaml
singlea_jwt:
    config_default_ttl: 1200
    issuer: 'https://sso.domain.org/'

Client Registration

Request Parameters

The JWT bundle uses token as the name (key) and jwt as the hash value to determine own parameters in client registration request. Besides the hash value, the bundle has the following registration request parameters:

  • ttl (optional) — a JWT lifetime in seconds.
  • claims (optional) — a list of user attribute names to be included in the JWT payload (if they exist for the user). If a claim ends with [] (square braces), user attribute named without braces will be included in the JWT payload as an array; if the attribute was not an array, it will be present as a one-element list. If claim does not end with [], the JWT payload will contain a scalar value; if user attribute is an array, only the first element will be included.
  • jws (required) — JWT signature parameters:
    • alg (required) — a signature algorithm which should be used for a JWT sending to the endpoint according RFC 7518 (except "none").
    • bits (optional) — a number of bits for generating an OpenSSL private key (applicable for RSA and octet algorithms).
  • jwe (optional) — JWT encryption parameters:

Tip

You can use a helpful CLI tool from Spomky's JWT Framework for JWK generation.

{
    # ...
    "token": {
        "#": "jwt",
        "ttl": 600,
        "claims": [
            "username",
            "email",
            "role[]"
        ],
        "jws": {
            "alg": "RS256",
            "bits": 512
        },
        "jwe": {
            "alg": "RSA-OAEP-256",
            "enc": "A256GCM",
            "zip": "DEF",
            "jwk": { ... }
        }
    }
}

Output

The JWT bundle adds to the client registration output the public JWK, which can be used further to verify the signature of the user's JWT.

{
    # ...
    "token": {
        "jwk": { ... }
    }
}