Single Sign On - Snapper Grape is master

This SSO system assumes that Snapper Grape is master of all user data, and that the client needs to be logged directly in to Snapper Grape. This should only be necessary if you communicate with the API server-to-server, and the end user needs to access Snapper Grape directly at some point, eg. to start an e-course.

See sequence diagram below describing how the SSO system is intended to work.

alt

Single Sign On - third party is master

The Snapper Grape API also supports SSO where a thrid party system is master of user credentials. However, this requires that all user data is present in Snapper Grape. There is no on-the-fly creation of users/persons.

Authentication is done through oAuth2, using simple web token (SWT).

Requests using this form of SSO needs to have a header named "Authorization", with value on the form "SWT ", where is an SWT token. An SWT token is a series of &-separated parameters, just like normal HTTP GET parameters. In addition, a parameter "HMACSHA256" is added, whose value is calculated using the rest of the parameters and a shared secret key. Snapper Grape calculates the HMAC value, and if it matches what was sent, we can log the user into Snapper Grape.

A typical SWT token looks like this:

Issuer=snapper&ExpiresOn=1446648625&username=test@snapper.no&HMACSHA256=dT4XPaBjyM8Lg1s+AG7/oiphpMCkA/ZkNG9nMklAUDQ=

More details on SWT.

"Issuer" and "ExpiresOn" are not required, but if given, they are checked. "Issuer" is checked against a configured parameter, while "ExpiresOn" is checked for expiry.

In order for Snapper Grape to know who is logged in, one of the following parameters must be present:

  • username
  • user_name
  • person_id
  • external_person_id

Alternatively, we can configure Snapper Grape to use corresponding parameter names:

  • api.oauth.user_name_key
  • api.oauth.person_id_key
  • api.oauth.extern_person_id_key

If everything checks out, and a user is found in Snapper Grape, the user should be logged in.

POST /api/login

Description

Logs a user in to Snapper Grape.

Parameters

user_name

String. User name for user trying to log in.

password

String. Password for user trying to log in.

login

Int. Must be set to 1 in order for the underlying security system to log the user in.

forward_url

String. URL to redirect to after successful login. Redirect is not done in this call, but if we are using SSO, the value of forward_url is relayed.

Return:

Single Login object.

Security:

Anyone

GET /api/validate

Description

Validate if user has a valid session in Snapper Grape. For use in SSO with third-party system, where Snapper Grape is master. Note that this is not a normal JSON request, it actually redirects the client, in order to do make SSO happen.

Parameters

user_name

String. User name of user in question.

hash

String. Short-lived hash, delivered by the login call.

forward_url

String. URL to forward to after successful negotiation.

Return

Redirect or error object

Security

Anyone

GET /api/logout

Description

Log out of Snapper Grape.

Parameters

forward_url

String. URL to forward to after successful logout. Simply relayed to the output.

Return

Single Logout object.

Security

Anyone, but only makes sense when logged in.

POST /api/forgot_password

Description

Resets a user's password

Parameters

identification

String. Identification of user to change password for. Can be user name, email or mobile.

Return:

Simple object containing two attributes: valid (boolean) and message (String)

Security:

Anyone