Signing keys

Authway uses public-key cryptography to sign ID tokens, access tokens and SAML assertions, so that an application (client) that uses Authway to authenticate users can trust the result. A signing key is a JSON web key (JWK) that consists of a public and privat key pair. The private key is used by Authway to create a signature that can be verified with the well-known public key.

By default, Authway uses RSA keys for RS256 signing algorithm.

A JSON web key set (JWKS) is a set of keys containing the public keys used to verify the signature in your application. The set can contain one or more public keys:

{
    "keys": [
        {
            "kty": "RSA",
            "use": "sig",
            "kid": "NOT THE REAL VALUE",
            "e": "NOT THE REAL VALUE",
            "n": "NOT THE REAL VALUE",
            "alg": "RS256"
        }
    ]
}

The JWKS can be fetched from the Identity Server at the relative URL .well-known/openid-configuration/jwks, but the preferred way to retrieve the URL for the JWKS is to read the jwks_uri from the metadata document (found at .well-known/openid-configuration). Within the set there can be one or more keys for one or more signing algorithms (if more than one algorithm is configured).

How it works

When a user signs in, Authway typically creates tokens with information about the signed-in user. The tokens are signed with the private key, before they are send to your application. To verify that the the token you retrieve is valid and issued by the Identity Server, your application uses the public key.

It is important that you use the jwks_uri endpoint to get the keys dynamically since the keys can change over time. Of course the keys should be cached, but it is a good practices to refresh the cash once every day.

Note that validation of the signature is only one aspect of validating a JWT and expiration, issued time, audience and issuer are examples of more necessary validation. We recommend the use of platform support for token validation is used since it is a complex and security critical process to do correct.

Key rotation

Key rotation is an Enterprise feature of Authway, but since this can change (both what is included in different price levels, but also what version is used) we strongly recommend each application to implement support for key rotation. The keys can also be changed in the case of a security breach.

It is a good practice to rotate the keys regularly and Authway rotates them every 90 days (by default, but it can be configured). The new key is announced 14 days in advance, and retained for 14 days after it expires. The first key in the list is the default key:

{
    "keys": [
        {
            "kty": "RSA",
            "use": "sig",
            "kid": "NOT THE REAL VALUE",
            "e": "NOT THE REAL VALUE",
            "n": "NOT THE REAL VALUE",
            "alg": "RS256"
        },
        {
            "kty": "RSA",
            "use": "sig",
            "kid": "NOT THE REAL VALUE",
            "e": "NOT THE REAL VALUE",
            "n": "NOT THE REAL VALUE",
            "alg": "RS256"
        }
    ]
}

If the signature couldn’t be verified with the default key, you should try to verify the signature with the other key(s) for the same signing algorithm.

Signing algorithms

By default Authway uses RS256 signing algorithm, but it is possible to configure support for RS, PS and ES family of cryptographic signing algorithms. When multiple algorithms is supported is is possible to override the default on a per resource and client basis.