User contexts - SuperOffice

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.

Requirement	SOAP	REST	Comments
User-interactive	X	X	Default workflow.
Non-interactive	X		System-user workflow.
Semi-interactive	X	X	`refresh_token` workflow.

Application user (interactive)

This is the typical case when a person is signed in to SuperOffice. Requirements:

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. Interactive authentication is facilitated by the SuperOffice Online sign-in page. This is discussed in the Authentication section.

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. Requirements:

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 ContactAgent.GetContactEntity method.

<?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.

Semi-interactive scenario

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 refresh_token
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>

​Application user (interactive)

​System user (non-interactive)

​Semi-interactive scenario

Application user (interactive)

System user (non-interactive)

Semi-interactive scenario