Using Snapplify Authentication

This guide describes how to use Snapplify Authentication to enable your application to take actions on behalf of a Snapplify account (Single Sign-On) or access certain data about users’ accounts. We use OAuth 2.0 protocol.

This article is for DEVELOPERS.

Centralised user management for your business, providing instant and convenient access to your services.

Snapplify Authentication allows the Snapplify Reader application to make user authentication requests to your existing subscriber base, enabling users to register and purchase content on your system.



Authentication involves the following steps:

  • Registering your app to obtain a client ID and client secret.
  • Getting a token to specify scopes, or the permissions your app requires.
  • Sending the token in your API request, to authenticate API requests.

 

Registration

To make an application that uses the Snapplify API, you first need to request your application credentials from our team at help@snapplify.com. When requesting this app, you must specify your redirect URI, which is where your users are redirected after being authorised.

Once the application has been created, you will be sent a Client ID and Client Secret.

Client IDs are public and can be shared (e.g. embedded in the source of a Web page).

Client secrets are equivalent to a password for your application and must be kept confidential. Never expose it to users, even in an obscured form.

Because your client secret is confidential, we cannot recover it, so make sure to record it somewhere safe. Also, generating a new client secret immediately invalidates the current one, which might make your API requests fail until your app is updated.

 

Getting tokens

The domain dedicated to Snapplify authentication is auth.snapplify.com.

We support the following authentication flows:

Flow Type

Description

Implicit code flow

Your app does not use a server, such as a client-side JavaScript app or mobile app. This approach does not require a server that must make requests to the API.

Authorisation code flow

Your application uses a server, can securely store a client secret, and can make server-to-server requests.

 

Sending user access tokens

When an API request requires authentication, send the following:

curl -H "Authorisation: Bearer <access token>" https://auth.snapplify.com/userinfo

 

Scopes

When you request authorisation from users, the scope parameter allows you to specify which permissions your app requires. These scopes are tied to the access token you receive on successful authorisation. Without specifying scopes, your app can access only basic information about the authenticated user.

Snapplify currently only supports the “identity“ scope.

 

Getting access tokens

There are two OAuth procedures:

  • The OAuth implicit code flow gets user access tokens.
  • The OAuth authorisation code flow gets user access tokens.

OAuth Implicit Code Flow

  1. Send the user you want to authenticate to your registered redirect URI. Then, an authorisation page will ask the user to sign up or log into Snapplify and allow the user to choose whether to authorize your application/identity system.

Example Request:

GET https://auth.snapplify.com/oauth/authorize

    ?client_id=<your client ID>

    &redirect_uri=<your registered redirect URI>

    &response_type=<type>

    &scope=<space-separated list of scopes>


There are several required and optional query-string parameters:

Required Parameter

Type

Description

client_id

string

Your client ID.

redirect_uri

string

Your registered redirect URI. This must exactly match the redirect URI registered in the prior, Registration step. For example: https://website.com/login

response_type

string

Specifies what information to return. This must be token, to return an access token. The user may be prompted to confirm authorisation once or repeatedly;

scope

string

Space-separated list of scopes.

 

Optional Parameter

Type

Description

state

string

Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.

 

In our example, you request access to a user’s basic information (by specifying the identity scope) and send the user to http://localhost:

GET 'https://auth.snapplify.com/oauth/authorize?response_type=token&client_id=<your client ID>&redirect_uri=http://localhost&scope=identity&state=<your state param>'

 

  1. If the user authorizes your application, the user is redirected to your redirect URL:

https://<your registered redirect URI>#access_token=<an access token>


The access token is in the URL fragment, not the query string, so it will not show up in HTTP requests to your server. URI fragments can be accessed from JavaScript with document.location.hash.
The response includes the state parameter, if it was in your request.

In our example, your user gets redirected to:

https://localhost#access_token=0123456789abcdefghijABCDEFGHIJ

    &scope=identity

    &state=<your state param>

    &token_type=bearer

 

OAuth authorisation Code Flow

  1. Send the user you want to authenticate to your registered redirect URI. Then, an authorisation page will ask the user to sign up or log into Snapplify and allow the user to choose whether to authorize your application/identity system. Use this request:

GET https://auth.snapplify.com/oauth/authorize

    ?client_id=<your client ID>

    &redirect_uri=<your registered redirect URI>

    &response_type=code

    &scope=<space-separated list of scopes>


There are several required and optional query-string parameters:

Required Parameter

Type

Description

client_id

string

Your client ID.

redirect_uri

URL

Your registered redirect URI. This must exactly match the redirect URI registered in the prior, Registration step.

response_type

string

This must be code, causing an authorization code to be returned, which is used later in this procedure. A given user is prompted to confirm authorisation only on the first request.

scope

string

Space-separated list of scopes.

 

Optional Parameter

Type

Description

state

string

Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.


In our example, you request access to a user’s basic information (by specifying the identity scope) and send the user to http://localhost:

GET 'https://auth.snapplify.com/oauth/authorize?response_type=code&client_id=<your client ID>&redirect_uri=http://localhost&scope=identity&state=<your state param>'

 

  1. If the user authorizes your application, the user is redirected to your redirect URI, with an authorisation code:

https://<your registered redirect URI>/?code=<authorisation code>


The OAuth 2.0 authorisation code is a 30-character, randomly generated string. It is used in the next step, a request made to the token endpoint in exchange for an access token.

The response includes the state parameter, if it was in your request.

In our example, your user gets redirected to:

https://localhost/?code=0123456789abcdefghijABCDEFGHIJ

    &scope=identity

    &state=<your state param>

 

  1. On your server, get an access token by making this request:

POST https://auth.snapplify.com/oauth/token

    ?client_id=<your client ID>

    &client_secret=<your client secret>

    &code=<authorisation code received above>

    &grant_type=authorisation_code

    &redirect_uri=<your registered redirect URI>

 

  1. We respond with a JSON-encoded access token. The response looks like this:

{

  "access_token": "<user access token>",

  "refresh_token": "<refresh token>",

  "expires_in": <number of seconds until the token expires>,

  "scope": ["<your previously listed scope(s)>"],

  "token_type": "bearer"

}

 

Code examples

Snapplify implements standard OAuth 1(a) and OAuth 2.0 protocols and as such all standard libraries can be used to integrate. Take a look at the many libraries available to developers oauth.net/code/.

User Info API allows access to basic user information and is used to integrate authentication into your own applications.

The next step requires you to to get the auth token, to make additional authenticated calls.

curl -H 'Accept: application/json' \

-H 'Authorisation: Bearer <Access Token>\

-X GET 'https://auth.snapplify.com/api/userinfo'


The user response would resemble the following:

{
    "id": 123456789,
    "name": "John Doe",
    "given_name": "John",
    "family_name": "Doe",
    "username": "testuser",
    "email": "john@doe.co.za",
    "email_verified": false,
    "picture": "http:// ...",
    "authorities": [
        "ADMIN"
    ]
}

 

Typically you will use this data to link to a user record in your application, for example.

class AuthProfile {
 
  authId:   '1'
  authType: 'snapplify'
  userId:   '<a userid in your application>'

}



Branding guidelines

Usage of the Snapplify sign-in button should be consistent with other sign-in options, with equal prominence and size.



Image

Details

This button needs to be the same height and width as other buttons used for Oauth purposes.

 

👉Learn how to integrate Snapplify Authentication on Wordpress or Moodle.

Need help? Use the live chat in the bottom right corner of your screen or email us at help@snapplify.com.