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.
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:
Each of the parameters are described in the table below.
|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:
|login_url||No||URL where your customer logs into your site. Ex:
|logout_url||No||URL where chargely should redirect your user when they log out. Ex:
|custom_domain||No||If your site is configured with a custom domain, set it here.|
A fully formed URL might look like this:
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.
|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.|
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
|auth -> cust_id||Yes||(Better) This must match the
|auth -> cust_ref||Yes||(Best) This must match the
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:
Chargely requires the 'HS256' algorithm for hashing the token. Tokens hashed with any other algorithm will be rejected.
Chargely SDK for PHP
Chargely provides an :doc:`official SDK for PHP </sdk_php/index>` that greatly simplifies the implementation of SSO.
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.