API Guide - eSD GURU API

Overview

The eSD GURU API (Application Programming Interface) provides a standard way for authorized third party applications to securely obtain data from, and, in select cases, write data back to, the eSD® Student Management System on behalf of a user or vendor. Utilizing modern RESTful approaches, Open ID Connect, and OAuth 2.0, eSD® partners can access a variety of data based on the access rights defined by each district, including school, staff, student, course, class roster, grade reporting, and attendance information.

OpenID Connect

eSchoolData's OAuth 2.0 APIs can be used for both authentication and authorization. This document describes our OAuth 2.0 implementation for authentication, which conforms to the OpenID Connect specification. The documentation found in Using OAuth 2.0 to Access eSchoolData APIs also applies to this service. If you want to explore this protocol interactively, we recommend the eSchoolData OAuth 2.0 API Explorer.

Setting up OAuth 2.0

Before your application can use eSchoolData's OAuth 2.0 authentication system for user login, you must complete the following steps:

Obtain OAuth 2.0 credentials

eSchoolData districts must authorize access to the eSD GURU API by provisioning accounts for approved vendors. Once an account has been created for your application, the district will provide you with a Client ID and Client Secret, which will be needed to access the eSD GURU API website and developer tools, authenticate users, and gain access to the API. For future reference, your application’s Client ID and Client Secret can be accessed from the My Account page within the eSD GURU API website.
Set a redirect URI

The redirect URI determines the destination where eSchoolData sends responses to your application’s authentication requests. To define your redirect URI, navigate to the My Account page within the eSD GURU API website and enter the destination in the corresponding field.
Authenticating the user

In order to authenticate a user, you must obtain an ID token and validate it. ID tokens are a standardized feature of OpenID Connect designed for use in sharing identity assertions on the Internet.

The most commonly used approaches for authenticating a user and obtaining an ID token are called the server flow and the implicit flow. The server flow allows the back-end server of an application to verify the identity of the person using a browser or mobile device. The implicit flow is used when a client-side application (typically a JavaScript app running in the browser) needs to access an API directly rather than via its back-end server.

Authorization/Authentication Endpoint

The authorization endpoint can be used to request either access tokens or authorization codes (implicit and authorization code flow). You either use a web browser or a web view to start the process.

Supported Parameters

client_id (required)
- identifier of the client
redirect_uri (required)
- must exactly match one of the allowed redirect URIs for that client
response_type (required)
- code requests an authorization code
- token requests an access token (only resource scopes are allowed)
- id_token token requests an identity token and an access token (both resource and identity scopes are allowed)
response_mode (optional)
- form_post sends the token response as a form post instead of a fragment encoded redirect
state (recommended)
- idsrv will echo back the state value on the token response, this is for correlating request and response
nonce (required for identity tokens using implicit flow)
- idsrv will echo back the nonce value in the identity token, this is for correlating the token to the request)
prompt (optional)
- none no UI will be shown during the request. If this is not possible (e.g. because the user has to sign in or consent) an error is returned
- login the login UI will be shown, even if the user has a valid session
login_hint (optional)
- can be used to pre-fill the username field on the login page
max_age (optional)
- if the user's logon session exceeds the max age (in seconds), the login UI will be shown
acr_values (optional)
- allows to pass additional authentication related information to the user service - there are also values with special meaning:
  - idp:name_of_idp bypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration)
  - tenant:name_of_tenant can be used to pass a tenant name to the user service

Example

(URL encoding removed for readability)

GET /v1/auth/authorize?client_id=client1&response_type=id_token token&redirect_uri=https://myapp/callback&state=abc&nonce=xyz

Token Endpoint

The token endpoint can be used to programmatically request or refresh tokens (resource owner password credential flow, authorization code flow and client credentials flow).

Supported Parameters

grant_type (required)
- authorization_code (three-legged), client_credentials (two-legged), refresh_token
sub (allowed for client credentials grant type)
- can be used to request access on behalf of the user
redirect_uri (required for code grant type)
code (required for code grant)
acr_values (allowed for password grant type to pass additional information to user service)
- there are values with special meaning:
  - idp:name_of_idp bypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration)
  - tenant:name_of_tenant can be used to pass extra information to the user service
refresh_token (required for refresh token grant)
client_id (either in the post body, or as a basic authentication header)
client_secret (either in the post body, or as a basic authentication header)

Authentication

All requests to the token endpoint must be authenticated - either pass client id and secret via Basic Authentication or add client_id and client_secret fields to the POST body.

When providing the client_id and client_secret in the Authorization header it is expected to be:

client_id:client_secret
Base64 encoded

var clientId = "...";
var clientSecret = "...";
var encoding = Encoding.UTF8;
var credentials = string.Format("{0}:{1}", clientId, clientSecret);
var headerValue = Convert.ToBase64String(encoding.GetBytes(credentials));

Example

(Form-encoding removed and line breaks added for readability)

POST /v1/auth/token Authorization: Basic abcxyz
                    grant_type=authorization_code&
                    code=hdh922&
                    redirect_uri=https://myapp.com/callback

UserInfo Endpoint

The UserInfo endpoint can be used to retrieve identity information about a subject. It requires a valid access token with at least the 'openid' scope.

Example

GET /v1/auth/userinfo Authorization: Bearer <access_token>

HTTP/1.1 200 OK
                    Content-Type: application/json
                    {
                       "sub": "248289761001",
                       "name": "Bob Smith",
                       "given_name": "Bob",
                       "family_name": "Smith",
                       "role": [
                           "user",
                           "admin"
                       ]
                    }

Discovery Endpoint

The discovery endpoint can be used to retrieve metadata about IdentityServer - it returns information like the issuer name, key material, supported scopes etc.

Example

GET /.well-known/openid-configuration

Logout Endpoint

Redirecting to the logout endpoint clears the authentication session and cookie.

You can pass the following optional parameters to the endpoint:

id_token_hint
- The id_token that the client acquired during authentication. This allows bypassing the logout confirmation screen as well as providing a post logout redirect URL
post_logout_redirect_uri
- A URI that IdentityServer can redirect to after logout (by default a link is displayed). The URI must be in the list of allowed post logout URIs for the client.

/v1/auth/endsession?id_token_hint=...&post_logout_redirect_uri=https://myapp.com

Token Revocation

This endpoint allows revoking access tokens (reference tokens only) and refresh token. It implements the token revocation specification (RFC 7009).

Supported parameters:

token (required)
- the token to revoke
token_type_hint
- either access_token or refresh_token

Requests must be authenticated using one of the supported client authentication methods.

Example:

POST /v1/auth/revoke HTTP/1.1
                        Host: api.example.com
                        Content-Type: application/x-www-form-urlencoded
                        Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
                        token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token

Access token validation endpoint

The access token validation endpoint can be used to validate reference tokens. It can be also used to validate self-contained JWTs if the consumer does not have support for appropriate JWT or cryptographic libraries.

Example:

GET /v1/auth/accesstokenvalidation?token=<token>

A successful response will return a status code of 200 and the associated claims for the token. An unsuccessful response will return a 400 with an error message.

It is also possible to pass a scope that is expected to be inside the token:

GET /v1/auth/accesstokenvalidation?token=<token>&expectedScope=calendar

Identity Token Validation Endpoint

The identity token validation endpoint can be used to validate identity tokens. This is useful for clients that don't have access to the appropriate JWT or crypto libraries (e.g. JavaScript).

The identity token is encrypted using HMACSHA256. In order to decrypt the token, you will need to retrieve the Signing Key, which is available from the My Account page.

Example

GET /v1/auth/identitytokenvalidation?token=<token>&client_id=<expected_client_id>

A successful response will return a status code of 200 and the associated claims for the token. An unsuccessful response will return a 400 with an error message.

{
    "nonce": "nonce",
    "iat": "1413203421",
    "sub": "88421113",
    "amr": "password",
    "auth_time": "1413203419",
    "idp": "idsrv",
    "iss": "https://esdguruapi.eschooldata.com",
    "aud": "implicitclient",
    "exp": "1413203781",
    "nbf": "1413203421"
}

Using OAuth 2.0 to Access eSchoolData APIs

eSchoolData APIs use the OAuth 2.0 protocol for authentication and authorization. eSchoolData supports common OAuth 2.0 scenarios such as those for web server, installed, and client-side applications.

Before your application can use the eSD GURU API, you must authenticate using the following steps:

Obtain OAuth 2.0 credentials

Before your application can access data via the eSD GURU API, it must obtain an access token. Using the client credentials, send a request for an access token to the eSchoolData Authorization Server. There are several ways to make this request, and they vary based on the type of application you are building. For example, a JavaScript application might request an access token using a browser redirect to eSD GURU, while an application installed on a device that has no browser uses web service requests.
Obtain an access token from the eSchoolData Authorization Server

Before your application can access data via the eSD GURU API, it must obtain an access token. Using the client credentials, send a request for an access token to the eSchoolData Authorization Server. There are several ways to make this request, and they vary based on the type of application you are building. For example, a JavaScript application might request an access token using a browser redirect to eSD GURU, while an application installed on a device that has no browser uses web service requests.

Some requests require an authentication step where the user logs in with their eSchoolData account. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent. If the user grants the permission, the eSchoolData Authorization Server sends your application an access token or an authorization code that your application can use to obtain an access token. If the user does not grant the permission, the server returns an error.
Send the access token to an API

After your application obtains an access token, send the token to the eSD GURU API in an HTTP authorization header. Access tokens are valid only for the set of operations and resources permitted for the corresponding user account.
Refresh the access token, if necessary

Access tokens have limited lifetimes. If your application needs access to the eSD GURU API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens.

For requests using OAuth, your application can make up to 3,000 requests per hour. The returned HTTP headers of any eSD GURU API request will indicate your application’s current rate status, including the date, rate limit per hour, minute and second, hour, minute, and second that the rate limit resets, and remaining requests permitted for the hour, minute, and second.

Rate Limit

For requests using OAuth, your application can make up to 3,000 requests per hour. The returned HTTP headers of any eSD GURU API request will indicate your application’s current rate status, including the date, rate limit per hour, minute and second, hour, minute, and second that the rate limit resets, and remaining requests permitted for the hour, minute, and second.

{
    "date": "Mon, 27 Jul 2015 18:07:10 GMT",
    "x-ratelimit-reset-minute": "1438020490",
    "x-ratelimit-limit-second": "5",
    "x-ratelimit-reset-hour": "1438024030",
    "x-powered-by": "eSchoolData GURU",
    "x-ratelimit-remaining-second": "4",
    "x-ratelimit-reset-second": "1438020431",
    "content-type": "application/json; charset=utf-8",
    "x-ratelimit-limit-minute": "15",
    "x-ratelimit-limit-hour": "60",
    "x-ratelimit-remaining-minute": "14",
    "x-ratelimit-remaining-hour": "59",
    "content-length": "4383",
    "server": "eSD GURU API 1.0"
}

Web server applications

The eSchoolData OAuth 2.0 endpoint supports web server applications that use languages and frameworks such as PHP, Java, Python, Ruby, and ASP.NET. For this scenario you need a web application account, which allows your application to call the eSD GURU API on behalf of an individual end user. This scenario is also known as "three-legged OAuth".

The authorization sequence begins when your application redirects a browser to a eSchoolData URL; the URL includes query parameters that indicate the type of access being requested. eSchoolData handles the user authentication and session selection. The result is an authorization code, which the application can exchange for an access token and a refresh token.

The application should store the refresh token for future use and use the access token to access the eSD GURU API. Once the access token expires, the application uses the refresh token to obtain a new one.

Service Accounts

The eSchoolData OAuth 2.0 system supports server-to-server interactions such as those between a web application and an eSchoolData service. For this scenario you need a service account, which belongs to your application instead of to an individual end user. A service account supports both the three-legged OAuth and two-legged OAuth approaches. Your application calls the eSD GURU API on behalf of the service account or an individual end user. Typically, an application uses a service account when it needs to access all data, rather than data related to a specific user. For example, applications that require class roster data can use a service account to obtain this information for all teachers.

The authorization sequence begins when your application makes a call to the eSD GURU API using the service account credentials. eSchoolData handles the account authentication and session selection. The result is an access token and refresh token.

The application should store the refresh token for future use and use the access token to access the eSD GURU API. Once the access token expires, the application uses the refresh token to obtain a new one.

Overview

OpenID Connect

Setting up OAuth 2.0

Obtain OAuth 2.0 credentials

Set a redirect URI

Authenticating the user

Authorization/Authentication Endpoint

Supported Parameters

Example

Token Endpoint

Supported Parameters

Authentication

Example

UserInfo Endpoint

Example

Discovery Endpoint

Example

Logout Endpoint

Token Revocation

Supported parameters:

Example:

Access token validation endpoint

Example:

Identity Token Validation Endpoint

Example

Using OAuth 2.0 to Access eSchoolData APIs

Obtain OAuth 2.0 credentials

Obtain an access token from the eSchoolData Authorization Server

Send the access token to an API

Refresh the access token, if necessary

Rate Limit

Web server applications

Service Accounts