Introduction

The Integrated App Environment (IAE) allows third party application integration with Wisenet services. It uses industry standard OAuth 2.1 framework to provide limited access to an HTTP service on behalf of a resource owner.

Why OAuth 2.1

OAuth 2.1 is consolidating best practices learned over the 11 years since OAuth 2 was published. The original OAuth 2.0 specification was released in October 2012 as RFC 6749 and RFC 6750. It replaced OAuth 1.0, released in April 2010. There have been a number of extensions and modifications to OAuth 2 over the subsequent years.

A new OAuth specification has been proposed and is currently under discussion. If approved, OAuth 2.1 will obsolete certain parts of OAuth 2.0 and mandate security best practices. The rest of the OAuth 2.0 specification will be retained.

That bears repeating. Nothing new will be added. This is an explicit design goal of OAuth 2.1.

See: Differences Between OAuth 2 And OAuth 2.1 and of course_offer OAuth 2.1 - 10 Differences from OAuth 2.0

Essentially this boils down to using PKCE (RFC 7636: Proof Key for Code Exchange by OAuth Public Clients) plus a few other bits and pieces. See article link above. Since OAuth 2.1 is essentially OAuth 2.0 with “security best practices” and it will not add anything new, we will work with the latest OAuth 2.1 draft.

OAuth 2.1 - Authorization Code Flow with PKCE

Roles

Scope	Description
Resource owner (RO) (end-user)	Wisenet tenant admin
Resource server (RS)	Wisenet Api
Client	Integrated app
Authorization server (AS)	Wisenet Auth Api

Endpoints

https://auth.wisenet.co/api/.well-known/oauth-authorization-server Used by the client to get authorization server metadata.
https://auth.wisenet.co/api/oauth/authorize Used by the client to obtain authorization from the resource owner via user-agent redirection.
https://auth.wisenet.co/api/oauth/token Used by the client to exchange an authorization code for an access token, with client authentication. Also to exchange a refresh token for an access token.

OAuth 2.1 - 4.1 Authorization Code Grant

Authorization Code grant diagram

(1) Resource owner tries to access the client application

This could also be a function within the application which requires Wisenet resource access.

(2) The Client Application makes an authorization request to the authorization endpoint

GET https://auth.wisenet.co/api/oauth/authorize
  ?response_type=code             // - Required
  &client_id={Client ID}          // - Required
  &client_secret={Client Secret}  // - Required
  &redirect_uri={Redirect URI}    // - Conditionally required
  &scope={Scopes}                 // - Optional
  &state={Arbitrary String}       // - Required
  &code_challenge={Challenge}     // - Required for PKCE
  &code_challenge_method={Method} // - Required for PKCE

(3) User authenticates and authorizes scopes

Using the familiar User Portal UI the user can login with credentials or social login, and select tenant and scopes to authorize.

(4) The Authorization Server sends a temporary Authorization Code back to the Redirect URI

OAuth 2.1 - 4.1.2 Authorization Response

HTTP/1.1 302 Found
Location: {Redirect URI}
  ?code={Authorization Code}  // - Always included
  &state={Arbitrary String}   // - Included if the authorization  request included 'state'.
  &iss={Issuer String}        // - Optional. Client can use to prevent mixup attacks

(5) The Client Application makes a grant_type=authorization_code token request (POST) to the token endpoint with the authorization code.

OAuth 2.1 - 3.2 Token endpoint (base implementation)
OAuth 2.1 - 4.1.3 Token endpoint extension

POST https://auth.wisenet.co/api/oauth/token
  Content-Type: application/x-www-form-urlencoded
  ?grant_type=authorization_code  // - Required
  &code={Authorization Code}      // - Required
  &redirect_uri={Redirect URI}    // - Required if the authorization request included 'redirect_uri'. Required if the authorization request included 'code_challenge'.

(6) Access token response

HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token": {Access Token},      // - Always included
    "token_type": {Token Type},          // - Always included
    "expires_in": {Lifetime In Seconds}, // - Optional
    "refresh_token": {Refresh Token},    // - Optional
    "scope": {Scopes}                    // - Mandatory if the granted scopes differ from the requested ones.
    "token_type": Bearer                 //
    "api_key": {Api Key}                 // - Always included. Use together with "access_token" for subsequent requests the resource server.
  }

Note: Subsequent requests to the resource server must include the Api Key value in a “x-api-key” header along with the “authorization” header containing the Bearer token

(7) Access token can be used to make requests to the resource server

OAuth 2.1 - 3.2.3 Token Response

GET https://api.wisenet.co/v1/lln-submissions/100
  x-api-key: {Api Key},                 // - Required
  Authorization: Bearer {Access Token}  // - Required

OAuth 2.1 - 4.3 Refresh Token Grant

Refrehs Token grant diagram

(8) The Client Application makes a grant_type=refresh_token token (GET) request to the token endpoint with the refresh token.

OAuth 2.1 - 3.2 Token endpoint (base implementation)
OAuth 2.1 - 4.3.1 Token endpoint extension

GET https://auth.wisenet.co/api/oauth/token
  Content-Type: application/x-www-form-urlencoded
  ?grant_type=refresh_token       // - Required
  &refresh_token={Refresh Token}  // - Required

(9) The Authorization Server creates new access and refresh tokens and sends them back to the client

HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  {
    "access_token": {Access Token},      // - Always included
    "token_type": {Token Type},          // - Always included
    "expires_in": {Lifetime In Seconds}, // - Optional
    "refresh_token": {Refresh Token},    // - Optional
    "scope": {Scopes}                    // - Mandatory if the granted scopes differ from the requested ones.
    "token_type": Bearer                 //
    "api_key": {Api Key}                 // - Always included. Use together with "access_token" for subsequent requests the resource server.
  }

Scopes

Scopes provide a way to limit the access granted to an application allowing only specific actions.

The full or a subset of the supported scopes will be agreed upon and assigned to the integration client during registration. The integration may only request scope from those assigned. Any required scopes, will be included even when not requested.

assessment_submission_read

Allows the reading of Assessment Submission data.
Endpoints included:

[GET] /assessment-submissions-data/{id}

assessment_submission_write

Allows the updating of Assessment Submission data.
Endpoints included:

[PUT] /assessment-submissions-data/{id}

class_read

Allows the reading of Class data.
Endpoints included:

[GET] /classes
[GET] /classes/{id}

class_write

Allows the updating of Class data.
Endpoints included:

[POST] /classes
[PUT] /classes/{id}
[PATCH] /classes/{id}

class_registration_read

Allows the reading of Class Registration data.
Endpoints included:

[GET] /class-registrations
[GET] /class-registrations/{id}

combos_read

Allows getting combos data.
Endpoints included:

[GET] /combos/class-absent-reasons
[GET] /combos/class-registration-statuses
[GET] /combos/custom-field-types
[GET] /combos/countries
[GET] /combos/currencies
[GET] /combos/elearning-course-statuses
[GET] /combos/elearning-enrolment-statuses
[GET] /combos/genders
[GET] /combos/languages
[GET] /combos/nz-degree-research-statuses
[GET] /combos/nz-embedded-literacy-numeracy
[GET] /combos/nz-register-levels
[GET] /combos/nz-research-levels
[GET] /combos/nz-unit-classifications
[GET] /combos/nz-unit-exemption-amfm
[GET] /combos/states
[GET] /combos/submission-data-statuses
[GET] /combos/submission-data-types
[GET] /combos/unit-enrolment-statuses
[GET] /combos/event-enrolment-statuses
[GET] /combos/event-session-statuses
[GET] /combos/event-session-types
[GET] /combos/nz-training-agreement-statuses
[GET] /combos/training-agreement-statuses
[GET] /combos/nz-training-agreement-grace-reasons
[GET] /combos/nz-training-agreement-on-hold-reasons
[GET] /combos/nz-training-agreement-withdrawal-reasons

combos_write

Allows the updating of combos data.
Endpoints included:

[POST] /combos/class-absent-reasons
[PUT] /combos/class-absent-reasons/{id}

document_file_read

Allows to get a pre-signed URL that the document can be downloaded from
Endpoints included:

[GET] /document-file/{id}

document_upload

Allows the upload of documents files, including pdf, jpg, png.
Endpoints included:

[POST] /document-file

course_read

Allows the reading of Course data.
Endpoints included:

[GET] /courses
[GET] /courses/{id}

course_write

Allows the updating of Course data.
Endpoints included:

[POST] /courses
[PATCH] /courses/{id}

course_offer_read

Allows the reading of Course Offer data.
Endpoints included:

[GET] /course-offers
[GET] /course-offers/{id}

course_offer_write

Allows the updating of Course Offer data.
Endpoints included:

[POST] /course-offers
[PUT] /course-offers/{id}

course_unit_read

Allows the reading of Course Unit data.
Endpoints included:

[GET] /course-units
[GET] /course-units/{id}

course_unit_write

Allows the updating of Course Unit data.
Endpoints included:

[POST] /course-units
[PUT] /course-units/{id}
[PATCH] /course-units/{id}

unit_read

Allows the reading of Unit data.
Endpoints included:

[GET] /units
[GET] /units/{id}

unit_write

Allows the updating of Unit data.
Endpoints included:

[POST] /units
[PATCH] /units/{id}

unit_offer_read

Allows the reading of Unit Offer data.
Endpoints included:

[GET] /unit-offers
[GET] /unit-offers/{id}

unit_offer_write

Allows the updating of Unit Offer data.
Endpoints included:

[POST] /unit-offers
[PUT] /unit-offers/{id}

learner_nz_read

Allows the reading of Learner data.
Endpoints included:

[GET] /learnersnz
[GET] /learnersnz/list
[GET] /learnersnz/{id}

learner_nz_write

Allows the updating of Learner data.
Endpoints included:

[POST] /learnersnz
[PATCH] /learnersnz/{id}

learner_nz_read

Allows the reading of Learner data.
Endpoints included:

[GET] /learnersnz
[GET] /learnersnz/list
[GET] /learnersnz/{id}

learner_nz_write

Allows the updating of Learner data.
Endpoints included:

[POST] /learnersnz
[PATCH] /learnersnz/{id}

learner_sa_read

Allows the reading of Learner data.
Endpoints included:

[GET] /learnerssa
[GET] /learnerssa/list
[GET] /learnerssa/{id}

learner_sa_write

Allows the updating of Learner data.
Endpoints included:

[POST] /learnerssa
[PATCH] /learnerssa/{id}

learner_sg_read

Allows the reading of Learner data.
Endpoints included:

[GET] /learnerssg
[GET] /learnerssg/list
[GET] /learnerssg/{id}

learner_sg_write

Allows the updating of Learner data.
Endpoints included:

[POST] /learnerssg
[PATCH] /learnerssg/{id}

location_read

Allows the reading of Location data.
Endpoints included:

[GET] /locations
[GET] /locations/{id}

location_write

Allows the updating of Location data.
Endpoints included:

[POST] /locations
[PUT] /locations/{id}

opportunity_read

Allows the reading of Opportunity data.
Endpoints included:

[GET] /opportunities
[GET] /opportunities/{id}

opportunity_write

Allows the updating of Opportunity data.
Endpoints included:

[POST] /opportunities
[PUT] /opportunities/{id}
[PATCH] /opportunities/{id}

course_enrolment_read

Allows the reading of Course Enrolment data.
Endpoints included:

[GET] /course-enrolments
[GET] /course-enrolments/{id}

course_enrolment_write

Allows the updating of Course Enrolment data.
Endpoints included:

[POST] /course-enrolments
[PATCH] /course-enrolments/{id}

unit_enrolment_read

Allows the reading of Unit Enrolment data.
Endpoints included:

[GET] /unit-enrolments
[GET] /unit-enrolments/{id}

unit_enrolment_write

Allows the updating of Unit Enrolment data.
Endpoints included:

[POST] /unit-enrolments
[PATCH] /unit-enrolments/{id}

agent_read

Allows the reading of Agent data.
Endpoints included:

[GET] /agents
[GET] /agents/{id}

agent_write

Allows the updating of Agent data.
Endpoints included:

[POST] /agens

workplace_read

Allows the reading of Workplace data.
Endpoints included:

[GET] /workplaces
[GET] /workplaces/{id}

workplace_write

Allows the updating of Workplace data.
Endpoints included:

[POST] /workplace

staff_read

Allows the reading of Staff data.
Endpoints included:

[GET] /staff
[GET] /staff/{id}

staff_write

Allows the updating of Staff data.
Endpoints included:

[POST] /staff
[PUT] /staff/{id}
[PATCH] /staff/{id}

sales_contact_read

Allows the reading of Sales Contact data.
Endpoints included:

[GET] /sales-contacts
[GET] /sales-contacts/{id}
[GET] /sales-contact-relationships

sales_contact_write

Allows the updating of Sales Contact data.
Endpoints included:

[POST] /sales-contacts/{id}

sales_person_read

Allows the reading of Sales Person data.
Endpoints included:

[GET] /sales-persons

filenote_read

Allows the reading of Filenote data.
Endpoints included:

[GET] /filenotes
[GET] /filenotes/{id}

filenote_write

Allows the updating of Filenote data.
Endpoints included:

[POST] /filenotes

elearning_course_read

Allows the reading of Elearning Course data.
Endpoints included:

[GET] /elearning-courses
[GET] /elearning-courses/{id}

elearning_course_write

Allows the updating of Elearning Course data.
Endpoints included:

[POST] /elearning-courses
[PUT] /elearning-courses/{id}

elearning_course_offer_read

Allows the reading of Elearning Course Offer data.
Endpoints included:

[GET] /elearning-course-offers
[GET] /elearning-course-offers/{id}

elearning_course_offer_write

Allows the updating of Elearning Course Offer data.
Endpoints included:

[POST] /elearning-course-offers
[PUT] /elearning-course-offers/{id}

elearning_enrolment_read

Allows the reading of Elearning Enrolment data.
Endpoints included:

[GET] /elearning-enrolments
[GET] /elearning-enrolments/{id}

elearning_enrolment_write

Allows the updating of Elearning Enrolment data.
Endpoints included:

[POST] /elearning-enrolments
[PUT] /elearning-enrolments/{id}

event_enrolment_read

Allows the reading of Event Enrolment data.
Endpoints included:

[GET] /event-enrolments
[GET] /event-enrolments/{id}

event_enrolment_write

Allows the updating of Event Enrolment data.
Endpoints included:

[POST] /event-enrolments
[PUT] /event-enrolments/{id}
[PATCH] /event-enrolments/{id}

event_session_read

Allows the reading of Event Session data.
Endpoints included:

[GET] /event-sessions
[GET] /event-sessions/{id}

event_session_write

Allows the updating of Event Session data.
Endpoints included:

[POST] /event-sessions
[PUT] /event-sessions/{id}
[PATCH] /event-sessions/{id}

finance_manager_read

Allows the reading of Finance Management data.
Endpoints included:

[GET] /fee-types
[GET] /fee-types/{id}
[GET] /finance-items
[GET] /finance-items/{id}

finance_invoice_read

Allows the reading of Finance Invoice data.
Endpoints included:

[GET] /finance-invoices
[GET] /finance-invoices/{id}

finance_payment_read

Allows the reading of Finance Payment data.
Endpoints included:

[GET] /finance-payments
[GET] /finance-payments/{id}

finance_quote_read

Allows the reading of Finance Quote data.
Endpoints included:

[GET] /quotes
[GET] /quotes/{id}

record_custom_fields_read

Allows the reading of Record Custom Fields data.
Endpoints included:

[GET] /record-custom-fields/{entityName}/{recordId}
[GET] /record-custom-fields/{id}

record_custom_fields_write

Allows the updating of Record Custom Fields data.
Endpoints included:

[PUT] /record-custom-fields/{entityName}/{recordId}
[POST] /record-custom-fields/{entityName}/{recordId}
[PUT] /record-custom-fields/{id}

timetable_read

Allows the reading of Timetable data.
Endpoints included:

[GET] /timetables
[GET] /timetables/{id}

timetable_write

Allows the updating of Timetable data.
Endpoints included:

[POST] /timetables
[PUT] /timetables/{id}
[PATCH] /timetables/{id}

training_agreement_read

Allows the reading of Training Agreement data.
Endpoints included:

[GET] /training-agreements
[GET] /training-agreements/{id}

training_agreement_write

Allows the updating of Training Agreement data.
Endpoints included:

[POST] /training-agreements
[PUT] /training-agreements/{id}
[PATCH] /training-agreements/{id}