The purpose of the library is to provide tools and building blocks for creating clients using delegated authentication/authorization based on the OAuth2 protocol with emphasis on the OpenID Connect specification.
- flexible and extensible
- dependency injection approach
- covered with unit tests
- based on parts of the Zend Framework 2
The library jas been tested successfully with the following identity providers:
- Zend Framework >= 2.2.1
Add the following requirement to your composer.json file:
"require": {
"ivan-novakov/php-openid-connect-client": "dev-master"
}
Just clone the repository or download and unpack the latest release and configure your autoloader accordingly.
You need a client_id and client_secret registered at the identity provider. And you have to know the URLs of the provider endpoints.
The most common flow is:
- generate authorize request URL
- redirect the user to the authorize URL or make him click a "login" button
- process the callback request and retrieve the authorization code
- make a token request with the authorization code and retrieve the access token
- (optional) make a user info request with the access token and retrieve information about the user
The library introduces a "flow" object, which integrates the above actions into just two calls:
getAuthorizationRequestUri- generates the URL for user authorization, then it's up to the developer, how the user is redirected to the URLprocess- performs actions 3, 4 and 5 from the above list in one go
Simple example:
use InoOicClient\Flow\Basic;
$config = array(
'client_info' => array(
'client_id' => '<client ID>',
'redirect_uri' => '<redirect URI>',
'authorization_endpoint' => 'https://accounts.google.com/o/oauth2/auth',
'token_endpoint' => 'https://accounts.google.com/o/oauth2/token',
'user_info_endpoint' => 'https://www.googleapis.com/oauth2/v1/userinfo',
'authentication_info' => array(
'method' => 'client_secret_post',
'params' => array(
'client_secret' => '<client secret>'
)
)
)
);
$flow = new Basic($config);
if (! isset($_GET['redirect'])) {
try {
$uri = $flow->getAuthorizationRequestUri('openid email profile');
printf("<a href=\"%s\">Login</a>", $uri);
} catch (\Exception $e) {
printf("Exception during authorization URI creation: [%s] %s", get_class($e), $e->getMessage());
}
} else {
try {
$userInfo = $flow->process();
} catch (\Exception $e) {
printf("Exception during user authentication: [%s] %s", get_class($e), $e->getMessage());
}
}
The "flow" object is just a facade. The real "work" is done by the so called "dispatchers":
InoOicClient\Oic\Authorization\Dispatcher- generates authorization request URI and processes the callbakc requestInoOicClient\Oic\Token\Dispatcher- sends a token requestInoOicClient\Oic\UserInfo\Dispatcher- sends a user info request
The library uses the Zend Framework 2 HTTP client with the cURL connection adapter, which provides the best security regarding secure HTTPS connections. The HTTP client is created through a factory, which configures the client to validate the server certificate by default. The client also performs a CN matching validation. You can find more info about secure HTTPS connections with Zend Framework 2 in this blogpost.
However, it is possible to inject your own instance of the HTTP client, configured differently.
According to the OpenID Connect specification (see also the OAuth2 specs), the library supports these client authentication methods:
client_secret_basic- the client secret is sent in anAuthorizationHTTP headerclient_secret_post- the client secret is sent as a POST parameter
The specifications recommend using the state parameter when requesting for authorization. The server is then obliged to return the same value in the callback. This may prevent cross-site request forgery attacks.
The library authomatically handles the state:
- generates an opaque state value during authorization URI creation
- saves the state in a user session
- checks the state value sent from the server against the saved one
By default, the generated state value is saved in the user session (a session container from the Zend Framework). It is possible to use another storage by implementing the InoOicClient\Oic\Authorization\State\Storage\StorageInterface
If you need to build custom flow or to extend/modify some of the functionality, you can implement your own flow object (see InoOicClient\Flow\Basic for details) or you can use dispatchers directly. Then you can build and configure the involved objects (dispatchers, requests, responses etc.) to suit your use case.
Creating the client info object:
use InoOicClient\Client\ClientInfo;
$clientOptions = array(
'client_id' => '<client ID>',
'redirect_uri' => '<redirect URI>',
'authorization_endpoint' => 'https://accounts.google.com/o/oauth2/auth',
'token_endpoint' => 'https://accounts.google.com/o/oauth2/token',
'user_info_endpoint' => 'https://www.googleapis.com/oauth2/v1/userinfo',
'authentication_info' => array(
'method' => 'client_secret_post',
'params' => array(
'client_secret' => '<client secret>'
)
)
);
$clientInfo = new ClientInfo();
$clientInfo->fromArray($clientOptions);
Preparing the authorization request URI:
use InoOicClient\Oic\Authorization;
$stateManager = new Manager();
$dispatcher = new Authorization\Dispatcher();
$dispatcher->setStateManager($stateManager);
$request = new Authorization\Request($clientInfo, 'code', 'openid profile email');
$uri = $dispatcher->createAuthorizationRequestUri($request);
Retrieve the authorization code from the callback:
$stateManager = new Manager();
$dispatcher = new Authorization\Dispatcher();
$dispatcher->setStateManager($stateManager);
$response = $dispatcher->getAuthorizationResponse();
printf("OK<br>Code: %s<br>State: %s<br>", $response->getCode(), $response->getState());
Peform token request:
$httpClientFactory = new Http\ClientFactory();
$httpClient = $httpClientFactory->createHttpClient();
$tokenDispatcher = new Token\Dispatcher($httpClient);
$tokenRequest = new Token\Request();
$tokenRequest->setClientInfo($clientInfo);
$tokenRequest->setCode($authorizationCode);
$tokenRequest->setGrantType('authorization_code');
$tokenResponse = $tokenDispatcher->sendTokenRequest($tokenRequest);
printf("Access token: %s<br>", $tokenResponse->getAccessToken());
- provide user-friendly demos for different providers
- add support for JWT and ID token validation
OpenID Connect:
OAuth2: