Slc camp technology getting started and api deep dive-boston_sep2012

Contains Company Confidential Material – Do Not Disclose

Hello World!

Getting started with the SLC API


1. Register an application2. Get a token from the API using a web browser3. Use REST console to make some API calls4. How to bypass realm selection5. Connect with the API from your application

Hello World


• Provide a redirect_uri like http://localhost/• Approve the app for all of the available districts• Get your client_id and client_secret

Register Your App

http://localhost/


URL: https://api.sandbox.slcedu.org/api/oauth/authorizeParameters: response_type, client_id, redirect_uri

Example:https://api.sandbox.slcedu.org/api/oauth/authorize?response_type=code&client_id=GLdkshFT2W&redirect_uri=http://localhost/

Initiate Authentication

http://local.slidev.org:3000/callback



URL: https://api.sandbox.slcedu.org/api/oauth/tokenParameters: redirect_uri, client_id, client_secret, code

Example:https://api.sandbox.slcedu.org/api/oauth/token?redirect_uri=http://localhost/&client_id=GLdkshFT2W&client_secret=HSh49ilWMkHAawoW4NjZbyOG8TnORdOl5uApeCHkS6tpEDQD&code=<retrieved from previous call>

Request a token






Chrome REST Console

Authentication:Add OAuth Token to HTTP Header:Authorization "Bearer <token>"

Setup REST console


Session check:• https://api.sandbox.slcedu.org/api/rest/system/session/

check

List of students:• https://api.sandbox.slcedu.org/api/rest/v1/students

Logout• https://api.sandbox.slcedu.org/api/rest/system/session/

logout

Make some API Calls from REST console


To skip the realm selection page you can add an additional parameter to the oauth/authorize call: Realm=SandboxIDP

• https://api.sandbox.slcedu.org/api/oauth/authorize?response_type=code&client_id=GLdkshFT2W&Realm=SandboxIDP&redirect_uri=http://localhost/

Skipping Realm Selection




1. Redirect the browser to the oauth/authorize endpoint

2. Add handling to receive the callback with the authorization code

3. Make a REST call to the API to retrieve your Oauth token using the authorization code

4. Make a REST call to the API to get the logged in user's name

Connect from your app


Code Example: Step 1: Start the authentication process

//define our api server url

api = "https://api.sandbox.slcedu.org/api"

//define our redirect endpoint

redirect_uri="http://localhost:1337/oauth"

//setup the url to forward to in order to start authentication process

loginUri="#{api}/oauth/authorize?Realm=SandboxIDP&response_type=code&client_id=#{clientId}&redirect_uri=#{redirect_uri}"

//handler for login that redirects to the loginURI

app.get '/login', (req, res) ->

res.redirect loginUri


//handler the authorization code coming back

app.get '/oauth', (req, res) ->

//retrieve the authorization code from the query

authCode = req.query['code']

//create the URI to retrieve a token

tokenUri = "#{api}/oauth/token?code=#{authCode}&client_id=#{clientId}&redirect_uri=#{redirect_uri}&client_secret=#{clientSecret}"

//issue the request to get the token

request tokenUri, (error, response, body) ->

Code Example: Step 2: Handle authorization code


//handle any errors

if error?

console.log "error: #{util.inspect error}"

Error.throw500 req, res

//no errors, parse the json response to retrieve the token

json = JSON.parse body

req.session.token = json.access_token

console.log "session.token=#{req.session.token}"

Code Example: Step 3: Handle token response


//issue a request to sessionCheck

sessionCheckUri = "#{api}/rest/v1/system/session/check"

request url: sessionCheckUri, headers: {"Authorization" : "Bearer " + req.session.token }, (error, response, body) ->

if error?

//handle errors

console.log "error: #{util.inspect error}"

Error.throw500 req, res

json = JSON.parse body

//parse the json and get the user's name

req.session.userName = json.full_name

Code Example: Step 4: Call session check


API Deep Dive

Session #1 - Authorization Model


Authentication & AuthorizationVerifying the user is who they say they are and what actions the user has permission to do.

Permissions and RolesPermissions are actions granted to a user. Roles are predefined relationships between a user and a specific set of permissions.

Vocabulary


Two Security Paradigms

User access is determined by: The user's rights (permission based security)

The user's associations to records (contextual security)

How security works: Context determine the records a user can access Rights determine the fields a user can view and write


Contextual Security

Context determines the scope of what users can access

• Scoped access - A teacher will not need to see the

homework grades for all students in a district but only

the students they are teaching

• Examples - A teacher may only have context to a few

sections at a school, while the principal at that school

would have context to all student and section records


Context is derived from associations and references in

the data

• Associations - A teacher-section-association record

gives a teacher context to a section, and a student-

section-association to the section gives the teacher

context to student

Contextual Security


The root of context for is the user.

• An Identity Provider gives the details of a user's

authentication that uniquely identify the user

• SLC will find a record of that user in the data store

which is the starting point for contextual access

Contextual Security


Staff Context Resolving

Staff context is determined by Ed-Org associations


Teacher Context Resolving

Teacher context is determined by associations to sections, programs, cohorts, and Ed-OrgsContext to a student gives context to records about the student


Permissions

Each user is granted a set of predetermined rightsRights grant read or write access to resources.Resources are API endpoints, records, and attributes of records.

SLC has four default levels of data accessSecurity Level Description Examples

Public Publicly available data School name, school address

Restricted Sensitive information Personal email address

Aggregate Derived fields, aggregations without PII

Average test scores, school attendance rates

General All remaining data Student name, section details


Roles are assigned to each user to give a set of rights. Default SLC Roles

Example Users for each RoleEducator - a teacher, counselor, or other user that will need access to most, but not all, of their student's dataLeader - a principal or superintendent that will need to view all data under their jurisdictionIT Administrator - a technical admin whose responsibility to maintain and fix all data in their jurisdictionAggregate Viewer - an agency or person that has access to only aggregate records

Default Roles

Roles/Rights Write Restrict

Write General

Read Restrict

Read General

Read Public

Read Aggregate

Educator

Leader

IT Administrator

Aggregate Viewer


What happens when your app calls /students? As a teacher? As a school leader? How to narrow the scope with contextual endpoints: /sections/[id]/studentSectionAssociations/students

What this means to an API user


Add context to api requests

/students for a state or district-level leader could be massive

Instead, narrow the scope to a school:/schools/<id>/studentSchoolAssociations/students

/studentAssessments for a teacher with access to many students

Instead, narrow the scope to a student:/students/<id>/studentAssessments

API Usage Recommendations


Forbidden Access

What happens when a user tries to access a resource without

proper rights or context?

o Forbidden access

o API will return a response containing 403 Forbidden

o Generates security event logs


API Deep Dive

Session #2 – Authentication OAuth and SAML


What is OAuth 2.0?

"An open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications." - Oauth.com

We use OAuth 2.0 to authorize third-party applications.


What is OAuth 2.0?

The Control Flow for OAuth 2.0

The goal of this control flow is to authenticate the user and the app.

User authentication is handled via SAML federation between SLC and an identity provider.

The application and SLC have an Oauth dance to authorize the application.

The Control Flow for OAuth 2.0


Endpoint:https://api.sandbox.slcedu.org/api/oauth/authorize

Parameters:response_type=code

client_id=#{clientId}redirect_uri=#{redirect_uri}

(optional)Realm=SandboxIDP

(optional)State=#{some app state}

https://api.sandbox.slcedu.org/api/oauth/authorize?Realm=SandboxIDP&response_type=code&client_id=#{clientId}&redirect_uri=#{redirect_uri}"

Redirect User to Login


Realm Selection During Authentication

• Realm selection occurs after hitting authorize endpointo User will be asked to pick the realm where they authenticateo User will be redirected to the realm they chooseo API is told specifics about the user after they authenticate from

SAML messages sent back from the IDP

• Realm selection can be skippedo Useful when making an app for a specific state or district where you

know all users will be picking the same realmo Pass in a realm ID as a parameter to the OAuth authorize endpoint

(Realm ID will be known by that realm's admins)o User will then be redirected to that realm's login page instead of

having to chooseo If realm ID passed in doesn't match, users must select it themselves


• API redirects the user to login• Authentication occurs at the users Identity Provider• SAML2.0 is the security messaging protocol used

between the API (SAML Service Provider) and the Identity Provider

• After login success the API will redirect the user back to the application

User Login


• User is redirected after login to the applications callback URI.

• A user’s OAuth authorization code will exist on the callback to be used in the OAuth token request.

• If State was passed in the authorize call, it will also be returned.

https://app.example.com/redirect_endpoint?code=c-77527ab7-4f70-40ee-a4a1-35cbeb735619&state=app_state

Callback after login


OAuth Request

Apps request an OAuth token from the API via a REST call to:

https://api.sandbox.slcedu.org/api/oauth/token

Parameters:code=#{userAuthCode}

client_id=#{appClientId}

redirect_uri=#{appRedirectUri}

client_secret=#{appClientSecret}

https://api.sandbox.slcedu.org/api/oauth/token?code=#{authCode}&client_id=#{clientId}&redirect_uri=#{redirect_uri}&client_secret=#{clientSecret}


OAuth Token Request and Response

• API returns a new access tokeno Token is used to identify user and app making callso Token is required to access all protected API endpointso API does not support refresh tokenso Tokens expire based on inactivity and time since issuance


OAuth flow for Installed Applications• Installed apps will not have redirect URIs for the API to callback since they do

not have a web application server to redirect to

• The app will have to embed a web-browser for the user to authenticate with their IDP and optionally choose their Realm in the realm chooser

• The apps auth code is returned in the page body after the user authenticates instead of using the callback URIo The code is rendered as json in the web browsero The app will need to intercept the code

• All other aspects of the authentication process are the same (OAuth endpoints, realm selection, login page, SAML messages)

OAuth for Installed Applications


Making API Calls with OAuth Bearer Token

Supply the following HTTP Header:

Authorization: Bearer #{OAuth Token}

Example:

Authorization: Bearer 12345678-abcd-1234-5678-abcd12345678


Calling system/session/check

• Want to know if your session is still valid?o Call /api/rest/system/session/check to return basic information about your

sessiono Useful for determining if a session has timed out, displaying the user's name,

or other personalized experiences

• Want more info about your user?o Call /api/rest/system/session/debug to return more detailed information

about your user & sessiono Returns info such as permissions granted to your user & the entity they map

back to in the datastoreo Info can be used to disable parts of your app if they don't have sufficient

permissions, like disabling an update button if they cannot write data


Handling Expired Tokens

• Tokens expire on logout or after idle timeoutso Logout affects all app sessions for that usero Idle timeouts occur after a token has not been used in an API call for several

minutes

• Detecting Expired Tokenso The API returns a 401 Unauthorized response on requests were the token is

expiredo On a 401 response the application should restart the authentication processo In the 401 response the authentication starting point URL is returned.


• SLC maintains one session for each user across all the SLC Apps they are simultaneously using.

• On first access the user is directed to their IDP to authenticate and the SAML request forces authentication

• When the user goes to a second SLC app and has an existing session, the SLC API redirects to their IDP but does not force authentication again. It is up to the IDP to decide if the user must login or not

SLC Single Sign-On


• Endpoint is /api/rest/system/session/logouto Can also use the logout link in the Portal header if the app includes it

• Logs the user out of ALL of the SLC apps they are using but does not log them out of their IDP. No Single Logout to the IDP

Logout Endpoint


Federated Authentication

Linking identity and attributes across multiple distinct systems

Identity Provider

A computer system that stores user identity information

(usernames/passwords/roles) and provides a way for other computer

systems to access this data

Service Provider

An entity that controls access to services and resources

Vocabulary


SAML Metadata and IDP Configuration

SAML Metadata is XML that describes our endpoints• Public endpoint is at /api/rest/saml/metadata

• Returns XML document used for federation

Metadata XML can be imported to setup federation


SLC Realm Creation

For SLC Administrators with the REALM_ADMINISTRATOR right.

Performed with the realm management tool.


SAML Request

SAML Request is composed describing the action we would like IDP to perform (authenticate the user in this case)<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="aaf23196-1773-2113-474a-fe114412ab72" Version="2.0" IssueInstant="2004-12-05T09:21:59" AssertionConsumerServiceIndex="0" AttributeConsumingServiceIndex="0"> <saml:Issuer>https://sp.example.com/SAML2</saml:Issuer> <samlp:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"/></samlp:AuthnRequest>


SAML Assertion

IDP replies with data containing series of statements about the user (Sample)<saml:AttributeStatement>

<saml:Attribute Name="roles"><saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> Teacher, Math Teacher

</saml:AttributeValue></saml:Attribute><saml:Attribute Name="userId">

<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> demo

</saml:AttributeValue></saml:Attribute><saml:Attribute Name="userName">

<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> Demo User

</saml:AttributeValue></saml:Attribute>

</saml:AttributeStatement>


SAML Assertion Attributes

The API processes SAML assertions to create user sessions.

These required attributes are extracted from the assertion:• userId - user's staffUniqueStateId from Ed-Fi data in datastore

• user name - user's full name, like John Doe

• roles - user's roles, used in determining roles-to-rights mapping

Education

Slc camp technology getting started and api deep dive-boston_sep2012