pws-auth/README.md
2017-03-16 02:18:19 +01:00

131 lines
3.9 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# PwsAuth
PwsAuth is an authentication protocol throught http header designed to web services
## Request Headers
Request headers must be define as follow :
Pws-Authorization : $type $token
Pws-Ident : $userkey
The **$token** can be either a `loginToken` or a `sessionToken`
The **$token** is divided in four part
* a datetime formatted with the `Authenticator::DATE_FORMAT` format
* an obfuscate part 's token builded by date, common salt & the third token 's part
* a loginToken representing a user signed token for a specific login at given date
OR
a session token representing the session id
* noise data to be removed
The complete token is valid only if obfuscate part can be rebuild.
This simple mecanism ensure that **sessionId** is valid and can be safety load
Authenticator 's configuration comes with a `hash.session.index` and `hash.noise.length` values
wich can be redefined to move the session token part into the complete token
<< hash.session.index >> << hash.noise.length >>
|-----------------------------------------------------------<<-^->>---------------------------------------------<<-^->>--------|
|- type ||-- date ---|------------ obfuscate token ---------<<-^->>-------------- session token ----------------<<-^->> noise -|
| || 1 | 2 | 3 | 4 |
PwsAuth2 242003031711e1a6104135f04c6c01e6cd5952ecafbb53c928603b0gb64tqo609qse6ovd7lhdvk4fnaqk7cdl26e4d4qh7jb41eu5f1zb5y79m8pgu3
### Requirements
PHP >= 5.4
### Install
The package can be installed using [ Composer ](https://getcomposer.org/).
```
composer require meta-tech/pws-auth
```
Or add the package to your `composer.json`.
```
"require": {
"meta-tech/pws-auth" : "^2.1"
}
```
### Authenticator instanciation
```php
<?php
require_once(__dir__ . '/vendor/autoload.php');
use Symfony\Component\Yaml\Yaml;
use MetaTech\PwsAuth\Authenticator;
$config = Yaml::parse(file_get_contents(__dir__ . '/config/pwsauth.yml'));
$authenticator = new Authenticator($config);
```
### ClientSide
A request header can be generated via the `generateHeader($login, $key, $sessid=null)` method.
The third parameter determine wich kind of token will be generated
for a client usage, see [ MetaTech\Ws\Client ](https://github.com/meta-tech/pws-client/blob/master/src/MetaTech/Ws/Client.php)
### ServerSide
The Token can be retriew via the `getToken` method
`loginToken` is validate by the `check(Token $token = null, $login)` method
`loginToken` must match a public url with method `POST` and a couple of login/password
On successfull login, the session id must be transmit to the client.
`sessionToken` is valid only if the session can effectively be loaded, and the
user key match the given `Pws-Ident` value
for a server usage, see [ MetaTech\Silex\Ws\Authentication ](https://github.com/meta-tech/silex-core/blob/master/src/MetaTech/Silex/Ws/Authentication.php)
and [ meta-tech/pws-server ](https://github.com/meta-tech/pws-server).
### Configuration
Configuration must be the same on server and client sides
Hash definition is a convenient way to obfuscate your tokens
`config/pwsauth.yml`
```yaml
type : PwsAuth2
header :
auth : Pws-Authorization
ident : Pws-Ident
salt :
common : jK5#p9Mh5.Zv}
# used for generating user specific salt
user.index : 10
user.length : 12
hash :
sep : /
algo : sha256
# effective token length size. out of bound data is simply noise
length : 52
# session index (or obfuscate length)
session.index : 58
# ending noise data length)
noise.length : 12
```
### Notes
A valid `$userkey` alone is useless
A valid `$sessionId` alone is useless
### License
The project is released under the MIT license, see the LICENSE file.