Your SlideShare is downloading. ×
  • Like
Slc camp technology getting started and api deep dive-boston_sep2012
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Now you can save presentations on your phone or tablet

Available for both IPhone and Android

Text the download link to your phone

Standard text messaging rates apply

Slc camp technology getting started and api deep dive-boston_sep2012

  • 345 views
Published

SLC technology Getting started Secruity and API deep dive

SLC technology Getting started Secruity and API deep dive

Published in Education
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
345
On SlideShare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
12
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. Hello World! Getting started with the SLC APIContains Company Confidential Material – Do Not Disclose
  • 2. Hello World 1. Register an application 2. Get a token from the API using a web browser 3. Use REST console to make some API calls 4. How to bypass realm selection 5. Connect with the API from your applicationContains Company Confidential Material – Do Not Disclose
  • 3. Register Your App • Provide a redirect_uri like http://localhost/ • Approve the app for all of the available districts • Get your client_id and client_secret Contains Company Confidential Material – Do Not Disclose
  • 4. Initiate Authentication URL: https://api.sandbox.slcedu.org/api/oauth/authorize Parameters: response_type, client_id, redirect_uri Example: https://api.sandbox.slcedu.org/api/oauth/authorize?res ponse_type=code&client_id=GLdkshFT2W&redirect_uri= http://localhost/ Contains Company Confidential Material – Do Not Disclose
  • 5. Request a token URL: https://api.sandbox.slcedu.org/api/oauth/token Parameters: redirect_uri, client_id, client_secret, code Example: https://api.sandbox.slcedu.org/api/oauth/token?redire ct_uri=http://localhost/&client_id=GLdkshFT2W&client _secret=HSh49ilWMkHAawoW4NjZbyOG8TnORdOl5uA peCHkS6tpEDQD&code=<retrieved from previous call>Contains Company Confidential Material – Do Not Disclose
  • 6. Setup REST console Chrome REST Console Authentication: Add OAuth Token to HTTP Header: Authorization "Bearer <token>"Contains Company Confidential Material – Do Not Disclose
  • 7. Make some API Calls from REST console Session check: • https://api.sandbox.slcedu.org/api/rest/system/session/c heck List of students: • https://api.sandbox.slcedu.org/api/rest/v1/students Logout • https://api.sandbox.slcedu.org/api/rest/system/session/lo goutContains Company Confidential Material – Do Not Disclose
  • 8. Skipping Realm Selection 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&Real m=SandboxIDP&redirect_uri=http://localhost/ Contains Company Confidential Material – Do Not Disclose
  • 9. Connect from your app 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 users nameContains Company Confidential Material – Do Not Disclose
  • 10. 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_i d=#{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
  • 11. Code Example: Step 2: Handle authorization code //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=#{redi rect_uri}&client_secret=#{clientSecret}" //issue the request to get the token request tokenUri, (error, response, body) -> Contains Company Confidential Material – Do Not Disclose
  • 12. Code Example: Step 3: Handle token response //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}"Contains Company Confidential Material – Do Not Disclose
  • 13. Code Example: Step 4: Call session check //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 users name req.session.userName = json.full_name Contains Company Confidential Material – Do Not Disclose
  • 14. API Deep Dive Session #1 - Authorization ModelContains Company Confidential Material – Do Not Disclose
  • 15. Vocabulary Authentication & Authorization Verifying the user is who they say they are and what actions the user has permission to do. Permissions and Roles Permissions are actions granted to a user. Roles are predefined relationships between a user and a specific set of permissions.Contains Company Confidential Material – Do Not Disclose
  • 16. Two Security Paradigms User access is determined by: The users rights (permission based security) The users 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 writeContains Company Confidential Material – Do Not Disclose
  • 17. 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
  • 18. Contextual Security 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 Contains Company Confidential Material – Do Not Disclose
  • 19. Contextual Security The root of context for is the user. • An Identity Provider gives the details of a users 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 Contains Company Confidential Material – Do Not Disclose
  • 20. Staff Context Resolving Staff context is determined by Ed-Org associations Contains Company Confidential Material – Do Not Disclose
  • 21. Teacher Context Resolving Teacher context is determined by associations to sections, programs, cohorts, and Ed-Orgs Context to a student gives context to records about the studentContains Company Confidential Material – Do Not Disclose
  • 22. Permissions Each user is granted a set of predetermined rights Rights grant read or write access to resources. Resources are API endpoints, records, and attributes of records. SLC has four default levels of data access Security Level Description Examples Public Publicly available data School name, school address Restricted Sensitive information Personal email address Aggregate Derived fields, Average test scores, school attendance rates aggregations without PII General All remaining data Student name, section detailsContains Company Confidential Material – Do Not Disclose
  • 23. Default Roles Roles are assigned to each user to give a set of rights. Default SLC Roles Roles/Rights Write Write Read Read Read Read Restrict General Restrict General Public Aggregate Educator Leader IT Administrator Aggregate Viewer Example Users for each Role Educator - a teacher, counselor, or other user that will need access to most, but not all, of their students data Leader - a principal or superintendent that will need to view all data under their jurisdiction IT Administrator - a technical admin whose responsibility to maintain and fix all data in their jurisdiction Aggregate Viewer - an agency or person that has access to only aggregate records Contains Company Confidential Material – Do Not Disclose
  • 24. What this means to an API user 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 Contains Company Confidential Material – Do Not Disclose
  • 25. API Usage Recommendations 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>/studentAssessmentsContains Company Confidential Material – Do Not Disclose
  • 26. 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 logsContains Company Confidential Material – Do Not Disclose
  • 27. API Deep Dive Session #2 – Authentication OAuth and SAMLContains Company Confidential Material – Do Not Disclose
  • 28. 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
  • 29. What is 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 The Control Flow for OAuth 2.0Contains Company Confidential Material – Do Not Disclose
  • 30. Redirect User to Login Endpoint: https://api.sandbox.slcedu.org/api/oauth/authorize Parameters: response_type=code client_id=#{clientId}redirect_uri=#{redirec t_uri} (optional)Realm=SandboxIDP (optional)State=#{some app state} https://api.sandbox.slcedu.org/api/oauth/authorize?Realm=SandboxIDP&re sponse_type=code&client_id=#{clientId}&redirect_uri=#{redirect_uri}" Contains Company Confidential Material – Do Not Disclose
  • 31. Realm Selection During Authentication • Realm selection occurs after hitting authorize endpoint o User will be asked to pick the realm where they authenticate o User will be redirected to the realm they choose o API is told specifics about the user after they authenticate from SAML messages sent back from the IDP • Realm selection can be skipped o Useful when making an app for a specific state or district where you know all users will be picking the same realm o Pass in a realm ID as a parameter to the OAuth authorize endpoint (Realm ID will be known by that realms admins) o User will then be redirected to that realms login page instead of having to choose o If realm ID passed in doesnt match, users must select it themselves Contains Company Confidential Material – Do Not Disclose
  • 32. User Login • 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 Contains Company Confidential Material – Do Not Disclose
  • 33. Callback after 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?c ode=c-77527ab7-4f70-40ee-a4a1- 35cbeb735619&state=app_state Contains Company Confidential Material – Do Not Disclose
  • 34. 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_i d=#{clientId}&redirect_uri=#{redirect_uri}&client_secret=#{clientSecret}Contains Company Confidential Material – Do Not Disclose
  • 35. OAuth Token Request and Response • • API returns a new access token o Token is used to identify user and app making calls o Token is required to access all protected API endpoints o API does not support refresh tokens o Tokens expire based on inactivity and time since issuanceContains Company Confidential Material – Do Not Disclose
  • 36. OAuth for Installed Applications 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 URI o The code is rendered as json in the web browser o 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) Contains Company Confidential Material – Do Not Disclose
  • 37. Making API Calls with OAuth Bearer Token Supply the following HTTP Header: Authorization: Bearer #{OAuth Token} Example: Authorization: Bearer 12345678-abcd-1234-5678- abcd12345678Contains Company Confidential Material – Do Not Disclose
  • 38. 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 session o Useful for determining if a session has timed out, displaying the users 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 & session o Returns info such as permissions granted to your user & the entity they map back to in the datastore o Info can be used to disable parts of your app if they dont have sufficient permissions, like disabling an update button if they cannot write data Contains Company Confidential Material – Do Not Disclose
  • 39. Handling Expired Tokens • Tokens expire on logout or after idle timeouts o Logout affects all app sessions for that user o Idle timeouts occur after a token has not been used in an API call for several minutes • Detecting Expired Tokens o The API returns a 401 Unauthorized response on requests were the token is expired o On a 401 response the application should restart the authentication process o In the 401 response the authentication starting point URL is returned.Contains Company Confidential Material – Do Not Disclose
  • 40. SLC Single Sign-On • 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 Contains Company Confidential Material – Do Not Disclose
  • 41. Logout Endpoint • Endpoint is /api/rest/system/session/logout o 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 IDPContains Company Confidential Material – Do Not Disclose
  • 42. Vocabulary 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 resourcesContains Company Confidential Material – Do Not Disclose
  • 43. 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 federationContains Company Confidential Material – Do Not Disclose
  • 44. SLC Realm Creation For SLC Administrators with the REALM_ADMINISTRATOR right. Performed with the realm management tool.Contains Company Confidential Material – Do Not Disclose
  • 45. 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
  • 46. 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
  • 47. SAML Assertion Attributes The API processes SAML assertions to create user sessions. These required attributes are extracted from the assertion: • userId - users staffUniqueStateId from Ed-Fi data in datastore • user name - users full name, like John Doe • roles - users roles, used in determining roles-to-rights mapping Contains Company Confidential Material – Do Not Disclose