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:
{
"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:
Enable the Bundle
If you use Symfony Flex, it enables the bundle automatically. Otherwise, to enable the bundle add the following code:
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 thetoken.ttl
registration parameter explicitly.issuer
(required) — theiss
JWT claim value, unless another value is explicitly specified in the payload.
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:alg
(required) — a key encryption algorithm according RFC 7518: 4. Cryptographic Algorithms for Key Management .enc
(required) — a content encryption algorithm according RFC 7518: 5. Cryptographic Algorithms for Content Encryption .zip
(optional) — a JWE compression algorithm according RFC 7518: 7.3. JSON Web Encryption Compression Algorithms Registry .jwk
(required) — a JSON data structure which represent a recipient public JWK according RFC 7518: 6. Cryptographic Algorithms for Keys.
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.