Download the PHP package cicnavi/oidc-client-php without Composer

OIDC Client - PHP

OIDC client written in PHP. It uses OIDC authorization code flow to perform authentication. It implements JWKS public key usage and automatic key rollover, caching mechanism (file based by default), ID token verification and claims extraction, as well as 'userinfo' user data fetching. It can also be used to simulate authorization code flow using PKCE parameters intended for public clients.

Prerequisites

PHP environment:

• Please check composer.json for environment requirements.
• ODIC client uses PHP session to handle 'state', 'nonce' and 'code_verifier' parameters storage and validation. If the session is not already started, OIDC client will try to start it using session config from php.ini.

OpenID Provider must support:

• authorization code flow
• OIDC Discovery URL (well-known URL with OIDC metadata)
• JWKS URI providing JWK key(s)

Installation

OIDC Client is available as a Composer package. In your project you can run:

Client instantiation

To instantiate a client you will have to prepare a Config instance. First, prepare an array with the following OIDC configuration values, for example:

Make sure to include 'openid' scope in order to use ID token for user claims extraction. Other scopes are optional (refer to the documentation for your OpenID Provider).

Next, create a Cicnavi\Oidc\Config instance using the previously prepared config array:

OIDC client can now be instantiated using config instance as parameter:

Client usage

To initiate authorization (authorization code flow), that is, to initiate a login process, you can use authorize() method:

This will initiate a browser redirection to the authorization server, where the user will log in. If the login is successful, authorization server will initiate a browser redirection to the 'redirect_uri' which was registered with the client (this is your callback).

On the callback URI, you'll receive authorization code and state (if state check is enabled) as GET parameters. To use that authorization code, you can use getUserData() method. This method will validate state (if state check is enabled) and send an HTTP request to token endpoint using the provided authorization code in order to retrieve tokens (access and ID token). After that it will try to extract claims from ID token (if it was returned, that is if 'openid' scope was used in client configuration), and will fetch user data from 'userinfo' endpoint using access token for authentication.

The returned user data will be in a form of array, for example:

Note that some OpenID providers (for example, AAI@EduHr Federation), will send claims that have multiple values, for example:

Note on Caching

OIDC client uses caching to avoid sending HTTP requests to fetch OIDC configuration content and JWKS content on every client usage.

Default cache TTL (time-to-live) is set in configuration, so you can modify it as needed. If you need to bust cache, use reinitializeCache() client instance before making any authentication calls.

By default, OIDC client uses file based caching. This means that it uses a folder on your system to store files with cached data. For your convenience, class Cicnavi\Oidc\Cache\FileCache is used to instantiate a Cache instance which will store files in the default system 'tmp' folder. In the background, this class will use the cicnavi/simple-file-cache-php package. If you want, you can utilize other caching techniques (memcached, redis...) by installing the corresponding package which provides psr/simple-cache-implementation, and use it for OIDC client instantiation.

Example below demonstrates how to initialize default FileCache instance using custom cache name and folder path (make sure the folder exists and is writable by the web server).

Note on SameSite Cookie Attribute

SameSite Cookie attribute plays an important role in Single Sign-On (SSO) environments because it determines how cookies are delivered in third party contexts. During OIDC authorization code flow (the authentication flow this OIDC client uses), a series of HTTP redirects between RP and OP is performed.

By default, the authorization code will be delivered to the RP using HTTP Redirect meaning that the User Agent will do a GET request to the RP callback. This means that the SameSite Cookie attribute can be set to 'Lax' or 'None', but not 'Strict' (if the value is 'None', the attribute 'Secure' must also be set).

Run tests

All tests are available as Composer scripts, so you can simply run them like this: