This article includes the following topics:

• OAuth 2 Authorization
  • Resource Owner Authorization
    • Authorization Code Grant
      • Authorization Request
      • Access Token Request
    • Implicit Grant
  • Service Level Authorization
  • Authorization Token Structure
  • Refresh Token
• Access to User Details
• Log Out

OAuth 2 Authorization

School Messenger provides its institutional tenants with the web-based Single Sign-On (SSO) Platform. Each tenant can have its custom domain name (e.g. schoolA.edu, myschool.edu.ca, etc).

There are two distinct scenarios for integration that rely on School Messenger’s OAuth service:

• Login with SchoolMessenger is when a Service Provider (your application) allows users to authenticate using School Messenger’s OAuth service. The District ID can be submitted when redirecting a user to School Messenger’s SSO Platform to eliminate the need for a user to select organization.
• SchoolMessenger initiated SSO to a Service Provider is when a user requests access to your service from School Messenger’s SSO Platform (being already authenticated into the SSO Platform). In a typical workflow, the Service Provider would provide an endpoint that redirects browser agent back to School Messenger’s OAuth service (see Authorization Request). This redirect should use the hostname of the originating SSO request (e.g. schoolA.edu or myschool.edu.ca etc). The Service Provider should derive the value of the hostname from the SSO request (either using the Referrer header, or School Messenger can include that value as a parameter). An alternative simplified workflow can be considered as well. For example, School Messenger can start SSO by sending either an OAuth code or an OAuth access token.

Resource Owner Authorization

Authorization Code Grant

Authorization Request

ENDPOINT	GET /oauth/auth?response_type={responseType}&client_id={clientId}&redirect_uri={redirectUri}
DESCRIPTION	The endpoint to authenticate a user.

 

Parameters:

PARAMETER	MODE	TYPE	DESCRIPTION
response_type	required	String	Type of response (should be: code).
client_id	required	String	OAuth client identifier registered with SSO Platform.
redirect_uri	optional	String	URI for redirection after successful authentication. This value should match the value registered in SSO Platform.
state	optional	String	This parameter will be returned back to a requester after successfully authenticating a user.
district_id	optional	String	Institutional identifier issued by School Messenger. Eliminates the need for a user to select an organization.

 

Sample request: (response_type=code)

https://{hostname}/oauth/auth?response_type=code&client_id={clientId}&redirect_uri=https://{partner’s_hostname}

Response (after successful authentication): Redirect to redirect_uri (as provided in the request)

Redirect to https://{partner’s_hostname}/?code=GmUGCD&state={state}

back to top

Access Token Request

ENDPOINT	POST /oauth/token?grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}
DESCRIPTION	Endpoint from which to obtain the access_token.

 

The request must contain WWW BASIC authorization with both the client_id and client secret key in the request header: ‘Authorization’: ‘Basic {data}’ where data = Base64.encode(‘{client_id}:{client secret}’). For example:

POST https://{hostname}/oauth/token
BODY: grant_type=authorization_code&code=GmUGCD&redirect_uri=https://{partner’s_hostname}/
Authorization Header: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0

Response:

{
  "access_token": "...",
  "token_type": "bearer",
  "refresh_token": "...",
  "expires_in": 43199,
  "scope": "user.profile",
  "auth_token": "..."
}

FIELD	TYPE	DESCRIPTION
access_token	String	OAuth 2.0 Access Token
token_type	String	Type of token (always 'bearer.)
expires_in	Integer	Expiration time in seconds.
scope	String	Optional list with scopes that define granted data access.
state	String	Value provided in the request.
auth_token	String	JWT Token with with brief information about the user. The signature is created with a secret key, per (opens an external site in a new tab/window).
refresh_token	String	OAuth 2.0 Refresh Token. Valid for 30 days (by default).

back to top

Implicit Grant

ENDPOINT	GET /oauth/auth?response_type={responseType}&client_id={clientId}&redirect_uri={redirectUri}
DESCRIPTION	Endpoint to authenticate a user.

 

PARAMETER	MODE	TYPE	DESCRIPTION
response_type	required	String	Response type (should be 'token').
client_id	required	String	Client identifier registered on the server.
redirect_uri	optional	String	The uri for redirection after successful authentication. (The value gets validated if is registered in the SSO Platform.)
state	optional	String	This parameter will be returned to the requester after successful user authentication.
district_id	optional	String	Institutional identifier issued by SSO Platform.

Example:

https://{hostname}/oauth/auth?response_type=token&client_id={clientId}&redirect_uri=https://{partner’s_hostname}

Response: (after successful authentication; redirect to redirect_uri, as provided in the request)

Redirect to https://{partner’s_hostname}#access_token=...&token_type=bearer&expires_in=43199&scope={scopes} &auth_token=...

FIELD	TYPE	DESCRIPTION
access_token	String	OAuth 2.0 Access Token
token_type	String	Token type, which is always 'bearer.'
expires_in	Integer	Expiration time in seconds.
scope	String	Optional list of scopes that define granted data access.
state	String	Value provided in the request.
auth_token	String	Optional JWT Token with with brief information about the user. The signature is created with a secret key, per http://tools.ietf.org/html/draft-ietf-oauth-jwt-bearer-07 (link opens an external site in a new browser tab/window).

back to top

Service Level Authorization

Where applications need to obtain an access_token without user interaction, the application should provide signed JWT, as described at http://tools.ietf.org/html/draft-ietf-oauth-jwt-bearer-07 (link opens an external site in a new browser tab/window).

ENDPOINT	POST /oauth/token
DESCRIPTION	The endpoint returns the access_token.

 

PARAMETER	MODE	TYPE	DESCRIPTION
auth_token	required	String	The signed JWT
grant_type	required	String	Must be 'jwt-bearer.'

 

JWT structure:

FIELD	MODE	DESCRIPTION
iss	required	The issuer of the secret key. Must be "oauth.School Messenger.com"
aud	required	The hostname where JWT will be verified.
sub	required	The client_id issued for the secret key by SSO Passport.
exp	required	The time window in seconds during which the token is valid.
iat	required	The time in seconds from 1 Jan 1970 GMT when JWT was created.
pid	required/optional	The identifier of the user in SSO Passport for whom the access_token is to be created. This should be provided for an existing user if the prn value is not provided.
prn	required/optional	The email of the user for whom the access_token is to be created. Should be provided for existing user if the pid value is not provided.
first	optional	First name of the user.
last	optional	Last name of the user.
district	optional	Identifier of the district associated with the user.
school	optional	Identifier of the school associated with the user.
role	optional	Role of the user.
type	optional	Users type, which will be one of the following values: “district_admin”, “school_admin”, ”teacher ”, ”student”, “contact”
external_id	optional	Identifier of the user in the external system (SIS/LMS etc)
grade	optional	Grade of the student.
last_modified	optional	The time in seconds from 1 Jan 1970 GMT when the user attributes were modified/.

Response:

{
  "access_token": "...",
  "token_type": "bearer",
  "refresh_token": "...",
  "expires_in": 43199,
  "scope": "user.profile",
  "auth_token": "..."
}

 

FIELD	TYPE	DESCRIPTION
access_token	String	OAuth 2.0 access token.
token_type	String	Type of token (always 'bearer').
expires_in	Integer	Expiration time in seconds.
scope	String	Optional list with scopes that define granted data access.
auth_token	String	Optional JWT Token with with brief information about the user. The signature is created with the secret key per http://tools.ietf.org/html/draft-ietf-oauth-jwt-bearer-07 (link opens an external site in a new browser tab/window).
refresh_token	String	OAuth2 Refresh Token. Valid for 30 days (by default)

 

back to top

Authorization Token Structure

New attributes can be added to the JSON response. Client side implementation should not rely on the order of the attributes.

JWT's claims:

{

  "iss": "oauth.School Messenger.com",
  "aud": "oauth.School Messenger.net",
  "sub": cba90bc1-941e-4247-hj87-288aca16507b,
  "exp": 43200,
  "iat": 1387459509775,
  "district": "4dff2226-2a51-56tg-a9ef-82c529b02000",
  "school": "332628ca-bdbc-4291-3eds-f4c31a05a032",
  "type": "student"
}

FIELD	TYPE	DESCRIPTION
iss	String	Unique identifier for the entity that issued the JWT - always “oauth.School Messenger.com”.
sub	GUID	Internal unique identifier of the user.
aud	String	Identifies the authorization server as an intended audience. This is the hostname that processed the request.
exp	Integer	Time window in seconds during which the JWT can be used
iat	Integer	The time at which the JWT was issued (seconds from 1 Jan 1970)
district	GUID	The unique id of user’s district in SSO Platform
school	GUID	The unique id of user’s organization in SSO Platform
type	String	User's type - one of the following values: “district_admin”, “school_admin”, ”teacher”, ”student”, “contact”
last_modified	BigInteger	The time in seconds from 1 Jan 1970 GMT when attributes of the user were modified (reserved for future use).

back to top

Refresh Token

ENDPOINT	POST /oauth/token
DESCRIPTION	The endpoint returns the access_token.

The request must contain WWW BASIC authorization with both the client_id and client secret key in the request header: ‘Authorization’: ‘Basic {data}’ where data = Base64.encode(‘{client_id}:{client secret}’).

FIELD	TYPE	DESCRIPTION
refresh_token	required	String	Refresh token value.
grant_type	required	String	Must be 'refresh_token.'

 

Response:

{
  "access_token": "...",
  "token_type": "bearer",
  "refresh_token": "...",
  "expires_in": 43199,
  "scope": "user.profile",
  "auth_token": "..."
}

FIELD	TYPE	DESCRIPTION
access_token	String	Token value that can be included in API requests as either a parameter “access_token” or as header “Authorization” (per OAuth 2.0 specification).
refresh_token	String	OAuth 2.0 Refresh Token
token_type	String	Always 'bearer.'
expires_in	Integer	Time window in seconds diring which the access_token is valid.
auth_token	String	Optional JWT Token with with brief information about the user. The signature is created with a secret key, per (opens an external site in a new tab/window).
scope	String	An optional list of scopes that define granted data access.

 

back to top

Access to User Details

New attributes can be added to JSON response. Client side implementation should not rely on the order of the attributes.

Additional data related to a user account (e.g. information about schools/sections/ students related to a teacher account) are available through the Data API (opens a new article).

ENDPOINT	POST /services/v1.4/users/me
DESCRIPTION	The endpoint returns identity information for a user account. The access token needs to be supplied in the authorization header per RFC 6750.

 

Response:

{
  "data":{
    "district":"4dff2226-er45-48c5-a9ef-82c529b02000",
    "school":"332628ca-fghj-4291-8ddd-f4c31a05a032",
    "id":"cba90bc1-941e-4247-uj89-288aca16500b",
    "type":"student",
    "email":"test@School Messenger.org",
    "first":"First",
  "last":"Last"
  }
}

FIELD	TYPE	DESCRIPTION
district	GUID	Identifier of the district associated with the user.
school	GUID	Identifier of the school associated with the user.
id	GUID	Identifier of the user in the SSO Platform.
type	String	User's type, which must be one of the following values: “district_admin”, “school_admin”, ”teacher ”, ”student”, “student_contact”.
email	String	Email of the user.
first	String	First name of the user.
last	String	Last name of the user.
last_modified	BigInteger	The time in seconds from 1 Jan 1970 GMT when attributes of the user were modified (reserved for future use).

Sample Request:

GET /services/v1.4/users/me HTTP/1.1
Host: nost.School Messenger.net
Authorization: Bearer mF_9.B5f-4.1JqM

Response:

{
  "data": {
    "district":"4dff2226-er45-48c5-a9ef-82c529b02000",
    "school":"332628ca-fghj-4291-8ddd-f4c31a05a032",
    "id":"cba90bc1-941e-4247-uj89-288aca1650bb",
    "type":"student",
    "email":"test@School Messenger.org",
    "first":"First",
    "last":"Last"
  }

}

back to top

Log Out

If access to your service was by means of Single Sign-on from SSO Passport, then the recommended method of handling logouts from your service is to navigate a user back to SSO Passport. An endpoint for logging a user out from SSO Passport is available upon request.

back to top