System user flow

•

Environment: cloud

• 3 minutes to read

The system user flow is how to obtain a Ticket credential to perform non-interactive server-to-server communications.

Note

In the future, system user functionality will be replaced with OAuth 2.0 Client Credentials flow.

Watch the walk-through on YouTube:

Overview

There are two prerequisites before one can begin using the System User flow:

The application has the System User option enabled.

It is enabled by selecting the Server to server option when creating an application in the Developer Portal.
The application has been issued a system user token.

A system user token is only available after someone with administrator rights uses the application to signs in to their tenant using OAuth 2.0/OpenID Connect. When the individual gives consent to the application, by clicking the I Approve button after authentication, the system user token is generated and issued as a claim in the id_token.

The system user token is:

formatted as: Application Name-<random-number-of-characters>
is unique for each tenant and application combination
will exist for the lifetime of the application
is included in the id_token claim collection

A system user token remains the same and will not change for the lifetime of the application, unless the customer or application vendor revokes it.

How to use the system user token to obtain a Ticket

The following procedure outline the steps necessary to use the system user token to obtain a Ticket credential.

Generate a signed System User token signature.
Send the signed system user token to the SuperOffice PartnerSystemUser endpoint.
In the response, validate the JSON Web Token (JWT).
Extract the Ticket claim from the JWT.

How to use the system user ticket credentials

An application can use the system user ticket credential in:

an Authorization header in HTTP requests
- Instead of Authorization Bearer <access_token>, use Authorization SOTicket <ticket>
- The SO-AppToken header must be included in the headers with the request.
  - The SO-AppToken value is the OAuth 2.0 client_secret.
an SoCredential ticket property in SOAP API

REST
SOAP

See the Authorization header:

GET https://sod.superoffice.com/Cust12345/api/v1/User/currentPrincipal HTTP/1.1
Authorization: SOTicket {{ticket}}
SO-AppToken: {{client_secret}}
Accept: application/json

See the <User:Credentials> and <User:ApplicationToken> elements:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope"
 xmlns:SOAP-ENC="http://www.w3.org/2003/05/soap-encoding"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:NetServerServices882="http://schemas.microsoft.com/2003/10/Serialization/Arrays"
 xmlns:NetServerServices881="http://schemas.microsoft.com/2003/10/Serialization/"
 xmlns:User="http://www.superoffice.net/ws/crm/NetServer/Services88">
  <User:ApplicationToken>1234567-1234-9876</User:ApplicationToken>
  <User:Credentials>
    <User:Ticket>{{ticket}}</User:Ticket>
  </User:Credentials>
 <SOAP-ENV:Body>
   <User:GetUser>
    <User:UserId xsi:type="xsd:int">0</User:UserId>
   </User:GetUser>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

With a valid credential set, the application can send authenticated requests to the customer tenant.