LaunchKey OAuth SDK for PHP

The PHP OAuth library provides a quick and simple way to add multi-factor authentication to your website or web service with the popular OAuth 2.0 protocol.

Before you can begin using the LaunchKey API, you need a service. If you have not created a service yet, you can use our Getting Started Guide to create one.

This SDK uses OAuth to do its heavy lifting. This will require configuring your service. Please read OAuth Configuration for Services for instructions.

Example Apps

See example.php inside the source for an example implementation of the calls below.

Installation

Clone Source

$ git clone https://github.com/LaunchKey/launchkey-oauth-php.git

Packagist

LaunchKey PHP OAuth SDK on Packagist

$ php composer.phar require launchkey/launchkey-oauth:~0.1

Add LaunchKey OAuth SDK To Your Project

Composer

The preferred way to install the LaunchKey OAuth SDK for PHP is to use Composer, the PHP package manager. No additional work beyond adding the auto-loader to your project is required.

Manual

Use whatever strategy you currently use for adding shared libraries to your code base and require the lib/LaunchKey/OAuth.php file where the SDK client is needed.

Example

This example shows how to add the code to your system using Git and add the location to your include path.

  1. Add the code to your system
$ sudo git clone https://github.com/LaunchKey/launchkey-oauth-php.git /usr/lib/php/launchkey-oauth-php

#. Add the library location to the include path and

set_include_path(get_include_path() . PATH_SEPARATOR . "/usr/lib/php/launchkey-oauth-php");
require_once("lib/LaunchKey/OAuth.php");

Create A LaunchKey SDK Client

Instantiate the \LaunchKey_OAuth object with your service key and secret key from the Service details page of your LaunchKey Service as well as a redirect URL in the specific domain you specified on your Service settings page.

Definition

LaunchKey_OAuth(app_key, $secret_key, $redirect_url))

Parameters

app_key:integer Unique 10-digit service key from your Service details page in dashboard
secret_key:string Service secret key from your Service keys page in dashboard
redirect_url:string Location user will be redirected to after login (default is current page)

Return

The constructor returns a LaunchKey_OAuth object that is ready to make OAuth API calls.

Example

$oauth = new LaunchKey_OAuth("1234567890","SuperSecretAndRandomSecretKey", "https://example.com");

Initiating The Login Dialogue

To initiate the LaunchKey login dialogue, your end users will click a LaunchKey login button. To add this button to your project, use the following method which will return a string containing the HTML needed for the button. Place this HTML in your document wherever you want the button to appear.

Definition

LaunchKey_OAuth::login($color, $size, $length)

Parameters

color:string [blue, light, dark] Login button color theme
size:string [small, medium, large] The width of the button
length:string full, short, mini] The length/style of button
lang:string [en, fr, it, de , es] The language of button

Example

<div class="launchkey-login">
    <?php echo $oauth->login("light", "medium", "short", "en"); ?>
</div>

Login Response

After the user clicks the login button, they will be forwarded to the OAuth endpoint where they'll log in with the Mobile Authenticator as usual. Once the user responds, they will be redirected back to the URL with a login response that you must catch and validate.

If successful, the method will return user, access_token, refresh_token and expires_in. These values will need to be stored in a session or cookie specific to your user for future use. If authorization failed, an error will be returned.

Definition

LaunchKey_OAuth::callback($code)

Parameters

code:string Code to validate it came from the LaunchKey OAuth provider

Returns

Array with the following keys:

access_token:The authenticating element for a user's session
token_type:string "Bearer"
expires_in:int Seconds until expiration
refresh_token:string Used to refresh session and get a new access_token without going through the entire authorization flow again
user:** string** Unique code identifying a specific user; this code will always be the same for that particular User

Note

These values should be stored in a session or cookie specific to your user for future use.

Example

$code = $_GET['code'];
$callback = $oauth->callback($code);

if(count($callback)) {
    if(isset($callback['user'])) {
        //the user hash returned is the value you will want to store and pair with a local system user for future access
        $_SESSION['user'] = $callback['user'];
        $_SESSION['access_token'] = $callback['access_token'];
        $_SESSION['refresh_token'] = $callback['refresh_token'];
        $_SESSION['expires_in'] = $callback['expires_in'];
    }
}

Verify Session Status

Once a user has logged in, you will need to periodically check the status of that user's session to determine whether or not the user has logged out remotely. This can be done using the verify() method.

Definition

LaunchKey_OAuth::verify($access_token)

Parameters

access_token:string User code returned on callback success.

Returns

Boolean value representing that session active state.

Example

$oauth->verify($_SESSION['access_token']);

Refresh The Current Session

Access codes expire after one hour. To obtain a new access code, use the refresh() method.

Definition

LaunchKey_OAuth::refresh($refresh_token)

Parameters

refresh_token:string Refresh code returned from callback success

Returns

Success

On success, and array with the following keys will be returned:

access_token:The authenticating element for a user's session
token_type:string "Bearer"
expires_in:int Seconds until expiration
refresh_token:string Used to refresh session and get a new access_token without going through the entire

Note

These values should be stored in a session or cookie specific to your user for future use.

Failure

On failure, and array with the following keys will be returned:

error:Error message

Example

$oauth->refresh($_SESSION['refresh_token']);
if(isset($refresh['access_token']) && isset($refresh['refresh_token'])) {
    $auth = True;
    $_SESSION['access_token'] = $refresh['access_token'];
    $_SESSION['refresh_token'] = $refresh['refresh_token'];
    $_SESSION['expires_in'] = $refresh['expires_in'];
}

Log Out The User

If a user logs out, you should notify the LaunchKey Platform so your app Service be removed from their Authorization List. This can be done by calling the logout() method.

Definition

LaunchKey_OAuth::logout($access_token)

Parameters

access_token:string User code returned on callback success

Returns

Boolean value representing the success of the call

Example

$oauth->logout($_SESSION['user']);

Additional Security (Optional But Suggested)

Add additional protection to the unique identifier to be stored locally with pbkdf2() function. Returns ***

A hashed string

Definition

LaunchKey_OAuth::pbkdf2($to_hash, $salt = 'provide_your_own_salt_per_hash_and_save_both', $iteration_count = 2048, $algo = 'sha256')

Parameters

to_hash:string The string to be hashed
salt:string (provide_your_own_salt_per_hash_and_save_both) Hash salt. Providing a salt-per-hash is the best practice to maximize security
iteration_count:int (2048) Number of hashing iterations. Should be more than 1000.
algo:string (sha256) Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..). See hash_algos() for a list of supported algorithms.

Example

$oauth->pbkdf2($callback['user'], "random_salt_to_be_saved_with_hash");

User Contributed

LaunchKey links to user contributed code as a resource to its community. LaunchKey does not in any way guarantee or warrant the quality and security of these code bases. User contributed code is supported by the creators. If you do find a link from the site to user contributed code that is malicious or inappropriate in any way, please report that link to LaunchKey immediately and we will investigate the claim. Submit any issue to LaunchKey support at https://launchkey.com./support. ×