README

A simple library that allows an application to authenticate a user through the basic OpenID Connect flow. This library hopes to encourage OpenID Connect use by making it simple enough for a developer with little knowledge of the OpenID Connect protocol to setup authentication.

This package is a complete refactor of JuliusPC/OpenID-Connect-PHP.

Supported Specifications

Requirements

PHP 8.1+
JSON extension
MBString extension
(Optional) One between GMP or BCMath extension to allow faster cipher key operations (for JWT; see here for more information)

Install

Install using composer:

composer require autisid/oidc-client-php

Examples

Example 1: Basic Client

This example uses the Authorization Code flow and will also use PKCE if the OpenID Provider announces it in his Discovery document. If you are not sure, which flow you should choose: This one is the way to go. It is the most secure and versatile.

use Autisid\OpenIDConnect\Client;

$oidc = (new Client())
    ->providerUrl('https://id.example.com')
    ->clientId('ClientIDHere')
    ->clientSecret('ClientSecretHere')
$oidc->authenticate();
$name = $oidc->getUserInfo()->given_name;

See OpenID Connect spec for available user attributes

Example 2: Dynamic Registration

use Autisid\OpenIDConnect\Client;

$oidc = (new Client())
    ->providerUrl('https://id.example.com')

$oidc->register();
[$client_id, $client_secret] = $oidc->getClientCredentials();

// Be sure to add logic to store the client id and client secret

Example 3: Network and Security

You should always use HTTPS for your application. If you are using a self-signed certificate, you can disable the SSL verification by calling the verifySsl method on the client and, if you have it, set a custom certificate with certPath method (this works only if verifySsl is set to false).

You can also setup a proxy via the httpProxy.

use Autisid\OpenIDConnect\Client;

$oidc = (new Client())
    ->providerUrl('https://id.example.com')
    ->clientId('ClientIDHere')
    ->clientSecret('ClientSecretHere')
    ->httpProxy('http://proxy.example.com:8080')
    ->certPath('path/to/cert.pem')
    ->verifySsl(false)

Example 4: Implicit flow

Reference: https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth

The implicit flow should be considered a legacy flow and not used if authorization code grant can be used. Due to its disadvantages and poor security, the implicit flow will be obsoleted with the upcoming OAuth 2.1 standard. See Example 1 for alternatives.

use Autisid\OpenIDConnect\Client;
use Autisid\OpenIDConnect\ResponseType;

$oidc = (new Client())
    ->providerUrl('https://id.example.com')
    ->clientId('ClientIDHere')
    ->clientSecret('ClientSecretHere')
    ->responseType(ResponseType::ID_TOKEN)
    ->allowImplicitFlow(true)
$oidc->authenticate();
$sub = $oidc->getUserInfo()->sub;

Example 5: Introspection of an access token

Reference: https://tools.ietf.org/html/rfc7662

use Autisid\OpenIDConnect\Client;

$oidc = (new Client())
    ->providerUrl('https://id.example.com')
    ->clientId('ClientIDHere')
    ->clientSecret('ClientSecretHere')

$data = $oidc->introspectToken('an.access-token.as.given');
if (!$data->get('active')) {
    // the token is no longer usable
}

Example 6: PKCE Client

PKCE is already configured and used in most scenarios in Example 1. This example shows you how to explicitly set the Code Challenge Method in the initial config. This enables PKCE in case your OpenID Provider doesn’t announce support for it in the discovery document, but supports it anyway.

use Autisid\OpenIDConnect\Client;
use Autisid\OpenIDConnect\CodeChallengeMethod;

$oidc = (new Client())
    ->providerUrl('https://id.example.com')
    ->clientId('ClientIDHere')
    ->clientSecret('ClientSecretHere')
    // for some reason we want to set S256 explicitly as Code Challenge Method
    // maybe your OP doesn’t announce support for PKCE in its discovery document.
    ->codeChallengeMethod(CodeChallengeMethod::S256)

$oidc->authenticate();
$name = $oidc->getUserInfo()->given_name;

Example 7: Token endpoint authentication method

By default, only client_secret_basic is enabled on client side which was the only supported for a long time. Recently client_secret_jwt and private_key_jwt have been added, but they remain disabled until explicitly enabled.

use Autisid\OpenIDConnect\Client;
use Autisid\OpenIDConnect\TokenEndpointAuthMethod;

$oidc = (new Client())
    ->providerUrl('https://id.example.com')
    ->clientId('ClientIDHere')
    ->clientSecret('ClientSecretHere')
    ->endpoints(options: [
        'token_endpoint_auth_methods_supported' => [
            TokenEndpointAuthMethod::CLIENT_SECRET_BASIC,
            TokenEndpointAuthMethod::CLIENT_SECRET_JWT,
            TokenEndpointAuthMethod::PRIVATE_KEY_JWT,
        ],
    ]);

Note: A JWT generator is not included in this library yet.

Development Environments

Sometimes you may need to disable SSL security on your development systems. You can do it by calling the verify method with the false parameter. Note: This is not recommended on production systems.

use Autisid\OpenIDConnect\Client;

$oidc = (new Client())
    ->providerUrl('https://id.example.com')
    ->clientId('ClientIDHere')
    ->clientSecret('ClientSecretHere')
    ->verifySsl(false)

Todo

Dynamic registration does not support registration auth tokens and endpoints

Contributing

All pull requests, once merged, should be added to the CHANGELOG.md file.

autisid / oidc-client

Maintainers

Details