Guardian

# Configuration

While Guardian is a library to handle JWT, we introduced some concepts to manipulate tokens more easily.

# Guardian

# Key

A key is composed of an algorithm and its parameters. For example, a key which uses the RS256 algorithm is RSA-based key and has a size expressed on bits.

The following table summarizes the key types, their available algorithms and parameters.

Type Available algorithms Parameters
ECDSA (Elliptic curves) ES256, ES384, ES512 curve
EdDSA (Edward's curve) EdDSA curve
HMAC HS256, HS384, HS512 size in bits
RSA RS256, RS384, RS512, PS256, PS384, PS512 size in bits

TIP

The algorithm suffix number stands for the associated sha version. For example, ES256 means "Elliptic Curve Digital Signature Algorithm SHA-256".

# Key parameter

# ECDSA

The curve parameter has to be in the following list:

  • P-256
  • P-384
  • P-521
# EdDSA

Since the JWT framework used in Guardian only supports the Ed25519 curve, the only available curve is Ed25519.

# HMAC

HMAC-based keys are the fastest but (in theory) the least secure. The key size has to a multiple of 8 bits and has a minimum size:

Algorithm Size (in bits)
HS256 256
HS384 384
HS512 512
# RSA

RSA is probably the most famous algorithm for digital signatures. However, is the slowest of the supported algorithms; thus, we do not recommend to RSA apart from compatibility reasons. The key size has to a multiple of 8 bits and has a minimum size:

Algorithm Size (in bits)
RS256 2048
RS384 3072
RS512 4096
PS256 2048
PS384 3072
PS512 4096

You can define multiple authorities in the config/guardian.php file.

return [
    'defaults'    => [
        // default authority, key and claims set
    ],
    'authorities' => [
        // your authorities declarations
    ],
    'keys'        => [
        'hmac' => [
            'algorithm' => 'HS512',
            'size'      => env('JWT_KEY_SIZE', 512),
            'path'      => storage_path('hmac.json'),
        ],
        'ecdsa' => [
            'algorithm' => 'ES512',
            'curve'     => 'P-521',
            'path'      => storage_path('ecdsa.json')
        ]
    ],
    'claims'      => [
        // your claims sets definitions
    ],
];

In this example, we defined two keys:

  1. hmac, which uses the HS512 algorithm with 512 bits key and is stored in storage/hmac.json.
  2. ecdsa, which uses the ES512 algorithm with P-521 curve and is stored in storage/ecdsa.json.

TIP

If the key file does not exist, Guardian will create it for you.

# Claims

In addition to the information contained in the JWTs generated by Guardian, you can add additional registered claims. They are all optional.

For example, the exp claim controls the validity period of a JWT. To do this, each set of claims is configurable in the config/guardian.php file.

// config/guardian.php
return [
    'defaults'    => [
        // default authority, key and claims set
    ],
    'authorities' => [
        // your authorities declarations
    ],
    'keys' => [
        // your keys declarations
    ],
    'claims'      => [
        'default' => [
            // "iss" (Issuer), see https://tools.ietf.org/html/rfc7519#section-4.1.1
            'iss' => 'Your Issuer',
            // "aud" (Audience), see https://tools.ietf.org/html/rfc7519#section-4.1.3
            'aud' => 'Your Audience',
            // "exp" (Expiration Time), see https://tools.ietf.org/html/rfc7519#section-4.1.4
            'exp' => '+3 months',
            // "nbf" (Not Before), see https://tools.ietf.org/html/rfc7519#section-4.1.5
            'nbf' => 'now',
            // "iat" (Issued At), see https://tools.ietf.org/html/rfc7519#section-4.1.6
            'iat' => 'now',
            // "jti" (JWT ID), see https://tools.ietf.org/html/rfc7519#section-4.1.7
            'jid' => 'uuid',
        ],
    ],
];

# Authority

An Authority is an association between a key and a claims set. Guardian mostly works through authorities.

You can define multiple authorities in the config/guardian.php file.

// config/guardian.php
return [
    'defaults'    => [
        // default authority, key and claims set
    ],
    'authorities' => [
        // the "login" authority will use the key "login-key" and the claims "login-claims"
        'login' => [
            'key'    => 'login-key',
            'claims' => 'login-claims',
        ],
    ],
    'keys' => [
        // your keys declarations
    ],
    'claims'      => [
        // your claims sets definitions
    ],
];

# Default authority, key and claims

Default authority, key and claims are configured in the default configuration entry in the config/guardian.php file.

return [
    'defaults'    => [
        'authority' => 'default-authority',
        'key'       => 'default-key',
        'claims'    => 'default-claims',
    ],
    'authorities' => [
        // your authorities declarations
    ],
    'keys'        => [
        // your keys declarations
    ],
    'claims'      => [
        // your claims sets definitions
    ],
];

# Authentication driver

Guardian exposes a guardian guard driver, which can be used in the config/auth.php. The additional configuration keys provider and authority are required.

// config/auth.php
return [
    'guards' => [
        'your-guard-name' => [
            'driver'    => 'guardian',
            'provider'  => 'eloquent', // or database
            'authority' => 'login',
        ]
    ]    
];