OIDC Federation Setup Guide (SSO)

OIDC Federation Setup Guide

This document describes the requirements for setting up Single Sign-On (SSO) via OpenID Connect (OIDC) between your Identity Provider (IdP) and the Adhese platform.

1. Overview

We use OIDC-based identity federation to allow your users to log in to the Adhese platform using your organization's Identity Provider. Our platform acts as the Service Provider (SP) / Relying Party (RP), and your IdP handles user authentication.

2. Information We Need From You

To configure the connection on our side, we need the following from your IdP:

Item	Description
Discovery URL	Your OIDC discovery endpoint, typically `https://<your-idp>/.well-known/openid-configuration`. If not available, provide the individual endpoints below.
Authorization endpoint	URL where we redirect users to authenticate
Token endpoint	URL where we exchange the authorization code for tokens
UserInfo endpoint	URL where we can retrieve additional user claims (if not all included in the ID token)
JWKS URI	URL to your public signing keys for token validation
Client ID	The client identifier registered for Adhese in your IdP
Client Secret	The client secret associated with the Client ID
Supported scopes	Confirmation that the required scopes (see section 4) are available

If your IdP supports a discovery endpoint, most of the above can be derived automatically. In that case, providing the discovery URL, Client ID, and Client Secret is sufficient.

3. Information We Provide To You

You will need the following from us to configure your IdP:

Item	Description
Redirect URI (Callback URL)	We will provide the exact redirect URI that must be registered as an allowed callback in your IdP.
Required scopes	See section 4
Required claims	See section 4

4. Required Scopes and Claims

Required Scopes

Scope	Purpose
`openid`	Mandatory for OIDC. Returns the `sub` (subject) claim.
`email`	Required. Must return the `email` and `email_verified` claims.

Required Claims

Claim	Scope	Required	Expected Value	Description
`sub`	`openid`	Yes	Unique user ID	Unique identifier for the user
`email`	`email`	Yes	Valid email address	The user's email address
`email_verified`	`email`	Yes	`true`	Must be `true`. Users with `email_verified: false` or a missing `email_verified` claim will be denied access.

Important: The email_verified claim is an optional claim per the OIDC specification, meaning IdPs are not required to include it by default. Please verify that your IdP is configured to include this claim in the ID token when the email scope is requested. Additionally, the value must be true — users whose email address has not been verified at the IdP level will not be able to log in.

Optional Scopes and Claims

The profile scope is not required but recommended. It enables us to display user-friendly names in the Adhese UI.

Claim	Scope	Required	Description
`name`	`profile`	No	Full display name
`given_name`	`profile`	No	First name
`family_name`	`profile`	No	Last name
`preferred_username`	`profile`	No	Username

5. Role Mapping (Optional)

User roles can be managed directly within the Adhese platform. However, if you prefer to manage roles centrally from your IdP, we support automatic role assignment based on a custom claim in the ID token.

How It Works

You choose the claim name (e.g., adhese_role) — let us know which name you use so we can configure the mapping on our side.
The claim value can be a single role (string) or multiple roles (array).
Roles are mapped automatically on each login, so changes in your IdP are reflected immediately.

Single role example:

{
  "adhese_role": "admin"
}

Multiple roles example:

{
  "adhese_role": ["viewer", "creative_approver"]
}

Available Roles — Classic UI

Role	Description
`classic_admin`	Full admin. Has full permissions in the Classic UI.
`classic_read_only`	Read-only access to the Classic UI.

Available Roles — New UI

Role	Description
`admin`	Full administrator
`creative_approver`	Can approve creatives
`creative_master`	Full creative management
`managed_ad_master`	Managed advertising management
`self_service_ad_master`	Self-service advertising management
`viewer`	Read-only access
`access_all_advertisers_debtors_brands`	Access across all advertisers, debtors, and brands

If you do not configure role mapping, roles will be managed manually within the Adhese platform by an administrator.

6. Setup Checklist

Your side (IdP)

Register a new OIDC client/application for Adhese
Configure the redirect URI provided by us as an allowed callback URL
Ensure the openid and email scopes are enabled
Verify that the email_verified claim is included in the ID token with a value of true
(Optional) Enable the profile scope
(Optional) Configure a custom claim for role mapping
Share the Client ID, Client Secret, and discovery URL (or individual endpoints) with us

Our side (Adhese)

Provide the redirect URI
Configure the IdP connection with the provided endpoints and credentials
Configure scope requests (openid, email, and optionally profile)
Configure essential claim validation for email_verified
(Optional) Configure role mapping based on the agreed custom claim
Perform a test login together

7. Testing

Once both sides are configured, we recommend performing a joint test:

Initiate a login on the Adhese platform
Verify that the redirect to your IdP works correctly
Authenticate with a test user
Verify that the callback to Adhese succeeds
Confirm that the user's email and profile information are correctly displayed
(If applicable) Confirm that role mapping is applied correctly

The email scope is not enabled on the IdP
The email_verified claim is not included in the ID token
The user's email is not verified at the IdP level (email_verified: false)