maenbn/openamauth

OpemAmAuth is a client for authenticating against OpenAM in PHP

OpenAM Authentication

, _(*1)

This is a PHP library for authenticating users via OpenAM, _(*2)

NOTE: Usage with Laravel

This package has been changed to be framework agnostic. If you're using Laravel 5.1 then continue to use **v1.1.*** of this package. For later versions of Laravel, a new separate package for Laravel will be created using this package as it's core logic. More information will follow., _(*3)

Installation

The tool requires you have PHP 5.6.*+ and Composer., _(*4)

You will also need a OpenAM server., _(*5)

To install the package run the following composer command, _(*6)

``` bash composer require maenbn/openamauth, <sub>(*7)</sub>

## Usage
### Setup

To setup an OpenAm object you will need to initialise a config object and pass that to the OpenAm factory:

 ```php
 // Construct parameters are address of your OpenAm server, realm (optional), deploy URI (optional)
 $config = new \Maenbn\OpenAmAuth\Config('https://myopenam.com', 'people', 'openam');
 // OpenAm instance
 $openAm = \Maenbn\OpenAmAuth\Factories\OpenAmFactory::create($config);
 ```

 ### Authenticating and retrieving the return token ID
 ```php
 if($openAm->authenticate('username', 'password'){
    $tokenId = $openAm->getTokenId();
    // Further successful authenication logic ...
 }
 ```

### Validate Token
If an OpenAm instance has ran a successful ```authenticate``` during the current runtime then you can validate
the token id without having to set a token ID on the instance. Other wise use the ```setTokenId``` setter before 
validating.

```php
// Returns a bool or throws and exception if not token ID is set
$valid = $openAm->setToken($tokenId)->validateTokenId();

Getting users details

If an OpenAm instance has ran a successful authenticate during the current runtime then you can get the users details return from OpenAM without having to set a token ID and the user ID. Other wise use the setTokenId and setUid setters before running the setUser then getUser., <sub>(*8)</sub>

```php // Returns a stdClass with the user's details or null if the token ID and user ID have not been set $user = $openAm->setToken($tokenId)->setUid($uid)->setUser()->getUser();, <sub>(*9)</sub>

// If successful authenicate has been ran if($openAm->authenticate('username', 'password'){ $user = $openAm->getUser(); // Further successful authenication logic ... }, <sub>(*10)</sub>

### Logging out
If an OpenAm instance has ran a successful ```authenticate``` during the current runtime then you can logout without 
having to set a token ID. Other wise use the ```setTokenId``` setter before logging out a user.

```php
// Return a bool based of success of log out
$openAm->setTokenId($tokenId)->logout();

Accessing Config object via OpenAm object

When the Config object is injected into the constructor of OpenAm it'll modify the cookieName and cookieSecure property on Config if they're set to null. This is done by retrieving this information from the OpenAm server. Obviously you may want to retrieve this data in order to set a cookie on your app correctly. Therefore you can access the Config object via the OpenAm object via the getter:, <sub>(*11)</sub>

```php // Will return Config object $config = $openAm->getConfig();, <sub>(*12)</sub>

$cookieName = $config->getCookieName(); $cookieSecure = $cofig->getCookieSecure(); ```, <sub>(*13)</sub>