An application can have three types of interaction with a tenant: interactive user sessions; non-interactive background services; or hybrid.
SuperOffice CRM Online supports both types of interactions. The first as an application user context and the second as a system user context.
Internal applications have tight integration with user interface components inside SuperOffice. Applications that add a navigator button, a menu button, or a web panel commonly follow this model.
External applications are hidden integrations where most or all interaction happens at the partner's website or cloud.
Application user (interactive)
This is the typical case when a person is signed in to SuperOffice.
- Application is interactive/reactive
- Application has UI in SuperOffice
- Users have their own sign-in credentials
- Users have their own options
Applications are not allowed to directly ask users for their credentials, and therefore must use SuperOffice federated authentication to sign SuperOffice CRM Online users into their applications.
System user (non-interactive)
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 our web services. None of the OpenID Connect flows are supported.
The system user has unlimited access to the tenant and is not restricted by functional rights or data rights.
- The application runs in the background
- The application must bypass the sentry
- No UI elements in SuperOffice
- Runs as a service
To conduct true background processing, applications must use the system user token that was issued to them during the installation process. Applications use the SOAP-based
PartnerSystemUserService endpoint to exchange a system user token for a system-user ticket.
When used in a SOAP request, the system-user ticket is used as credentials, placed inside each SOAP header as seen in the
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope namespaces left out for brevity> <Contact:ApplicationToken>1234567-1234-9876</Contact:ApplicationToken> <Contact:Credentials> <Contact:Ticket>7T:1234abcxyzExample==</Contact:Ticket> </Contact:Credentials> <SOAP-ENV:Body> <Contact:GetContactEntity> <Contact:ContactEntityId xsi:type="xsd:int">0</Contact:ContactEntityId> </Contact:GetContactEntity> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
When used in a REST request, the system-user ticket is placed in the Authorization header as an SOTICKET.
Authorization: SOTicket 7T:1234abcxyzExample== SO-AppToken: Application_Token_Value
System users have unlimited access to the database and are not subject to any security or sentry constraints. System users cannot impersonate other users in the online environment.
See also the system user MVC example.
Hybrid applications can, as the name suggests, have some UI components inside SuperOffice CRM Online and can operate or be configured on a partner web portal. The majority of applications are hybrids.
Applications that use OAuth2/OpenID Connect to authenticate users via the Authorization Code flow, or Native App Flow, do receive a refresh token. The refresh token is (as of this writing) good for as long as the user is authorized to access the application, and can be securely stored on behalf of that user for subsequent API interaction.
To use a refresh token, the application must issue a POST request to the tokens endpoint with the following details:
- Client ID
- Client secret
- Redirect URI
- Grant type specified as
- The actual refresh token
An example POST request:
POST Request (can be tested in a client such as Postman or Fiddler) Content-Type: application/x-www-form-urlencoded https://sod.superoffice.com/login/common/oauth/tokens? client_id=f123b7d98f3c496fb5aaa4b1f54cawe6& client_secret=09d5f3bdf0afbc3bv9d0682e9b86lk89& redirect_uri=http://partner-app/callback& grant_type=refresh_token& refresh_token=t6XaHSHkTbB1234abcxyzExample
The response contains the
access_token necessary to issue in subsequent REST or SOAP requests.
When used in RESTful requests, the
access_token is placed in each request Authorization header using the Bearer prefix.
Accept: application/json Authorization: Bearer 8A:Cust12345.abcxyzExample==
Supported in version Services86 and higher, when used in SOAP requests, the
access_token is placed in each SOAP header.
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope namespaces left out for brevity> <Contact:ApplicationToken>1234567-1234-9876</Contact:ApplicationToken> <Contact:Credentials> <Contact:Ticket>8A:Cust12345.abcxyzExample==</Contact:Ticket> </Contact:Credentials> <SOAP-ENV:Body> <Contact:GetContactEntity> <Contact:ContactEntityId xsi:type="xsd:int">0</Contact:ContactEntityId> </Contact:GetContactEntity> </SOAP-ENV:Body> </SOAP-ENV:Envelope>