README

This library is a multi-protocol client based on OAuth.

Supported protocols are: OAuth 1.0, OAuth 1.0a, OAuth 2.0 and OpenID 1.0

This library can be configured to work with any platform providing services or resources based on these protocols.

The configuration of some providers is integrated in the library (built-in providers) which allows to use their services with a minimum of parameters.

For those who are not integrated, an array of options allows you to control access to services and resources. This array contains the list of endpoints, the mapping of non-standard fields, the identifiers registered with the provider as well as the way (strategy) to compose access requests.

Requirements

PHP >=7.1.3
symfony/http-client >= 4.3

Installation

From the root directory of your application, run: composer require eureka2/oauth-client

Usage

Low-level requests to a builtin OAuth provider

use eureka2\OAuth\Client\OAuthClient;

try {
   $client = OAuthClient::create('Google');
   $client->setClientId('<YOUR CLIENT ID>');
   $client->setClientSecret('<YOUR CLIENT SECRET>');
   $client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']);
   $user = (object) [];
   if ($client->initialize([
       'strategy' => [
           'offline_access' => true
       ]
   ])) {
       if ($client->authenticate()) {
           if (!empty($client->getAccessToken())) {
               $user = $client->getResourceOwner();
           }
       }
       $client->finalize();
   }
   if ($client->shouldExit()) {
       exit;
   }
   ....
   // Do something with $user
} catch (\Exception $e) {
   // Do something with $e
}

High-level request to a builtin OAuth provider

use eureka2\OAuth\Client\OAuthClient;

try {
   $client = OAuthClient::create('Google');
   $options = [ // See the full list of options below
       'provider' => [
           'registration' => [
               'keys' => [
                   'client_id' => '<YOUR CLIENT ID>',
                   'client_secret' => '<YOUR CLIENT SECRET>',
                   'redirect_uri' => 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['SCRIPT_NAME']
               ]
           ]
       ],
       'strategy' => [
           'offline_access' => true
       ]
   ];
   $user = $client->fetchResourceOwner($options);
   ....
   // Do something with $user
} catch (\Exception $e) {
   // Do something with $e
}

Options

$options = [
  'provider' => [
    'protocol' => [
      'name' => 'string',
      'version' => 'string'
    ],
    'endpoints' => [
      'discovery_endpoint' => 'string',
      'authorization_endpoint' => 'string',
      'token_endpoint' => 'string',
      'registration_endpoint' => 'string',
      'introspection_endpoint' => 'string',
      'revocation_endpoint' => 'string',
      'request_token_endpoint' => 'string',
      'userinfo_endpoint' => 'string',
      'end_session_endpoint' => 'string',
      'pin_dialog_url' => 'string',
      'jwks_uri' => 'string'
    ],
    'mapping' => [ // see https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims and https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim
      'user_id_field' => 'string',
      'name_field' => 'string',
      'given_name_field' => 'string',
      'family_name_field' => 'string',
      'middle_name_field' => 'string',
      'nickname_field' => 'string',
      'preferred_username_field' => 'string',
      'profile_field' => 'string',
      'picture_field' => 'string',
      'website_field' => 'string'
      'email_field' => 'string',
      'email_verified_field' => 'string',
      'gender_field' => 'string',
      'birthdate_field' => 'string',
      'zoneinfo_field' => 'string',
      'locale_field' => 'string',
      'phone_number_field' => 'string',
      'phone_number_verified_field' => 'string',
      'updated_at_field' => 'string',
      'formatted_field' => 'string',
      'street_address_field' => 'string',
      'locality_field' => 'string',
      'region_field' => 'string',
      'postal_code_field' => 'string',
      'country_field' => 'string'
    ],
    'registration' => [
      'keys' => [
        'client_id' => 'string',
        'client_secret' => 'string',
        'redirect_uri' => 'string',
        'realm' => 'string',
        'api_key' => 'string',
        'pin' => 'string'
      ],
      'credentials' => [
        'username' => 'string',
        'password' => 'string'
      ]
    ]
  ],
  'strategy' => [
    'reauthentication_parameter' => 'string',
    'offline_access' => 'boolean',
    'offline_access_parameter' => 'string',
    'append_state_to_redirect_uri' => 'string',
    'authorization_in_header' => 'boolean',
    'parameters_in_url' => 'boolean',
    'token_request_method' => 'string',
    'signature_method' => 'string',
    'signature_certificate_file' => 'string',
    'access_token_authentication' => 'string',
    'access_token_parameter' => 'string',
    'default_access_token_type' => 'string',
    'store_access_token_response' => 'boolean',
    'refresh_token_authentication' => 'string',
    'grant_type' => 'string',
    'get_token_with_api_key' => 'boolean',
    'access_token_content_type' => 'string',
    'access_token_language' => 'string',
    'scope' => 'string'
  ],
  'storage' => [
     'type' => 'string',
     'key' => 'string',
     'dsn' => 'string'
  ]
];

Name	Type	Values	Default	Description
provider.protocol.name	string	openid, oauth	oauth	The OAuth-based protocol supported by the OAuth provider
provider.protocol.version	string	1.0, 1.0a, 2.0	2.0	Version of the protocol supported by the OAuth provider
provider.endpoints.discovery_endpoint	string			URL that returns a JSON list of the OpenID/OAuth endpoints, supported scopes and claims, public keys
provider.endpoints.authorization_endpoint	string			URL of the OAuth provider to redirect the browser so the user can grant access to the application.
provider.endpoints.token_endpoint	string			URL of the OAuth provider endpoint used to obtain an ID token, access token, and refresh token
provider.endpoints.registration_endpoint	string			URL of an administrator managed service that is used to dynamically register, update, delete, and retrieve information about an OAuth client
provider.endpoints.introspection_endpoint	string			URL of the OAuth provider endpoint used to inspect the underlying authorisation properties of a token.
provider.endpoints.revocation_endpoint	string			URL of the OAuth provider endpoint that enables clients to notify that an issued token is no longer needed and must be revoked
provider.endpoints.request_token_endpoint	string			URL of the OAuth provider endpoint to request the initial token for OAuth 1.0 and 1.0a servers.
provider.endpoints.userinfo_endpoint	string			URL of the OAuth provider endpoint that returns Claims about the authenticated user.
provider.endpoints.end_session_endpoint	string			URL of the OAuth provider endpoint that allow a client to clear the provider-side session and cookies for a web browser.
provider.endpoints.pin_dialog_url	string			URL of the OAuth provider to redirect the browser so the user can grant access to your application for PIN-based authorization.
provider.endpoints.jwks_uri	string			URL for the OAuth Provider's JWK Set used for JSON Web Signature and/or JSON Web Encryption keys (JWK).
provider.mapping.user_id_field	string		sub	The field name received from the userinfo endpoint corresponding to the user identifier.
provider.mapping.name_field	string			The field name received from the userinfo endpoint corresponding to the user full name.
provider.mapping.given_name_field	string			The field name received from the userinfo endpoint corresponding to the user given name(s).
provider.mapping.family_name_field	string			The field name received from the userinfo endpoint corresponding to the user family name(s).
provider.mapping.middle_name_field	string			The field name received from the userinfo endpoint corresponding to the user middle name(s).
provider.mapping.nickname_field	string			The field name received from the userinfo endpoint corresponding to the user casual name.
provider.mapping.preferred_username_field	string			The field name received from the userinfo endpoint corresponding to the user preferred username.
provider.mapping.profile_field	string			The field name received from the userinfo endpoint corresponding to the URL of the user profile.
provider.mapping.picture_field	string			The field name received from the userinfo endpoint corresponding to the URL of the user picture.
provider.mapping.website_field	string			The field name received from the userinfo endpoint corresponding to the URL of the user website.
provider.mapping.email_field	string			The field name received from the userinfo endpoint corresponding to the user preferred email address.
provider.mapping.email_verified_field	string			The field name received from the userinfo endpoint corresponding to the user email verified flag.
provider.mapping.gender_field	string			The field name received from the userinfo endpoint corresponding to the user gender (female or male).
provider.mapping.birthdate_field	string			The field name received from the userinfo endpoint corresponding to the user birth date.
provider.mapping.zoneinfo_field	string			The field name received from the userinfo endpoint corresponding to the user zoneinfo.
provider.mapping.locale_field	string			The field name received from the userinfo endpoint corresponding to the user locale.
provider.mapping.phone_number_field	string			The field name received from the userinfo endpoint corresponding to the user phone number.
provider.mapping.phone_number_verified_field	string			The field name received from the userinfo endpoint corresponding to the user phone number verified flag.
provider.mapping.updated_at_field	string			The field name received from the userinfo endpoint corresponding to the user update datetime.
provider.mapping.formatted_field	string			The field name received from the userinfo endpoint corresponding to the user full mailing address.
provider.mapping.street_address_field	string			The field name received from the userinfo endpoint corresponding to the user full street address.
provider.mapping.locality_field	string			The field name received from the userinfo endpoint corresponding to the user city or locality.
provider.mapping.region_field	string			The field name received from the userinfo endpoint corresponding to the user state, province, prefecture or region.
provider.mapping.postal_code_field	string			The field name received from the userinfo endpoint corresponding to the user zip code or postal code.
provider.mapping.country_field	string			The field name received from the userinfo endpoint corresponding to the user country name.
provider.registration.keys.client_id	string			Identifier of the application registered with the OAuth provider.
provider.registration.keys.client_secret	string			Secret value assigned to the application when it is registered with the OAuth provider.
provider.registration.keys.redirect_uri	string			The URL registered with the OAuth provider that it must use after user authentication. For PIN-based authorization, set this variable to 'oob' (out-of-box)
provider.registration.keys.realm	string			Realm of authorization for OpenID Connect
provider.registration.keys.api_key	string			Identifier of the API key provided by the OAuth provider if it is required for authentication
provider.registration.keys.pin	string			Value of the PIN code for PIN-based authorization (redirect_uri = 'oob').
provider.registration.credentials.username	string			The user name to use to obtain authorization using a password (grant_type = 'password').
provider.registration.credentials.password	string			The password to use to obtain authorization using a password (grant_type = 'password').
strategy.reauthentication_parameter	string			The parameters to add to the OAuth provider authorization endpoint URL in case of new authentication.
strategy.offline_access	bool	true, false	false	Specify whether it will be necessary to call the API when the user is not present and the provider supports renewing expired access tokens using refresh tokens.
strategy.offline_access_parameter	string			The parameter to add to the OAuth provider authorization endpoint URL when offline access is requested
strategy.append_state_to_redirect_uri	string		state	The name of the OAuth session state variable, if different from the standard name
strategy.authorization_in_header	bool	true, false	true	Determines if the OAuth parameters should be passed via HTTP Authorization request header.
strategy.parameters_in_url	bool	true, false	false	Determines if the API call parameters should be moved to the calling URL.
strategy.token_request_method	string	GET, POST	GET	The HTTP method that should be used to request tokens from the provider
strategy.signature_method	string	PLAINTEXT, HMAC-SHA1, RSA-SHA1	HMAC-SHA1	The method to generate the signature for API request parameters values (Oauth 1.0 or 1.0a)
strategy.signature_certificate_file	string			The full path of the file containing a PEM encoded certificate/private key if signature_method is 'RSA-SHA1'
strategy.access_token_authentication	string	basic, none		Determines if the requests to obtain a new access token should use authentication to pass the application client ID and secret.
strategy.access_token_parameter	string		oauth_token, access_token	The name of the access token parameter to be passed in API call requests.
strategy.default_access_token_type	string			The type of access token to be assumed when the OAuth provider does not specify an access token type.
strategy.store_access_token_response	bool	true, false	false	Option to determine if the original response for the access token request should be stored
strategy.refresh_token_authentication	string	no		Option to determine if the requests to refresh an expired access token should use authentication to pass the application client ID and secret.
strategy.grant_type	string	client_credentials, password, authorization_code	authorization_code	The type of grant to obtain the OAuth 2 access token.
strategy.get_token_with_api_key	bool	true, false	false	Option to determine if the access token should be retrieved using the API key value instead of the client secret.
strategy.access_token_content_type	string			Content type to be assumed when retrieving the response to a request to retrieve the access token.
strategy.access_token_language	string			Language to be assumed when retrieving the response to a request to retrieve the access token.
strategy.scope	string			Permissions that your application needs to call the OAuth provider APIs
storage.type	string	session, cookie, apcu, pdo	session	The session storage mode (session: in $_SESSion, cookie: in browser encrypted cookies, apcu: in APC user store, pdo: in a PDO database)
storage.key	string			A key used to encrypt the cookies when the storage mode is 'cookie'
storage.dsn	string			The Data Source Name, or DSN, contains the information required to connect to the database if the storage mode is 'pdo'

Static methods

Name	Description
OAuthClient::create	Creates a OAuth client instance according to the given parameters.
OAuthClient::getConnectedResourceOwner	Returns the last connected resource owner if there is one.

Methods

Name	Description
initialize	Initialize the class variables and internal state. It must be called before calling other class functions.
isAuthenticated	Checks if the user is authenticated with the current OAuth provider.
authenticate	Process the OAuth protocol interaction with the OAuth provider.
callAPI	Send a HTTP request to the Web services API using a previously obtained access token via OAuth.
getResourceOwner	Returns the information about the resource owner using a previously obtained access token via OAuth.
fetchResourceOwner	Performs the entire authentication process (initialization, authentication, ...) and returns information about the resource owner.
finalize	Clean up resources that may be used when processing the OAuth protocol or executing API calls.
checkAccessToken	Check if the access token has been retrieved and is valid.
introspectToken	Determines the active state of a token and the meta-information about this token.
resetAccessToken	Reset the access token to a state back when the user has not yet authorized the access to the OAuth server API.
canRevokeToken	Determines whether the revokeToken function can be called.
revokeToken	Revoke a previously obtained token so it becomes invalid.
canLogOut	Determines whether the logOut function can be called.
logOut	Calls the end-session endpoint to notify the provider that the end-user has logged out of the relying party site.
shouldExit	Determine if the current script should be exited.
getAccessToken	Returns the obtained access token upon successful OAuth authentication.
getRefreshToken	Returns the obtained refresh token upon successful OAuth authentication.
getIdToken	Returns the obtained ID token upon successful OpenID authentication.
getProvider	Returns the current instance of the OAuthProvider class.
getStrategy	Returns the current instance of the OAuthClientStrategy class.

API documentation

Documentation of oauth-client classes

eureka2 / oauth-client

Maintainers

Details