SSO API Specification Doc (Quest Track) Version Date Author Description Index

Transcription

1 SSO API Specification Doc (Quest Track) Version Date Author Description /28/2015 Bob Rodgers Initial draft Index 1. Provision User 2. Verify User 3. Login User Conventions Status Codes User Object fields:

2 Objective This API enables 3rd party systems to create users and log them in to Quest Track, bypassing Quest Track s registration. With this, we can minimize the amount of custom work we need to do for clients who request this. All the work is on the 3rd party side to call into our system. 1. Provision User Methods Create or update a user within the Quest Track system and obtain a password. All fields are updated during this call. If a field is currently filled out but left blank during this call, the value will be removed. Method URL endpoint POST api/services.asmx?op=provisionuser Type Params Values Body Username Password user Userobject RequiredUserobjectfields: Username, SSO ID, Group ID, First Name, Last Name and must be sent with all requests. The Username and password are keys that help the server validate the request source. Status 200 { } " Value ": <password>-savethisvalue " StatusDescription ": REGISTRATION_SUCCESS

3 password ( ) VerifyUser API call must include this key 400 { " StatusDescription ":"REGISTRATION_ERROR" } 400 { " StatusDescription ": <listofmissingfields> } 401 { " Value ": <> " StatusDescription ": "Invalidusernameand/orpassword" } Theusernameand/orpasswordintheheaderwere incorrect 500 {" StatusD escription ": <exceptionerrormessage> } 2. Verify User Verify the username and password in Quest Track. Returns an authentication code to be used for directly logging in the user. The auth code expires after a short period of time, currently 10 seconds. If the user has not been updated, the password value will remain the same so storing this on the client side will preclude the need to call Provision User for every login. Method URL POST api/services.asmx?op=verifyuser Type Params Values Body Body Username Password ssoid password ssoid The ssoid for the user you are trying to verify that was given in the call to /api/services.asmx?op=provisionuser password The password value returned from the call to /api/services.asmx?op=provisionuser. This value will change every time the Provision User call is made. If you are not updating the user

4 information, you can save this value for future use and only make this call to obtain the auth code needed to login the user. Status 200 Value will be a that will contain the auth code needed to validate the user for auto login. An example response is: { " Value ": d5064f9f e7-8c47-dad5c " StatusDescription ":"VERIFICATION_SUCCESS" } 400 {" StatusDescription ":" Userdoesnotexist"} Incorrectorinvalidssoidvalue. 400 {" StatusDescription ":"Invalidpassword"} 400 {" StatusDescription ":"Invalidpassword"} 400 {" StatusDescription ":"Unknownerror"} 401 {" StatusD escription ":"Invalidusernameand/orpassword" } Theusernameand/orpasswordintheheaderwereincorrect 500 {" StatusDescription ":"Unknownerror"} 3. Login User This is a call to a specific URL with query parameters for that page to use to verify the user and optionally direct them to a particular course or page in Quest Track. URL Query Parameters api/autologin.aspx ssoid-samevaluesuppliedintheprovisioningand verifycall authcode ValuereturnedintheVerifyUserAPI call [optionalparameters] courseid -CourseIDtotakeuserdirectlytothe courselaunchpage

5 pagename takestheuserdirectlytoaparticular page,i.e.courses.aspxwilltaketheuserdirectly totheircoursetranscriptpage.

6 Conventions Client Client application. Status HTTP status code of response. Glossary Possible responses are listed under s for each method. Only one of them is issued per request server. All responses are in SOAP format. All request parameters are mandatory Status Codes All status codes are standard HTTP status codes. The following are used in this API. 2XX - Success 4XX - Error occurred in client s part 5XX - Error occurred in server s part Status Code Description 200 OK 400 Badrequest 401 Authenticationfailure 500 InternalServerError User Object fields: Field Name Field Type Required UserID Int GroupID X UserName X X

7 FirstName X LastName X SSOID X Password Birthdate DateTime IsAdmin boolean Phone CompanyName CompanyPhone CompanyAddress1 CompanyAddress2 CompanyCity Company CompanyZip Country Countryobject MiddleInitial EmployeeID int Locale Localeobject IsInstructor boolean Active boolean