Download the PHP package ingenerator/oidc-token-verifier without Composer

oidc-token-verifier is a lightweight PHP validator for OIDC ID Tokens as used in the OpenID Connect protocol.

$> composer require ingenerator/oidc-token-verifier

Usage of OIDC tokens

In the full OpenID Connect specification, the ID Token forms part of a multi-step end-user authorization flow. This is a similar concept to using OAuth to authenticate users based on a third-party auth provider.

However, OIDC Tokens can also be used for lightweight server-to-server authentication. For example, they can be used to authorise HTTP requests from Google Cloud Tasks.

Server-to-Server flows like this do not require the full OpenID Connect protocol. They only require the ability to verify the ID Token itself. The ID Token is a JWT, which is cryptographically signed by the issuer. Authenticating the token involves verifying the signature against the issuer's public keys, which are available from a well-known HTTP endpoint, and then performing some checks on the content of the token itself.

Although there are number of PHP JWT libraries, we have struggled to find any that support the certificate discovery / claim assertion phases of the process. This library fills that gap.

Note that all cryptographic / JWT-level operations are delegated to the firebase/php-jwt package. Also note that at present we only support RSA keys and the RS256 token algorithm.

Usage

You validate a token with the OIDCTokenVerifier. There is also a MockTokenVerifier using the same interface for unit testing purposes.

In the simplest case you would do something like this:

Extra constraints

By default, the library only performs basic JWT validation - signature, expiry time / not before time etc.

For security, additional verification is almost always required. For example, any Google Cloud Platform user can produce a valid JWT signed by https://accounts.google.com so you would usually want to authorize based on both the audience (that the token was created for) and the email (the service account used to create it).

The library provides support for these common constraints out of the box:

You can easily support additional custom constraints e.g. to verify additional custom claims:

If your app handles authorization separately (or for testing purposes) you can use the TokenConstraints::signatureCheckOnly() method to create an empty set of constraints.

Certificate discovery and caching

By default, the library uses the OpenIDDicoveryCertificateProvider to dynamically fetch public certificates for a given issuer. This uses the {issuer}/.well-known/openid-configuration discovery document to find the issuer's JWKS url. Certificates are then fetched from the JWKS url, decoded and cached (in a PSR-6 cache) for subsequent requests.

For obvious reasons, both the discovery document and the JWKS must be served over HTTPS. In development environments e.g. if working against an emulator, you may not have HTTPS available. In this case, pass the allow_insecure => TRUE option to enable fetching certs over HTTP.

The cache lifetime is based on the Expires header of the JWKS response. Note that we do not cache (or pay attention to) the cache headers on the OpenID Discovery Document itself. If an issuer changes their jwks_uri this will not be detected until the JWKS response itself expires.

Occasionally, network / issuer errors might occur when fetching or refreshing certificates. Since JWKS change fairly infrequently, the default behaviour is to log failures but use a stale cache value for up to 2 hours. This can be configured with the cache_refresh_grace_period option to OpenIDDiscoveryCertificateProvider.

HTTP-based discovery is the simplest and recommended solution, as it allows for issuer-controlled certificate and key rotation. However, an ArrayCertificateProvider is available (or you can provide your own implementation) if you would prefer to work with a hardcoded / alternative source of issuer certificates.

Contributing

Contributions are welcome but please contact us (e.g. by filing an issue) before you start work on anything substantial : we may have particular requirements / opinions that differ from yours.

Contributors

This package has been sponsored by inGenerator Ltd

• Andrew Coulton acoulton - Lead developer

Licence

Licensed under the BSD-3-Clause Licence