Integrating Snapplify Access for Single Sign On (SSO)

This article is for DEVELOPERS.

Snapplify Access enables users to get instant and convenient access to your services. With Snapplify Access, signing in is as simple as clicking a button. SSO is part of the basic offering, for more complex Roster data, you will need to upgrade to a paid version of Access. 

Learn more about the benefits of Snapplify Access here.

Setting up SSO 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.

Your Client Secret is confidential, which means 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 Access is auth.snapplify.com.

We support the following authentication flows:

Sending user access tokens

When an API request requires authentication, send the following:

curl -H "Authorisation: Bearer <access token>" https://auth.snapplify.com/api/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 supports the following scopes:

On Access basic

'identity'.
This scope is available by default, and allows the users basic identity information.

On Access Professional or Enterprise

'teacher'

This scope is used to determine if a user is a teacher within the Snapplify platform. It also includes additional information about the school.

'learner'

This scope is used to identify if a user is a learner within the Snapplify environment. It also includes additional information about the school, grade and classes.

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

Step 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 authorise your application/identity system or not.

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:

In our example, you request access to a user’s basic information (by specifying the 'identity' scope) and send the user to 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>'

Step 2:

If the user authorises your application, the user is redirected to your redirect URL:

https://<your registered redirect URI>#access_token=<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#access_token=0123456789abcdefghijABCDEFGHIJ
    &scope=identity
    &state=<your state param>
    &token_type=bearer

OAuth authorisation code flow

Step 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 in to Snapplify and allow the user to choose whether to authorise 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:

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>'

Step 2:

If the user authorises 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 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>

POST https://auth.snapplify.com/oauth/token
    ?client_id=<your client ID>
    &client_secret=<your client secret>
    &code=<authorisation code received above>
    &grant_type=authorization_code
    &redirect_uri=<your registered redirect URI>

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 Snapplify Access into your own applications.

The next step requires you 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'

Depending on which scope was requested, and allowed, you would get different information.

Example with only the 'identity' scope.

{
    "id": 1,
    "email": "placeholder@email.com",
    "name": "John Doe",
    "username": "JohnDoe25@",
    "given_name": "John",
    "family_name": "Doe",
    "picture": "https://via.placeholder.com/96",
    "mobileNumber": null,
    "email_verified": false,
    "emailVerified": false,
    "authorities": []
}

{
  "teacher": true,
  "teacher_verified": true,
  "school": {
      "id": ,
      "name": "School Name",
      "url": "https://schoolname.snapplify.com/",
      "createdDate": "2017-11-16T11:48:09.000Z",
      "updatedDate": "2023-05-17T07:19:20.000Z"
  },
  "grade": {
      "id": 11,
      "name": "Grade 10",
      "createdDate": "2018-10-25T12:51:02.000Z",
      "updatedDate": "2022-10-08T20:05:57.000Z"
  },
  "class": [
      {
          "id": 11377,
          "name": "Grade 10 English Class",
          "createdDate": "2022-03-29T09:47:34.000Z",
          "updatedDate": "2022-03-29T09:47:34.000Z",
          "grade": {
              "id": 11,
              "name": "Grade 10",
              "description": "Grade 10",
              "createdDate": "2018-10-25T12:51:02.000Z",
              "updatedDate": "2022-10-08T20:05:43.000Z"
          }
      }
  ]
}

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.

You can also integrate Snapplify Access on Wordpress or Moodle for SSO.

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