Contents:, (*1)
[TOC], (*2)
auth-sdk
The auth-sdk is just a simple wrapper around persistent state storage and redirect response parsing for the
OAuth2 web grant type., (*3)
A simpler explanation is given http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified.
You should read it at least once, to have a basic understanding of OAuth2.
This sdk covers the "Web Server Apps" part mentioned there., (*4)
The auth-sdk hides most of the OAuth2 stuff, so you'll basically have to do 3 things (in this order):, (*5)
- First try to parse the redirect sent back to your site after the login.
- Call sdk->parseRedirectResponse()
- Check, if you have permissions (=access token) to call an api method for the user.
- If not, redirect the user to an external login page. [^1]
- Redirect to sdk->getLoginUrl()
Your app now should have permissions to make an api call on behalf of the user. Take a look at: ./examples/basic.php
, (*6)
You can use the acces token then stored in the auth-sdk for subsequent api calls until the token expires.
(Server-side or until the user logs out), (*7)
Include with composer
"require": {
"aboutyou/auth-sdk": "~0.3.6"
}
If you just want to run the examples now, please refer to the "Examples" section., (*8)
Oauth2 web grant type usage
- Have a look at:
./examples/basic.php
Create the sdk object
$authSDK = new AuthSDK(array(
'clientId'=>'from_dev_center',
'clientToken'=>'from_dev_center',
'clientSecret' => 'from_dev_center',
'redirectUri'=>'entered_in_dev_center',
'scope'=>'firstname', //optional. the only valid value is firstname at the moment
'popup'=>'true|false', //optional. true will render a small login, false the login webpage
),new SessionStorage());
(There are two optional parameters that can be "overwritten" 'loginUrl' and 'resourceUrl'. But usually there is no need
for that), (*9)
Parse the response (login redirected back to your site)
- Call this method first and only once per request
- $parsed will be true, if it was a redirect. Just in case you need this information.
$parsed = $authSDK->parseRedirectResponse();
Check user status. Show login or logout
- Check, if login button|redirect needed
$authResult = $authSDK->getUser();
if($authResult->hasErrors()){
//optional, add values you want to get back on your redirect endpoint
//but do this before getLoginUrl()
$authSDK->setState('someKey','someVal');
renderLoginButton( $authSDK->getLoginUrl() ); //renderLoginButton: your render method
var_dump($authResult->getErrors());
}else{
renderLogoutButton( $authSDK->getLogoutUrl() ); //renderLogoutButton: your render method
var_dump($authResult->getResult()->response);
var_dump($authSDK->getState('someKey'));
}
- Its also possible to set 'state' params (will be returned)
- getLogoutUrl() has an optional parameter redirectUrl. If set, after the logout you will be redirected to that. Else to the 'redirectUri' of the sdk config.
- In both cases getLogoutUrl() will append the get parameter logout=true to redirectUrl (which is used by e.g. parseRedirectUrl() to clean the persistent storage).
Examples
- Can be found in the folder:
./examples/*
Running
- Open a terminal, in the sdk root folder run
php composer.phar install
.
- If you use php >= 5.4 you can now try
./run.sh
(as root/sudo) in the ./examples
folder. Keep an eye on the console messages (it will complain about the /etc/hosts config, add it). If everything works, you should be able to open the (local) url shown in the console afterwards.
- On Windows, or if run.sh is not working: With php >= 5.4 just try
php -S mytestserver.local:8080
in the ./examples
folder (as root/sudo on linux/osx). Notice you have to add 127.0.0.1 mytestserver.local
to your /etc/hosts
for this to work. (Windows: system32\drivers\etc\hosts)
- For php < 5.4 refer to your server documentation to create a vhost config with the document root pointing to the
./examples
folder.
Files
-
./examples/basic.php
:, (*10)
- example for typical usecase, just as much code as needed. Note, that you need to set your redirectUrl to {yourdomain}/basic.php
-
./examples/parent_page.php
& ./examples/result_page.php
:, (*11)
- example for showing more options, intercepts the redirect, so you can take a look at the params returned. Note, that you need to set your redirectUrl to {yourdomain}/result_page.php
Config
- Copy
./example/common_params.php
to ./example/common_params.local.php
- Change the params in ./example/common_params.local.php to match your values (from dev center)