OAuth2 API Applications
Overview
Please ensure you have a good understanding of the OAuth2 workflows within the OAuth2 GitHub documentation.
OAuth2 allows the TASS Parent Orbit app, Staff Orbit app and third-party products to connect to TASS.web APIs as an entity (e.g. a parent) and uniquely identify them in order to return targeted data. It does not require the entity (e.g. parent) to share any password data, but instead uses authorisation 'bearer' tokens to identify an entity. It is separate to the existing LDAP, SAML or proprietary Username/Password combination.
The OAuth2 method provides Mobile Apps with the ability to perform push notifications.
Parents and staff must log into their respective apps, consent to identification, and then the app receives a unique identifier to access OAuth2 API endpoints.
As a security provision, TASS has implemented PCKE to provide an extra layer of security in the authentication layer to prevent malicious attacks.
User Security Permissions
Access to this tab requires security permission.
Use TASS.web System Admin > Users > Security Role Permissions > Administration section > 'API Gateway Maintenance' > 'OAuth2 API Applications' permission.
Adding an OAuth2 Application
Click ‘Add OAuth2 Application’ and enter details.
OAuth2 Application Details | |
|---|---|
* Application ID | An alphanumeric text field (max 40 characters). This ‘Application ID’ code is also used as the 'School Code' to select your school when logging into the Parent Orbit and Staff Orbit app for the first time. |
* Application Type | Select from the drop-down menu. 'Parent' is currently the only option for third-party apps. 'Orbit Parent' is for users using TASS.web's parent mobile app. ‘Orbit Staff’ is for users using TASS.web’s staff mobile app. |
* Application Name | A text field (max 1,000 characters). |
* Login Title | A text field (max 400 characters). This will be displayed to parents and staff on the OAuth login screen (LDAP or TASS.web login only). |
* Authorisation Title | A text field (max 400 characters). This will be displayed to parents and staff on the OAuth login screen. |
* Redirect URI | A text field (max 1,000 characters). The App provider can provide this information. e.g. https://oauth.pstmn.io/v1/callback |
Redirect URI 2 | A text field (max 1,000 characters). |
Redirect URI 3 | A text field (max 1,000 characters). |
Redirect URI 4 | A text field (max 1,000 characters). |
* Session Expiry (days) | Enter the number of days the authorisation remains for (between 1 - 90). |
School Logo | Click 'Choose File' to locate and upload your school logo. |
OAuth2 Scope - API Access | |
For the 'Parent' application type, refer to the OAuth2 GitHub documentation for these details. For the ‘Orbit Parent' and 'Orbit Staff’ application types, select each component that you wish to share between TASS.web/Staff Kiosk and the app. | |
SAML Configuration | |
* SAML Enabled | Select ‘Yes’ or ‘No’. |
SP Entity ID | A user definable value used to identify the OAuth2 app in your SAML identity provider. |
SP Endpoint | This value is derived from the TASS.web product domain and Application Type. Format is: https://[tassweb product domain]/tassweb/api/[application type]/oauth/SAML/index.cfm eg. https://tasshub.kb.tassweb.com.au/tassweb/api/parent/oauth/SAML/index.cfm |
IDP Metadata URL | This is a URL that is obtained from the identity provider. Fetch IDP Metadata XML: Click to check if there is an entry in the IDP Metadata URL field and to populate the remaining fields. |
IDP Metadata XML | A free text field. |
Certificate (X.509) | An encrypted free text field. Click the ‘Extract IDP Certificate (X.509)’ button to generate the certificate (if it was not populated previously or if changes have been made). |
SP Metadata XML | This is a free text field. Click the ‘Generate SP Metadata XML’ button to generate (if it was not populated previously or if changes have been made). Click the ‘Download SP Metadata XML’ button to download the SP Metadata XML. This button will become active after performing a Save. |
SP Private Key | 'Add Private Key' is not required unless advised. |
Click ‘Save’ when complete.
Click the ‘Download SP Metadata XML’ button and re-upload the SP Metadata XML to the SAML IDP.
Where scopes are updated, i.e. permissions revoked, the user is automatically logged out so that the new scopes can be applied upon login.
For more information, refer to https://github.com/TheAlphaSchoolSystemPTYLTD/OAuth2
Editing an OAuth2 Application
Click the ‘Edit’ link in the Action column to make changes to the application.
Make the required changes, then click the ‘Update’ button.
Deleting an OAuth2 Application
Click ‘Delete’ in the Action column to delete the application.
Metadata Details
Click the ‘Metadata’ link in the Action column to access the Metadata Details screen.
Fields that require further explanation | |
|---|---|
* Accent Colour | Use this field to choose the accent colour that will be displayed in the app. Click the Colour icon beside this field to select a colour using your mouse, or enter a Hex Colour Code. e.g. #7d3333. |
* Highlight Colour | Use this field to choose the highlight colour that will be displayed in the app. Click the Colour icon beside this field to select a colour using your mouse, or enter a Hex Colour Code. e.g. #7d3333. |
Icon Colour | Use this field to choose the icon colour that will be displayed in the app. Click the Colour icon beside this field to select a colour using your mouse, or enter a Hex Colour Code. e.g. #7d3333. |
* Icon Colour Customisation | This field allows you to choose icon colour customisation preferences. Select ‘Default’ to use the default settings, or select the ‘Two tone colour: icon colour used with gradient’ option. |
Mandatory PIN Code / Biometric Authentication | When this checkbox is selected, Staff Orbit app users must enable either a PIN code or biometric authentication before accessing school data. This feature is currently available only for Staff Orbit. |
Disable In App Screenshots | When this checkbox is selected, Staff Orbit app users will not be able to take screenshots within the app. This feature is currently available only for Staff Orbit. |
App Link Label | Enter the text you want to appear on the call button in the Staff Orbit app. This feature will allow staff to initiate calls or chats directly from the app when the ‘App Link’ is configured in the field below. Examples: Teams Call, Zoom Call, Make a Phone Call. This feature is currently available only for Staff Orbit. |
App Link (Deeplink Address) | Enter the Deeplink address of the app that you want to use for the call button in the Staff Orbit app. Examples: Microsoft Teams, Zoom, SIP. This feature is currently available only for Staff Orbit. |