SuperOffice Online OAuth 2.0 and OpenID Connect

•

Environment: cloud

• 7 minutes to read

SuperOffice Online offers OAuth 2.0 and OpenID Connect identity protocols for front-channel API access, where users are interactive and present. For back-channel communications, it employs the proprietary System User flow.

Prerequisites

To access tenant web services, a registered application is necessary. If you haven't registered as an app developer yet, submit this developer registration form to create your developer account. For those with a developer account wanting to create a new application, use the Developer Portal and read the Developer Portal docs for guidance.

Upon registered, you will receive 2 application identifiers:

Application ID - this is the OAuth client_id: 4e5e6f90f529fede129bd25ad
Application token - this is the OAuth client_secret, do not share this. 74252df1e0119f1913f64c6d8d

OAuth 2.0 vs OpenID Connect

OAuth 2.0 and OpenID Connect are related but serve different purposes. OAuth 2.0 is an authorization framework, while OpenID Connect is an authentication protocol built on top of OAuth 2.0.

OAuth 2.0 overview

Purpose: OAuth 2.0 is designed for authorization, allowing users to grant third-party applications access to their resources on another service without sharing their credentials.

Key components

Resource Owner (User): The user who grants access to their resources.
Resource Server: The server hosting the resources.
Client: Your application acts on behalf of the user or accesses their data after obtaining permission. The client is also known as the Relying Party (RP).
Authorization Server: The server that issues access tokens to the client after authenticating the resource owner. Responsible for prompting to grant access to the client.

SuperOffice uses two authorization servers, superid and central-superid.

Main features

Delegated access to resources through access tokens.
Multiple grant types to support various use cases (for example, implicit, hybrid and authorization code). SuperOffice does not support client credentials, and resource owner password credentials.
Token-based communication between components for security.
Revocable and time-limited access tokens.

OpenID Connect

Purpose: OpenID Connect extends OAuth 2.0 to provide authentication, allowing users to securely authenticate with a single identity provider (IdP) and use their identity to access various applications and services.

Key components

Identity Provider (IdP): A service that securely stores and manages user identities and authentication (e.g., Google, Facebook, Microsoft).
Relying Party (RP) or Client: An application or service that relies on the IdP for user authentication.
End-User: The person who wants to access the RP using their identity from the IdP.

Main Features

Authentication built on top of OAuth 2.0.
Uses ID Tokens (JSON Web Tokens) to communicate user authentication information between the IdP and the RP.
Standardized user profile data using UserInfo endpoint. SuperOffice does not support the standardized OIDC endpoint, instead clients must use the https://{env}.superoffice.com/{tenantId}/api/v1/User/currentPrincipal endpoint.
Supports single sign-on (SSO) and single logout (SLO) across multiple applications and services. SuperOffice allows federated single sign-on to the application, with one possible exception - in a web panels (iframe)

OpenID Connect

Access Tokens and Authorization Codes

Access tokens demonstrate proof of authorization, showing that a user has approved client access, restricting it to a specific duration and scope. Authorization codes are intermediate tokens issued during the Authorization Code flow, used by the client to obtain an access token.

ID tokens

ID tokens are encoded JSON web tokens (JWTs) containing user-profile information. They consist of three elements: HEADER.PAYLOAD.SIGNATURE. These tokens include required claims like subject, issuing authority, audience, issue date, and expiration date, as well as optional claims for validation purposes.

ID tokens are used to access information about the signed-in user, personalizing and enhancing their experience. They are time-limited and must be validated upon receipt.

Claims and scopes

OpenID Connect uses claims and scopes to define user information. Claims provide identity details, while scopes define resource access. SuperOffice Online supports one scope, 'openid,' which grants access to all APIs and claims.

OIDC flows

OIDC defines 3 authentication flows:

Authorization Code flow: The recommended flow for interactive applications, where the client receives an authorization code to obtain access and refresh tokens.
Hybrid flow: Combines the Authorization Code and Implicit flows, offering flexibility but less security.
Implicit flow: A less secure flow where the client receives an ID token and access token directly.

Caution

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.

Integrating SuperOffice Online and SuperID

With a solid understanding of OAuth 2.0 and OpenID Connect, you can now effectively integrate SuperOffice Online and SuperID into your application. By using the recommended Authorization Code flow, you can ensure that your application is secure and compliant with industry standards.

To successfully implement SuperOffice Online and SuperID, follow these steps:

Register your application and obtain the necessary credentials (Application ID and Application token).
Set up your application to use the appropriate OAuth 2.0 and OIDC components and flows.
Ensure your application securely stores ID tokens and validates them upon receipt.
Utilize claims and scopes to access user information and enhance the user experience in your application.

By following these guidelines, you can create a seamless, secure, and user-friendly experience for your application users while adhering to industry standards and best practices.