This article includes the following topics:

OAuth 2 Authorization

EduTone 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 EduTone’s OAuth service:

  • Login with EduTone is when a Service Provider (your application) allows users to authenticate using EduTone’s OAuth service. The District ID can be submitted when redirecting a user to EduTone’s SSO Platform to eliminate the need for a user to select organization.
  • EduTone initiated SSO to a Service Provider is when a user requests access to your service from EduTone’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 EduTone’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 EduTone can include that value as a parameter). An alternative simplified workflow can be considered as well. For example, EduTone 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 EduTone. 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.edutone.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.edutone.com",
  "aud": "oauth.edutone.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.edutone.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@edutone.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.edutone.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@edutone.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