maicol07 / oidc-client
OpenID Connect client
Fund package maintenance!
maicol07
paypal.me/maicol072001/10eur
Installs: 468
Dependents: 2
Suggesters: 0
Security: 0
Stars: 5
Watchers: 1
Forks: 366
Open Issues: 0
Requires
- php: >=8.3
- ext-json: *
- ext-mbstring: *
- cse/helpers-session: ^1
- guzzlehttp/guzzle: >=7
- illuminate/collections: >=8
- illuminate/http: >=8
- illuminate/support: >=8
- web-token/jwt-library: ^4.0.1
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3
- php-webdriver/webdriver: ^1
- phpunit/phpunit: ^11
- rector/rector: ^1
- roave/security-advisories: dev-latest
- vlucas/phpdotenv: ^5
Suggests
- ext-bcmath: Faster cipher key operations. Please see https://web-token.spomky-labs.com/introduction/pre-requisite
- ext-gmp: Faster cipher key operations. Please see https://web-token.spomky-labs.com/introduction/pre-requisite
- dev-main
- 4.0-rc1
- 3.0
- 2.3
- 2.2.1
- 2.2
- 2.1
- 2.0.5
- 2.0.4
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0
- 2.0a1
- 1.2
- 1.1.5.3
- 1.1.5.2
- 1.1.5.1
- 1.1.5
- 1.1.4
- 1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.0
- v0.9.2
- v0.9.1
- v0.9.0
- v0.8.0
- 0.7.0
- 0.6.0
- v0.5.0
- 0.4.1
- 0.4.0
- 0.3.0
- 0.2.0
- 0.1.0
- dev-patch-1
- dev-JuliusPC/fix-warnings
- dev-JuliusPC/configure-https-upgrade
- dev-JuliusPC/fix-composer-dependency
- dev-JuliusPC/cleanup
This package is auto-updated.
Last update: 2024-11-02 14:01:05 UTC
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.
Supported Specifications
- OpenID Connect Core 1.0
- OpenID Connect Discovery 1.0 (finding the issuer is missing)
- OpenID Connect RP-Initiated Logout 1.0 - draft 01
- OpenID Connect Dynamic Client Registration 1.0
- RFC 6749: The OAuth 2.0 Authorization Framework
- RFC 7009: OAuth 2.0 Token Revocation
- RFC 7636: Proof Key for Code Exchange by OAuth Public Clients
- RFC 7662: OAuth 2.0 Token Introspection
- Draft: OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response
Tested providers
Note: This list is not exhaustive. Other generic OIDC providers should work as well. If you have tested this library with a provider not listed here, please open a PR to add it to the list and add a test configuration (.run directory).
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 maicol07/oidc-client
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 Maicol07\OpenIDConnect\Client; $oidc = new Client( provider_url: 'https://id.example.com', client_id: 'ClientIDHere', client_secret: 'ClientSecretHere', redirect_uri: 'https://example.com/callback.php', ); $oidc->authenticate(); $name = $oidc->getUserInfo()->given_name;
See OpenID Connect spec for available user attributes
Example 2: Dynamic Registration
use Maicol07\OpenIDConnect\Client; $oidc = new Client( provider_url: 'https://id.example.com', redirect_uri: 'https://example.com/callback.php', client_name: 'My Client', ); $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 setting the verify_ssl
property on the client and, if you have it, set a custom certificate in the cert_path
property
(this works only if verifySsl is set to false).
You can also setup a proxy via the http_proxy
.
use Maicol07\OpenIDConnect\Client; $oidc = new Client( provider_url: 'https://id.example.com', client_id: 'ClientIDHere', client_secret: 'ClientSecretHere', redirect_uri: 'https://example.com/callback.php', http_proxy: 'http://proxy.example.com:8080', cert_path: 'path/to/cert.pem', verify_ssl: 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 Maicol07\OpenIDConnect\Client; use Maicol07\OpenIDConnect\ResponseType; $oidc = new Client( provider_url: 'https://id.example.com', client_id: 'ClientIDHere', client_secret: 'ClientSecretHere', redirect_uri: 'https://example.com/callback.php', response_type: ResponseType::ID_TOKEN, allow_implicit_flow: true, ); $oidc->authenticate(); $sub = $oidc->getUserInfo()->sub;
Example 5: Introspection of an access token
Reference: https://tools.ietf.org/html/rfc7662
use Maicol07\OpenIDConnect\Client; $oidc = new Client( provider_url: 'https://id.example.com', client_id: 'ClientIDHere', client_secret: 'ClientSecretHere', redirect_uri: 'https://example.com/callback.php' ); $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 Maicol07\OpenIDConnect\Client; use Maicol07\OpenIDConnect\CodeChallengeMethod; $oidc = new Client( provider_url: 'https://id.example.com', client_id: 'ClientIDHere', client_secret: 'ClientSecretHere', redirect_uri: 'https://example.com/callback.php', // 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. code_challenge_method: 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 Maicol07\OpenIDConnect\Client; use Maicol07\OpenIDConnect\TokenEndpointAuthMethod; $oidc = new Client( provider_url: 'https://id.example.com', client_id: 'ClientIDHere', client_secret: 'ClientSecretHere', redirect_uri: 'https://example.com/callback.php', 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 Maicol07\OpenIDConnect\Client; $oidc new Client( provider_url: 'https://id.example.com', client_id: 'ClientIDHere', client_secret: 'ClientSecretHere', redirect_uri: 'https://example.com/callback.php', verify_ssl: false );
Testing
To run the tests, you need to have a running OpenID Connect provider
Keycloak
- Run a Keycloak docker container
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:25.0.5 start-dev
- Create a realm named
test
- Create a client named
test-client
withconfidential
access type - Set the
Valid Redirect URIs
tohttp://localhost:8080/callback
- Set the
Web Origins
tohttp://localhost:8080
- Set the
Access Type
toBearer-only
- Set the
Client Authenticator
toClient id and secret
- Set the
Client ID
totest-client
- Set the
Client Secret
totest-client-secret
- Set the
Root URL
tohttp://localhost:8080
Todo
- Dynamic registration does not support registration auth tokens and endpoints
Contributing
- Issues and pull requests are welcome.