Single sign-on

These methods will help you perform all necessary actions for implemeneting SSO within your application.

Configuration

To get started with SSO you’ll first need to create a configuration file and store it safely on your server. Be sure to have your public/private key pair handy.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
<?php

/**
 * PHP array based configuration.
 *
 * Store this file in a safe place. As with any configuration file you should ensure that your web server will not
 * expose your secrets.
 */

return array(
    // always populate a default_profile
    'default_profile' => array(
        /**********************
         * Core configuration *
         **********************/
        // (required) The subdomain of your site.
        'subdomain'   => 'yourcompany',
        // (required) Public key from your API configuration.
        'public_key'  => '{{PROD_PUBLIC_KEY}}',
        // (required) Private key from your API configuration.
        'private_key' => '{{PROD_PRIVATE_KEY}}',
        // (optional) Set hostname for dev purposes.
        //'hostname' => 'chargelyapp.com',
        // (optional) Set protocol for dev purposes.
        //'protocol' => 'https://',
        // (optional) The custom domain for your site, if configured
        //'custom_domain' => null

        /*********************
         * SSO configuration *
         *********************/
        'sso'         => array(
            // (required) Fully qualified URL where your customer should login.
            // This is where your customer will be redirected if there are any errors during login.
            'login_url'  => 'https://yourcompany.com/login',
            // (optional) Fully qualified URL where your customer will be redirected after clicking "logout" within Chargely.
            'logout_url' => 'https://yourcompany.com/logout'
        )
    ),

    /**
     * Additional profile names.
     *
     * NOTE: You do not need to use these specific profile names. Simply adapt them to our environment and adjust your
     * Client::factory(); calls.
     */
    'prod'            => array(
        'subdomain'   => 'yourcompany',
        'public_key'  => '{{PROD_PUBLIC_KEY}}',
        'private_key' => '{{PROD_PRIVATE_KEY}}',
        'sso'         => array(
            'login_url'  => 'https://yourcompany.com/login',
            'logout_url' => 'https://yourcompany.com/logout'
        )

    ),
    'stage'           => array(
        'subdomain'   => 'stage-yourcompany',
        'public_key'  => '{{STAGE_PUBLIC_KEY}}',
        'private_key' => '{{STAGE_PRIVATE_KEY}}',
        'sso'         => array(
            'login_url'  => 'https://yourcompany.com/login',
            'logout_url' => 'https://yourcompany.com/logout'
        )

    ),
    'dev'             => array(
        'subdomain'   => 'dev-yourcompany',
        'public_key'  => '{{DEV_PUBLIC_KEY}}',
        'private_key' => '{{DEV_PRIVATE_KEY}}',
        'sso'         => array(
            'login_url'  => 'https://yourcompany.com/login',
            'logout_url' => 'https://yourcompany.com/logout'
        )
    )
);

Note that you can configure multiple environments such as dev, stage, prod to simplify your development process.

Creating a client

Once your configuration file is in place and stored safely on your server, you are ready to create a client instance. There are several invocations available to suit your development process.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<?php
require_once '/path/to/project/vendor/autoload.php';

use \Chargely\Sso\Jwt\Client;

/**
 * The easiest way to configure an SSO client is by storing your configuration in a file.
 */
$client = Client::factory('../config/chargely.php');        // 'default_profile' will be used
$client = Client::factory('../config/chargely.php', 'dev'); // Load the 'dev' profile

/**
 * You can also provide configuration explicitly in your code.
 *
 * This method is useful for rapid development or integrating with your existing configuration systems. However, be
 * careful to not hard-code your credentials inside of your applications. Hard-coding your credentials can be dangerous,
 * because it is easy to accidentally commit your credentials into an SCM repository, potentially exposing your
 * credentials to more people than intended. It can also make it difficult to rotate credentials in the future.
 */
$client = Client::factory(
    array(
        'subdomain'  => 'mycompany',
        'public_key' => '{{PUBLIC_KEY}}',
        'private_key' => '{{PRIVATE_KEY}}'
    )
);

Refresh token

This method will create the HTTP response needed for a refresh token endpoint.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<?php
require_once '/path/to/project/vendor/autoload.php';

use \Chargely\Sso\Jwt\Client;

$client = Client::factory('../config/chargely.php');

/**
 * Presumably your application has a User object that gives you access to certain
 * properties such as logged-in status and e-mail address.
 *
 * Here we will just use "stdClass" to represent the User object in your system.
 */
$user = new stdClass();

// Never give a valid refresh token to users who are not authenticated with your system.
if ($user->isLoggedIn) {
    // (Good) Set user e-mail
    $client->setEmail($user->email);
    // (Better) Set Chargify customer ID if you have it stored in your system.
    $client->setCustId($user->chargify_customer_id);
    // (Best) Set Chargify customer reference if you have it stored in Chargify.
    $client->setCustRef($user->id);

    // Send refresh token to browser and exit.
    $client->sendRefreshToken(200);
    exit();
} else {
    // the user is not authorized.
    $client->sendRefreshToken(401);
    exit();
}

Login URL

This method will generate a one-time use single sign-on login URL.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
<?php
require_once '/path/to/project/vendor/autoload.php';

use \Chargely\Sso\Jwt\Client;

$client = Client::factory('../config/chargely.php');

/**
 * Identify your customer
 *
 * Use only ONE of these options. If multiple options are given, the option
 * with highest precedence level will be used.
 */

/**
 * Set customer email (Good)
 * Precedence: 3
 *
 * This must match the "email" field returned from the Chargify Customer API.
 * @link https://docs.chargify.com/api-customers
 */
$client->setEmail('foo@bar.com');

/**
 * Set customer ID (Better)
 * Precedence: 2
 *
 * This must match the "id" field returned from the Chargify Customer API.
 * @link https://docs.chargify.com/api-customers
 */
$client->setCustId('12345');

/**
 * Set customer reference (Best)
 * Precedence: 1
 *
 * This must match the "reference" field returned from the Chargify Customer API.
 * @link https://docs.chargify.com/api-customers
 */
$client->setCustRef('12345');

echo "\n";

/**
 * Create URL for SSO authentication
 */
$url = $client->url('/dashboard');

echo "Login URL: $url\n\n";