Standard applications are listed in the app store and are availability for all online customers. These are applications who are owned, operated by and the responsibility of SuperOffice partnters.
Custom applications are unique one-off integrations build for a specific customer. Each custom app, reguardless if it is the same basic functionality installed and used by another customer, will have a unique application identifier and application token, per customer.
Each application type generally falls into one of the following application model categories. Application models represent how customers will interact with applications.
- Internal Application: Tight integration with UI components inside SuperOffice CRM Online.
- External Application: Hidden integration with most/all interactions occur on partner web site or in partners cloud.
- Hybrid Application: Can have some UI components inside SuperOffice CRM Online, and can operate or be configured on a partner web portal.
applications never ask for username or password, all users must use SuperOffice Online login page!
For both standard and custom application, the application must provision the customer accordingly.
Provisioning is accomplished by a tenant administrator user installing the application and interacting with the applications provisioning routines. Interacting with an application provisioning routines means the user successfully logs into SuperID, is then forward to the applications installation pages, and the application begins to use the administrative credentials it received from SuperID to access and setup the tenant by the API's.
Setting up the tenany by the API's means the application creates whatever it needs to exist and function inside SuperOffice. This could be web panels, buttons, lists and list items, etc.
For custom applications, this could be automated, but is generally more of a manual step. For both, however, the tenant administrative user will have to sign-in to SuperID and approve the application to establish an authorization record between the application and the tenant.
When approved, the application receives a JWT token containing all the claims needed to connect to and communication with the tenant web services. More information about authentication and claims are in the Security and Authentication article.
There are two types of interaction applications have with tenant installations.
- Interactive user session.
- Non-interative background servies.
SuperOffice CRM Online supports both types of interactions. The first as a normal user and the second as a system user contexts.
Normal User Context
Once an administrator installs an application, normal users will be able to interact with their new application via web panels or clicking a button that opens a new window to the applications cloud, or portal.
Application are not allowed to directly ask users for their credentials, and therefore must use SuperOffice federated authentication to sign SuperOffice online users into their applications.
The typical requirements for a normal user context are:
- Application is interactive/reactive
- Application UI in SuperOffice
- Users have their own logins
- Users have their own options
System User Context
All applications that run as background tasks, without user interaction, must receive a system user token, and use the System-User Flow for interacting with tenant web services. A system user token is included in the JWT claims when an administrator installs the application, and is used to obtain a valid system user ticket credential. Under these circumstances, conducting background processing, none of the OpenID Connect flows are supported.
The system user ticket is used to as an authentication token when it submits web service requests to the tenant API's.
The system user token is a string formatted as NAME_OF_APP- + some_random_characters.
System User Tokens
A system user token is included in the SAML/JWT claims collection after an administrator or user successfully authenticates and installs, or uses, the application. It is a string of characters that is unique for each tenant-application, and will exist for the lifetime of the application. The system user token is used to call SuperID and exchange it for a valid system user ticket credential.
With a system user ticket credential, an application can use the ticket string to set the credential; either as an SoCredential Ticket property in SOAP API, or as a SOTicket header in the REST API. With a valid credential set, the application can connect to and process data with the customer tenant.
The typical requirements for a system user context are:
- Application runs in the background
- Application must bypass sentry
- No UI elements in SuperOffice
- Runs as a service
A system user token is a contract between an application and a tenant. A tenant administrator is prompted to grant access to the application to the tenants web services when the application is installed. With consent given to the application, a system user token is generated and appended to the application in SuperOffice Online as an Application Authorization record. The application authorization record binds the application to the tenant. The system user token is then included as one of the claims in the SAML/JWT security token that is sent to the redirect during the callback phase.
All applications must have a redirect URL, and after the administrator clicks the Allow button that generates the Application Authorization, SuperOffice Online redirects the adminisrator to the applications redirect URL.
The application residing at the redirect URL is expected to receive the security token from the request body, validate the security token, and then can reliably access the claims contains in the security token.
With access to the system user token claim, it's up to the application to securely store the system user token. Then, the application can use it for all future background processing by exchanging the system user token for a system user ticket.