SuperOffice Online and SuperID
For front-channel API access, when users are present and interactive, SuperOffice Online supports OAuth 2.0 and OpenID Connect identity protocols.
For back-channel communications SuperOffice provides the proprietary System User flow.
Access to tenant web services requires a registered application. If your not already registered as an app developer with us, please submit this developer registration form to create your developer account.
If you already have a developer account, and just want to create a new application, use the Developer Portal to register your new application. Read the Developer Portal docs to become more familiar with how to create and manage your application.
Once registered, you will receive 2 application identifiers:
- Application ID - this is the OAuth client_id:
- Application token - this is the OAuth client_secret, do not share this.
Introduction to OAuth 2.0
OAuth is an open, industry-standard specification for token-based authorization. It allows 3rd-party applications to obtain limited access to an HTTP service.
The OAuth 2.0 spec refers to the user as a Resource Owner. Any application that wants to act on behalf of a user must first get permission from them to access their data and services.
This is your application acting on behalf of the user or accessing the user's data. Needs to obtain permission before accessing the user's account.
This server has a dual role:
- Prompts the user to grant the client access to user-tenant resources
- grants access tokens to the client after authorization has been granted
SuperOffice has two,
central-superid. Each interacts with the roles above, respectively.
The OAuth access token is proof of authorization:
- shows that user A has approved client X
- restricts access to a specific duration and scope
- provides other information the server may need
The OAuth Authorization Code is an intermediate token issued to the Client during Authorization Code flow. The client uses this code to obtain an access token.
Limitations in OAuth 2.0
With an OAuth access_token, the user proved they were presented to the Authorization Server. However, the sole purpose of this was to create and grant an access token to the client application.
The user does not authenticate directly with an online application itself. OAuth is limited in that it provides a type of pseudo authentication:
- OAuth provides temporary access to resources rather than information about the authentication itself.
- OAuth doesn't provide the when, where, and how the authentication occurred.
- OAuth doesn’t allow federated single sign-on.
To understand how OpenID Connect (OIDC) works, we’ll review basic concepts such as participants, ID tokens, claims and scopes, and endpoints.
Open ID Connect is a thin layer that sits on top of the OAuth 2.0 protocol. It extends OAuth so that online applications can get identity information and retrieve details about the authentication event.
- OIDC enables clients to verify the identity of a (human) user based on the authentication done by an Authorization Server
- OIDC allows federated single sign-on to the application, with one possible exception
- OIDC is required because OAuth provides authorization only, not authentication
|SuperOffice term||Role||OpenID Connect term|
|Tenant end-user||Resource Owner||Resource Owner|
|SuperOffice SuperID||Identity provider||OAuth 2.0 Authorization Server|
|Partner application||Relying Party||OAuth 2.0 client|
This is the tenant user for whom we are requesting identity information. Also known as the OAuth Resource Owner. One of the resources they own is their own identity.
This is your application. It relies on the identity provider to authenticate users and request claims about that user. Also known as the Relying Party.
Identity provider (IdP)
This is the OAuth 2.0 Authorization Server:
- offers authentication as a service
- ensures the user is authenticated
- provides claims about the user and the authentication event to the Relying Party
- has multiple endpoints
So how does the OpenID Connect identity provider give the Relying Party information about the identity of the end-user? The answer is through an ID token.
ID tokens are encoded JSON web tokens (JWTs) used in token-based authentication to cache user-profile information for the signed in user. Each JWT consists of 3 elements separated by a period:
The ID token is similar to an ID card or a passport. It contains multiple claims about the user, including which identity provider authenticated the user. The following claims are required:
- Subject: a unique identifier assigned to a user by the identity provider, for example, a username
- Issuing authority: the identity provider that issued the token
- Audience: identifies the Relying Party or partner application, that can use the token
- Issue date: the date and time the token was issued
- Expiration date: the date and time the token will expire
There are also optional claims that help the Relying Party validate the ID token. For example:
- Authentication time, which shows the time the user was authenticated
- Nonce values, which mitigate replay attacks
How is the ID token used?
The ID token is primarily a means to access information about the currently signed-in application user. It:
- is typically used for UI display
- can be used to personalize and enhance the user experience
- is time-limited and needs to be verified upon receipt
Where does the ID token come from?
You will receive the ID token in the final response of the Authorization Code flow.
The contents should not be trusted until the token has been validated.
It is up to the application to securely store the ID token.
Claims and scope
OpenID Connect uses claims and scopes to define user information. Claims generally provide details about the user's identity. Scope is commonly used to define what resources a user has access to.
The OpenID Connect specification contains about 20 standard claims and 4 standard scopes. These are used to supply the client application with consented user details.
OpenID Connect standard ID token claims:
|Claim name||Federated ID||OpenID Connect||Description|
||X||X||The service principal name (SPN) claim identifier followed by the tenant database serial number.|
||X||X||Expiration time on or after which the ID token must not be accepted for processing.|
||X||Code hash value.|
||X||Time at which the JWT was issued.
Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
||X||X||An identifier for the issuer of the response. Options:
SuperOffice AS (federated ID)
||X||X||The time before which the JWT must not be accepted for processing.|
||X||A string used to associate a client session with an ID token and to mitigate replay attacks.|
Always the same as the claim:
SuperOffice Online supports 1 scope only: openid. The access granted by this one scope include access to all APIs, and all claims normally obtained at the userInfo endpoint - which isn't supported. Profile claims are in the ID token, and listed in the JWT validation documentation.
OpenID Connect flows
Now let’s look at the authentication flows available in OpenID Connect, and how ID tokens and user information are exchanged.
OpenID Connect defines 3 authentication flows:
The Authorization Code and Implicit OpenID Connect flows are based on the OAuth flow with the same name. The main difference between the OpenID Connect and OAuth counterparts is the ID token. If the implicit OAuth flow is best suited for your application, you can assume that the Implicit OIDC flow is also the best choice. Similarly for the Authorization Code flows.
In this illustration, application I users the Implicit flow while application A uses the Authorization Code flow.
The Hybrid flow is a combination of the Authorization Code and Implicit flow. In this flow, the client can request ID tokens, access tokens, or both from the authorization endpoint, along with an Authorization Code.
- The code can be exchanged at the token endpoint for the remaining tokens. This is useful in situations such as single sign-on, where the partner application needs to immediately use an ID token to access the user’s identity.
- The code is used to request access and the refresh token to get long-lived access to resources.
The Hybrid flow offers more flexibility with this token flow, but it’s less secure than the Authorization Code flow because some tokens are exposed directly to the user agent.
We recommend all interactive applications use Authorization Code flow with PKCE where appropriate. Implicit and Hybrid flow are not secure enough and should be avoided at all costs. Deprecated.