Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
138 lines (106 sloc) 9.79 KB

Introduction

Single sign-on (SSO) is a mechanism that allows you to authenticate users in your systems and subsequently tell Chargely that the user has been authenticated. The user is then allowed to access Chargely without being prompted to enter separate login credentials.

At the core of single sign-on is a security mechanism that allows Chargely to trust the login requests it gets from your systems. Chargely only grants access to the users that have been authenticated by you. Chargely SSO relies on a technology called JSON Web Token (JWT) for securing the exchange of user authentication data.

Read more about JSON Web Token

The SSO authentication process

Chargely's SSO feature is very flexible and there are many possible authentication flows you could implement. Regardless of the authentication flow, your users will ultimately be logged into Chargely by sending them to a :ref:`specially generated login link <sso_login_url>`.

Generating the login link

The SSO login link is generated in the following format:

https://{{subdomain}}.chargelyapp.com/sso/jwt/login?public_key={{public_key}}&token={{token}}&return_to={{return_to}}&login_url={{login_url}}&logout_url={{logout_url}}

Each of the parameters are described in the table below.

Parameter Required Description
subdomain Yes Subdomain of your Chargely site.
public_key Yes Public key from your Chargely site. :doc:`(read more) <enabling>`
token Yes Generated token. :ref:`(read more) <generate_token>`
return_to No Internal Chargely page to send your customer to after logging in. Ex: /dashboard
login_url No URL where your customer logs into your site. Ex: https://yourcompany.com/login Chargely will redirect the user here if there are any errors with the single sign-on process.
logout_url No URL where chargely should redirect your user when they log out. Ex: https://yourcompany.com/logout
custom_domain No If your site is configured with a custom domain, set it here.

A fully formed URL might look like this:

https://yourcompany.chargelyapp.com/sso/jwt/login?public_key=Ng2t1S0khsz8uaRpa4yqmAu874IyuL9N&token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIydzdYRkRRZEdjWGt4OXhJTnV1ODBYWmdSNGFaS1JxRiIsImlhdCI6MTQyOTIzODczNCwiYXVkIjoiLSIsImN1c3RfZW1haWwiOiJjaGFyZ2VseV8xMzM0NTAyNjUzQG1haWxpbmF0b3IuY29tIn0.-C_ze2TLFODNmAnxhgHJQIpE4lF4_R2Jv8cKdYLg73I&return_to=&login_url=https%3A%2F%2Fyourcompany.com%2Flogin&logout_url=https3A%2F%2Fyourcompany.com%2Flogout

Generating the SSO token

In order to generate the JWT token, your application needs to send several required parameters to Chargely as a hash (hash table, dictionary). The parameters are described in the table below.

Parameter Required Description
Core JWT claims
jti Yes "JWT ID" A unique, random identifier for the token. Tokens can be used one-time only and duplicates will be denied access.
iat Yes "Issued At" A Unix timestamp which identifies the time at which the token was issued. Tokens will automatically expire 5 minutes after this time. Chargely allows up to 2 minutes of clock skew, so make sure your server time is accurate.

Authentication Parameters

Use one of these fields to uniquely identify your customer. If multiple options are given, the option with highest precedence level will be used.

auth Yes A dictionary of field(s) to uniquely identify your customer.
auth -> cust_email Yes (Good) This must match the email field returned from the Chargify Customer API. https://docs.chargify.com/api-customers
auth -> cust_id Yes (Better) This must match the id field returned from the Chargify Customer API. https://docs.chargify.com/api-customers
auth -> cust_ref Yes (Best) This must match the reference field returned from the Chargify Customer API. https://docs.chargify.com/api-customers

Most JWT implementations take a hash and a secret, and return a plain string token. For context, here's an example in PHP using the firebase/php-jwt library:

Note

Chargely requires the 'HS256' algorithm for hashing the token. Tokens hashed with any other algorithm will be rejected.

:doc:`Learn how to obtain a Public Key and Private Key for SSO.<enabling>`

Chargely SDK for PHP

Chargely provides an :doc:`official SDK for PHP </sdk_php/index>` that greatly simplifies the implementation of SSO.

Other languages

The actual JWT implementation is straightforward and most modern languages have libraries available. Unfortunately we do not have code samples for other languages at this time. Please get in touch for assistance with your implementation.