View
348
Download
0
Category
Tags:
Preview:
DESCRIPTION
SLC technology Getting started Secruity and API deep dive
Citation preview
Contains Company Confidential Material – Do Not Disclose
Hello World!
Getting started with the SLC API
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
• 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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
Chrome REST Console
Authentication:Add OAuth Token to HTTP Header:Authorization "Bearer <token>"
Setup REST console
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
//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
Contains Company Confidential Material – Do Not Disclose
//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
Contains Company Confidential Material – Do Not Disclose
//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
Contains Company Confidential Material – Do Not Disclose
API Deep Dive
Session #1 - Authorization Model
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
Staff Context Resolving
Staff context is determined by Ed-Org associations
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
API Deep Dive
Session #2 – Authentication OAuth and SAML
Contains Company Confidential Material – Do Not Disclose
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.
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
• 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
Contains Company Confidential Material – Do Not Disclose
• 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
Contains Company Confidential Material – Do Not Disclose
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}
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
Making API Calls with OAuth Bearer Token
Supply the following HTTP Header:
Authorization: Bearer #{OAuth Token}
Example:
Authorization: Bearer 12345678-abcd-1234-5678-abcd12345678
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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.
Contains Company Confidential Material – Do Not Disclose
• 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
Contains Company Confidential Material – Do Not Disclose
• 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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
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
Contains Company Confidential Material – Do Not Disclose
SLC Realm Creation
For SLC Administrators with the REALM_ADMINISTRATOR right.
Performed with the realm management tool.
Contains Company Confidential Material – Do Not Disclose
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>
Contains Company Confidential Material – Do Not Disclose
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>
Contains Company Confidential Material – Do Not Disclose
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
Recommended