OIDC Federation Setup Guide (SSO)

This

Setting document describes the requirements for setting upUp Single Sign-On (SSO) viawith OpenIDAdhese

Connect

This (OIDC)guide betweenexplains what's needed to connect your company's login system (your "Identity ProviderProvider" (IdP)or andIdP — e.g. Okta, Azure AD, OneLogin, Keycloak) to the Adhese platform.platform, so your users can log in with their existing company account instead of a separate Adhese password.

We've tried to keep this guide free of unnecessary jargon. Where a technical term is unavoidable, we explain it in plain language the first time it appears.

It is probably best to direct your organizations' IdP responsible to this document, because they will be best suited to go through its steps.

---

1. Overview — how this works

WeThink useof OIDC-basedit identitylike federationusing to"Sign allowin with Google" on another website. Instead of Adhese storing a password for your users, your users to log in tothrough your own company system. Once they're verified there, your system tells Adhese "this person is who they say they are, and here's some basic info about them."

Your IdP = your company's login system. It does the actual authentication (checking passwords, MFA, etc.). Adhese platform= usingthe application your organisation'susers Identitywant Providerto (IdP).reach. OurWe platformjust actsneed asto the Service Provider (SP)/Relying Party (RP), whiletrust your IdPIdP's handlesconfirmation.

The technology that makes this handshake work is called OIDC (OpenID Connect) — a standard way for two systems to exchange "this user authentication.is verified, here's who they are" information.

---

2. InformationWhat Wewe Needneed Fromfrom Youyou

To configureconnect theto connectionyour on our side,IdP, we need thea followingsmall fromset of technical addresses and credentials. Your IT/identity team will have these, or can generate them when creating a new application/integration for Adhese in your IdP:IdP.

Item	DescriptionIn plain terms
Discovery URL	YourA OIDCsingle discoveryweb endpoint,address typicallythat https://<your-idp>/.well-known/openid-configuration.automatically tells us all the other addresses below. If notyour available,IdP provideprovides thethis individual(most endpointsmodern below.ones do), you usually don't need to give us anything else in this table.
Authorization endpoint	URLThe whereweb weaddress redirectyour users get sent to, to authenticatelog in. (Only needed if there's no discovery URL.)
Token endpoint	URLThe whereaddress we exchangeuse, behind the authorisationscenes, codeto forconfirm tokensthe login was real. (Only needed if there's no discovery URL.)
UserInfo endpoint	URLAn whereaddress we can retrievecheck additionalfor extra user claimsdetails, if needed. (Only needed if notthere's allno includeddiscovery in the ID token)URL.)
JWKS URI	URLThe address holding your IdP's "signature keys," which we use to yourconfirm publicnothing signingwas keystampered forwith. token(Only validationneeded if there's no discovery URL.)
Client ID	TheAn clientID identifier registered for Adhese innumber/string your IdP assigns to identify "the Adhese application" specifically.
Client Secret	TheA clientpassword-like secret associatedthat goes with the Client IDID, so we can prove to your IdP that we really are Adhese. Keep this confidential.

Client authentication method How we should send the Client ID/Secret when talking to your IdP: client_secret_post or client_secret_basic. Supported scopes Confirmation that your IdP can send us the requiredspecific scopespieces of information we need (see sectionSection 4) are available.

IfSimplest path: if your IdP supportshas a discovery endpoint,URL, mostyou ofreally theonly aboveneed canto begive derived automatically. In that case, providingus: the discovery URL, the Client ID, andthe Client SecretSecret, isand sufficient.the client authentication method.

---

3. InformationWhat Wewe Providegive To Youyou

YouTo willset needthings theup following from us to configureon your IdP:side, we'll send you:

Item	DescriptionIn plain terms
Redirect URI (Callback URL)	We will provide theThe exact redirectweb URIaddress thatyour IdP must be registeredtold asto ansend allowedusers callbackback into after login. You'll paste this into your IdP.IdP's app configuration, usually a field called "Redirect URI," "Callback URL," or "Allowed callback."
Required scopes	SeeWhich sectionpermissions/data 4your IdP setup needs to allow (see Section 4).
Required claims	SeeWhich sectionspecific 4pieces of user information must be included (see Section 4).

---

4. RequiredScopes and claims, explained simply

Think of it this way:

A scope is a permission you switch on in your IdP's app configuration. It's like ticking a box that says "yes, allow sharing this category of information." A claim is the actual piece of information that gets sent to us once that permission is switched on, like a labeled field with a value.

For example, ticking the email scope is what allows the email claim (the user's actual email address) to be included.

4.1 Scopes and Claimsclaims

Requiredwe Scopesrequire

Scope (the permission)	PurposeClaim it unlocks

What that claim contains 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 openidA Yes Unique userunique ID Unique identifiernumber for the useruser. Always required for any OIDC login — this is the standard itself. email email Yes Valid email address The user's email addressaddress. email email_verified emailA Yes true/false Mustflag beconfirming your IdP has actually verified that email address (e.g. via a confirmation link). This must come through as true. Users with email_verified: false or a missing email_verified claim will be denied access.

⚠️ Important: TheSome IdPs don't send email_verified claimautomatically, 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 tokeneven when the email scope is requested.enabled Additionally,— it's technically an optional field in the valueOIDC muststandard. bePlease double-check with whoever manages your IdP that this field is switched on and will read true —for usersyour whoseusers. emailIf addressit's hasmissing, notor beenset verifiedto atfalse, the IdP levellogin will not be able to log in.rejected.

Optional4.2 ScopesOptional: andshowing Claimsreal names in Adhese

TheEnabling the profile scope is not requiredrequired, but recommended. It enableslets us toshow displayyour user-friendlyusers' actual names in the Adhese UI.interface instead of just an ID or email address.

Scope

Claim ScopeWhat Requiredit Descriptioncontains profile name profile No Full display name given_nameprofile profilegiven_name No First name family_nameprofile profilefamily_name No Last name preferred_usernameprofile profilepreferred_username No Username

---

5. RoleClient Mappingauthentication method (Optional)client_auth_mode)

UserWhen rolesAdhese cantalks beto managedyour directlyIdP withinto confirm a login, we have to prove we are who we say we are, using the AdheseClient platform.ID However,and ifClient youSecret preferfrom Section 2. There are two common ways to managesend rolesthat centrallyproof, fromand your IdP,IdP will only accept one of them — so we supportneed automaticto roleknow assignmentwhich.

basedon Mode In plain terms client_secret_basic The Client ID and Secret are sent using a custombuilt-in claimweb standard called "HTTP Basic Authentication" — essentially packed into a request header, not visible in the main message body. client_secret_post The Client ID token.and

HowSecret Itare Works

sent

as Youregular choosefields inside the claimrequest nameitself (e.g.like filling in a form), adhese_role)rather than in a header.

Neither option is more or less secure in practice — it's purely about which format your IdP expects. Most modern IdPs support both, and their app registration screen will usually have a dropdown or setting labeled something like "Token endpoint authentication method." Please check this setting and let us know which namevalue youit's useset to, so we canconfigure configureour side to match. If we don't match your IdP's expectation, the login exchange will fail even if everything else is correct.

---

6. Role mapping

on

How ourit side.works

The

You (or your IdP admin) pick a claim name — for example adhese_role — and tell us that name. From then on, whatever value(s) come through in that claim will decide what roles the user gets in Adhese, updated automatically every time they log in.

The value can bebe:

One role, as plain text, or Several roles, as a single role (string) or multiple roles (array). Roles are mapped automatically on each login, so changes in your IdP are reflected immediately.list.

SingleOne role example:role:

{
  "adhese_role": "admin"
}

Multiple roles example:roles:

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

The important part: the claim name you chose becomes a normal, top-level field in the token, with the role name(s) as its value. Nothing more nested or wrapped around it.

Extra scope

If your idp expects us to send a specific scope before it embeds the custom claim in the token, you need to let us know the scope we have to request.

Available Rolesroles — Classic UI

Role	Description
classic_admin	Full admin.admin Hasaccess full permissions into the Classic UI.UI
classic_read_only	Read-only access to the Classic UI.UI

Available Rolesroles — 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

Examples

{
  "bidfood_role": "adheseAdmin"
}

If a user has more than one role:

{
  "bidfood_role": ["adheseAdmin", "adheseOtherRole"]
}

💡 Tip: Some IdPs also require you doto notseparately configureenable a scope before a custom claim will actually be included in the token — even if the claim itself looks correctly configured. For example, some setups need a params (or similarly named) scope explicitly requested before the custom role mapping,claim rolesshows willup at all. If your custom role claim isn't arriving, check whether an additional scope needs to be managedrequested, manuallyand withinlet theus Adheseknow platformits byexact anname administrator.so we can add it to our request.

---

6.7. Setup Checklistchecklist

Your side (IdP)

•  Register a new OIDC client/applicationapplication/client for Adhese
• Configure Add the redirect URI providedwe by usprovide as an allowed callback URL
• Ensure Enable the openid and email scopes are enabled
• Verify thatConfirm the email_verified claim is included inand thewill ID token with a value ofread true | if not, let us know

 Confirm which client authentication method your IdP uses: client_secret_post or client_secret_basic  (Optional) Enable the profile scope for real names  (Optional) ConfigureSet up a custom claim for role mappingmapping, making sure it outputs a plain value (see Section 6's common mistake) Share the(Optional) Confirm whether an extra scope is needed to expose that custom claim  Send us: Client ID, Client Secret, and discovery URL (or individual endpoints), withclient usauthentication method, wether or not email_verified claim will be set correctly

Our side (Adhese)

•  Provide the redirect URI
•  Configure the IdP connection with theyour provided endpoints and credentials
•  Configure the client authentication method to match yours

 Configure scope requests (openid, email, and optionally profile)  Configure essential claim validation forso email_verified must be true  (Optional) Configure role mapping based on the agreed custom claim  Perform a test login together

---

7.8. Testing

Once both sides are configured,set weup, recommendwe'll performingdo a jointtest test:login together:

1. InitiateStart a login on the Adhese platform
2. Verify thatConfirm the redirect to your IdP works correctly
3. AuthenticateLog in with a test user
4. Verify thatConfirm the callbackreturn trip back to Adhese succeeds
5. Confirm that the user's email and profilename information aredisplay correctly displayed
6. (If applicable) Confirm thatthe rolecorrect mappingrole(s) iswere applied correctly

If the test login fails

with an error related to the essential claim, the

The most common causescauses, are:in order of likelihood:

• The email scope isisn't notactually enabled on the IdP side
• The email_verified claim is notisn't included in the IDtoken tokenat all
• The user's email isisn't notmarked verified at the IdP level (email_verified: false)
• The client authentication method (Section 5) doesn't match what we configured on our side

A custom role claim contains the IdP's raw parameter configuration instead of a plain value (see the common mistake in Section 6)