# PHP OpenID Connect Client library

Implement OpenID Connect Client (Relying Party) functionality in your project.

Minimum configuration, maximum usability and security.

## Installation

`composer require authstack/oidc-client: *`

## Use

This library requires knowledge of OpenID Connect terminology and authentication flows.

There are three objects involved in the workflow:

1. `Client` object. It represents the application asking for authentication/authorization info.
2. `Provider` object. It represents OpenID Provider (IdP).
3. `FlowInterface` object. It represents the *flow* (means) of communication between `Client` and `Provider`.


### AuthorizationCode flow

This is a 2 step protocol. First we ask for `code` which we exchange (via http) for `id_token`. Security checks are performed in between automatically

Create the request and redirect to OP (OpenID Provider, IdP)
---

```php
use Authstack\OpenIDConnect\Client;
use Authstack\OpenIDConnect\Provider;
use Authstack\OpenIDConnect\Model\Protocol\Flow\AuthorizationCode;

$client = Client::create([
                // Client ID as registered with OP
                'clientID' => 'your client ID',

                // Client secret, as registered with OP
                'secret' => 'Your client secret',

                // Redirect URI where OP will send the response, must be registered with OP
                'redirectURI' => 'https://your-client.domain.tld/redirect/callback'
            ]);

$provider = Provider::create([
                // OP issuer value - used for signature when verifying the origin
                'iss' => 'https://authstack',

                // Authorization URL - you'll be redirected there with required parameters
                'authorizationEndpoint' => 'https://authstack.dev/oauth2/authorize'
            ]);

// The flow we need to use. AuthorizationCode is the most complex one because it consists of two HTTP requests
$flow = new AuthorizationCode();

$redirect = $client
                // Assign the provider
                ->setProvider($provider)

                // Assign the flow
                ->setFlow($flow)

                // Returns the Illuminate\Http\RedirectResponse object
                ->authenticate();
```


### Consume the OpenID Provider Response (encapsulated via `Illuminate\Http\Request` object);
---

```php
use Authstack\OpenIDConnect\Client;
use Authstack\OpenIDConnect\Provider;
use Authstack\OpenIDConnect\Model\Protocol\Flow\AuthorizationCode;

// This is available by default in Laravel
$request = \Illuminate\Http\Request::createFromGlobals();

$client = Client::create([
                // Client ID as registered with OP
                'clientID' => 'your client ID',

                // Client secret, as registered with OP
                'secret' => 'Your client secret',

                // Redirect URI where OP will send the response, must be registered with OP
                'redirectURI' => 'https://your-client.domain.tld/redirect/callback'
            ]);

$provider = Provider::create([
                // OP issuer value - used for signature when verifying the origin
                'iss' => 'https://authstack',

                // Authorization URL - you'll be redirected there with required parameters
                'authorizationEndpoint' => 'https://authstack.dev/oauth2/authorize'
            ]);

// The flow we need to use. AuthorizationCode is the most complex one because it consists of two HTTP requests
$flow = new AuthorizationCode();

$response = $client
                ->setProvider($provider)
                ->setFlow($flow)
                ->consume($request);

```

### AuthorizationCode flow with PKCE (Proof Key for Code Exchange)

PKCE is toggled on/off using `AuthorizationCode` flow class.

```php
use Authstack\OpenIDConnect\Client;
use Authstack\OpenIDConnect\Provider;
use Authstack\OpenIDConnect\Model\Protocol\Flow\AuthorizationCode;

$client = Client::create([]); // Pseudocode
$provider = Provider::create([]);
$flow = new AuthorizationCode();

// Turn PKCE ON
$flow->setPKCE(true);

$flow = $client->setProvider($provider)->setFlow($flow)->buildAuthenticationRequest();

// Get the code_verifier (secret). In this case, it's auto-generated. You're supposed to save
// it because it's used when exchanging the code for ID token
$code_verifier = $flow->getCodeVerifier();

// RedirectResponse object
$response = $flow->getResponse();
```

### Consume AuthorizationCode flow response with PKCE

```php
use Illuminate\Http\Request;
use Authstack\OpenIDConnect\Client;
use Authstack\OpenIDConnect\Provider;
use Authstack\OpenIDConnect\Model\Protocol\Flow\AuthorizationCode;

$request = Request::createFromGlobals();
$client = Client::create([]); // Pseudocode
$provider = Provider::create([]);
$flow = new AuthorizationCode();

// Turn PKCE ON
$flow->setPKCE(true);

// Set the code_verifier to the one you **saved** in the previous step
$code_verifier = ''; // pull this out from session, db, whatever mechanism you used

$flow->setCodeVerifier($code_verifier);

// You have the ID token now
$result = $flow->consume($provider, $client, $request);
```


### Implicit flow


### Hybrid flow