OAuth2 API Applications
Overview
Important!
Before configuring OAuth2 API Applications, please ensure you have a good understanding of the OAuth2 workflows within the OAuth2 GitHub documentation.
OAuth2 enables the TASS Parent Orbit, Staff Orbit, and Student Orbit apps, as well as other third-party products, to connect to TASS.web APIs as an entity (e.g., a parent) and uniquely identify them to return targeted data.
Coming Soon!
The Student Orbit app is still under development. Refer to the 'Student Orbit App' page on the TASS website for details, or contact TASS Licencing to enquire about getting Student Orbit for your school.
It does not require the entity (e.g., the parent) to share any password data; instead, it uses 'bearer' authorisation tokens to identify the entity. It is separate from the existing LDAP, SAML or proprietary Username/Password combination.
The OAuth2 method enables Mobile Apps to send push notifications.
Parents, staff, and students must log in to their respective apps, consent to identification, and then the app receives a unique identifier to access the OAuth2 API endpoints.
As a security measure, TASS has implemented PCKE to provide an additional layer of authentication protection against malicious attacks.
User Security Permissions
Access to this tab requires the ‘OAuth2 API Applications' security permission, which can be granted in TASS.web System Admin > Users > Security Role Permissions in the 'Administration’ section under 'API Gateway Maintenance'.
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, Staff Orbit and Student Orbit apps 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. ‘Orbit Student’ is for users using TASS.web’s student 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, staff and students 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, staff and students 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 and 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', ‘Orbit Staff’ and 'Orbit Student’ 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.
How to upload the SP Metadata XML to Microsoft Entra ID as an IDP
Create a new SAML application/entity in Microsoft Entra ID in Enterprise Applications, and click edit for the OAuth application. Note: This OAuth product cannot use the same Enterprise app as another portal product.
Go into the Single Sign-on tab, and look for the ‘Basic SAML Configuration’ section. Click ‘Edit’ on this section.
Click ‘Upload’ on the Upload metadata file (across the top) and upload the SP Metadata XML generated from the TASS software.
The metadata uploaded in the previous step should set the Identifier and Rely URL fields in Microsoft Entra ID, but here are the steps on how to also configure those fields manually:
In the Identifier (Entity ID) field in Microsoft Entra ID, delete the currently configured identifier. In this Microsoft Entra ID field, set the identifier to the TASS field "SP Entity ID" data configured in TASS.web System Admin > Utilities > API Gateway Maintenance > OAuth2 API Applications.
In the Reply URL (Assertion Consumer Service URL) field in Microsoft Entra ID, clear the currently configured URL, and then set the URL to the TASS field "SP Endpoint" URL found in TASS.web System Admin > Utilities > API Gateway Maintenance > OAuth2 API Applications.
When scopes are updated (i.e., permissions are 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 default 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. Parent Orbit colours can be changed in Parent Orbit Setup, and Student Orbit in Student Orbit Setup. |
* Highlight Colour | Use this field to choose the default 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. Parent Orbit colours can be changed in Parent Orbit Setup, and Student Orbit in Student Orbit Setup. |
Icon Colour | Use this field to choose the default 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. Parent Orbit colours can be changed in Parent Orbit Setup, and Student Orbit in Student Orbit Setup. |
* Icon Colour Customisation | This field lets you choose default preferences for icon colour. Select ‘Default’ to use the default settings, or select the ‘Two tone colour: icon colour used with gradient’ option. Parent Orbit colours can be changed in Parent Orbit Setup, and Student Orbit in Student Orbit Setup. |
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. |