There are a lot of possibly-unfamiliar terms with sometimes-varying meanings in the world of web authentication. Here are the terms as used in Gafaelfawr. The below definitions of terms should be used consistently throughout the documentation and code, including in variable naming and function and method names.
A single key/value pair contained in the payload of a JWT. Represents some fact about either the user represented by the JWT or the JWT itself (such as its issue or expiration date). A collection of multiple claims may be referred to as claims, although payload is preferred if they are intended as the complete contents of a JWT.
- identity provider
Often shortened to “provider,” this is a system that can authenticate a user and provide their identity information to other systems. This may be via the OpenID Connect protocol or (as with GitHub) some other protocol such as OAuth 2.0.
To create a new authentication token, either Gafaelfawr’s own token or a JWT.
An entity that issues JWTs. Each issuer is identified by a unique URI, which goes into the
issclaim of JWTs it issues.
A JSON key set. Roughly the JSON equivalent of a PEM-encoded public key, except that it can hold a broader range of keys. This is how public keys are communicated in the JWT world.
A JSON web token, consisting of a header, a set of claims, and a signature. The set of claims is also called a payload. A JWT is the signed and serialized version; the claims alone without the header and signature are referred to as the payload.
- key ID
Also known as
kid, which is the JSON key for it in a JWKS or in the header of a JWT, this identifies which key of an issuer was used to sign a JWT.
The claims portion of a JWT. Consists of key/value pairs. The value is normally a
strbut may be an
intor a more complex structure.
- protected service
A service that uses Gafaelfawr for authentication and authorization. Gafaelfawr will run as an NGINX auth subrequest handler and return headers that NGINX will in turn pass to the protected service, which it can use for further authorization and identity decisions.
A permission that a user holding a token has in some system. When requesting authentication from an OpenID Connect provider, the requested scopes control what information is returned about the user in the ID token. For a token issued by Gafaelfawr, a scope represents a general class of permissions on systems protected by Gafaelfawr. Services can be protected by authorization rules that require specific scopes.
A stored authentication token for a user that expires after some set length of time. Sessions are stored in an encrypted cookie named
gafaelfawr. The cookie will include a token if the user is authenticated. It may contain other state information for the login process, a CSRF token, or other state used internally by Gafaelfawr. Session cookies are encrypted in a key known only to the Gafaelfawr service, but act as bearer credentials (so must be kept secure from theft by attackers).
The identity of an entity that authenticates with a JWT. Alternately, the identity represented by that JWT. This term is widely used in authentication systems but is not used internally by Gafaelfawr.
There are two types of authentication tokens used by Gafaelfawr. When authenticating the user to an external OpenID Connect service, or when acting as an OpenID Connect service to a protected service, tokens are JWTs. For all other operations, tokens are opaque strings starting with
gt-. These opaque tokens consist of two parts: a key and a secret. The key is the Redis key for the stored session. The secret proves that the client has the right to use that stored session.
A numeric ID for a user, suitable for use as a POSIX UID. Confusingly, LDAP, and thus claims based on LDAP attributes, use
uidto store what is known everywhere else as the username, and use
uidNumberto store the UID. Gafaelfawr always uses UID to refer to the numeric identifier.
A short string identifying a user, suitable for use as a POSIX username. Conventionally this does not include an
@or domain (see the user’s email address for that).
To check the signature and validity of a JWT. This includes retrieving the key used to sign it from its issuer, ensuring that is one of the expected keys if the list of valid keys is restricted, and checking that all the expected claims are present.
Terms to avoid#
Gafaelfawr avoids the following terms.
Except when referring to LDAP or GitHub API results, an attribute doesn’t clearly map to a component of a JWT-based authentication system. The intended term is probably “claim.”
Use “scope” instead.