How do I set up custom single sign-on (SSO)?

What's in it for you


  • A two-stage access concept — sign-in runs through your identity platform, with optional 2FA managed there.
  • Your own login domain — a dedicated URL for your account, so people sign in on a domain carrying your company name.
  • Central user management — access is governed in Microsoft or Okta. When an employee leaves, access ends automatically.
  • A standard protocol, no custom build — connected over OpenID Connect to Microsoft Entra ID, Azure AD or Okta.


In practice that means fewer password-reset tickets, better security, and much simpler on- and offboarding.


Supported identity platforms


  • Microsoft Entra ID (formerly Azure AD)
  • Azure AD (legacy name)
  • Okta


Every connection runs over OpenID Connect. If you use a different IdP, talk to us — we'll assess feasibility case by case.


Before you start


  • Access to ContractHero with the owner role, including the Security („Sicherheit") tab in the settings.
  • Access to Microsoft Entra / Azure (or Okta) with enough rights to create app registrations and client secrets.
  • SSO is enabled on your plan — check with your Customer Success Manager if you're unsure.


How the rollout works


  1. A short exchange. You tell us which identity platform you want to connect (Microsoft Entra ID, Azure AD, Okta) and who your technical contact with admin rights is.
  2. Preparation on our side. We take care of everything needed on the ContractHero end and hand your IT admin the step-by-step guide plus the redirect URL.
  3. Your IT sets it up. Your admin works through the steps below independently.
  4. Rollout to existing users. Existing users sign out once and sign back in via the new domain using SSO.


Step by step: Microsoft Entra ID / Azure AD


The walkthrough below uses Microsoft Entra ID as the example. For Okta setups we provide an adapted guide.


1. Prepare in ContractHero


Open ContractHero and go to Settings → Security („Einstellungen → Sicherheit").


Set your custom prefix („Benutzerdefinierter Prefix") — typically your company name. That gives you a login URL of the form <prefix>.app.contracthero.com, which is where SSO sign-in happens later.


Careful: lowercase letters only. Once the team prefix is set, changing it afterwards is not straightforward.


Click Update („Aktualisieren").


2. Create an app registration in Microsoft Entra


Sign in to the Microsoft Entra admin center. There are two routes to app registrations:


  • Option A — Microsoft Azure (portal.azure.com): search for Entra ID, then in the left menu choose Identity → App registrations.
  • Option B — Microsoft Admin Center: choose Identity in the left menu, which opens Microsoft Entra, then Applications → App registrations.


Click New registration at the top.






3. Register the application


Give the app a name (for example ContractHero).


Make sure supported account types is set to accounts in this organizational directory only (your company's name).


Switch to ContractHero and copy the redirect URL.








Back in Microsoft: choose Web as the platform and paste the redirect URL into the field.




Click Register.


If you aren't redirected, open ContractHero in a new tab.


4. Get the discovery URL


With Overview selected in Microsoft's left-hand navigation, click the Endpoints button.


A popup appears. One of the rows is the OpenID Connect metadata document, also known as the discovery URL. Copy it.


Back in ContractHero (Settings → Security), tick allow login with OpenID Connect („Login mit OpenID Connect erlauben") and paste the discovery URL into the field.





5. Copy the client ID from Microsoft


Switch back to the Microsoft tab. On the Overview page you'll find a value labelled Application (client) ID.


Copy it and paste it into the client ID field in ContractHero.





6. Configure authentication in Microsoft


In Microsoft Entra ID, select Authentication.


Choose Add a platform, then Web.


A dialog opens. Paste in the redirect URL you copied from ContractHero earlier.






7. Create a client secret


In the left-hand menu choose Certificates & secrets, open the Client secrets tab and click New client secret.






Pick an expiry (12 months, for example) and set yourself a reminder.


Careful: if the expiry date passes without the secret being renewed beforehand, signing in to ContractHero stops working entirely.


Copy the client secret — the Value, not the Secret ID — into the client secret field in ContractHero.


Important: Microsoft shows the value only once. If you don't copy it straight away, you'll have to create a new secret.


8. Save and test


Save the configuration in ContractHero, go to your custom domain (<prefix>.app.contracthero.com) and test the login.





Linking SSO to existing ContractHero accounts


Existing users have to confirm the connection twice, once:


  1. On their first visit to the new domain, they click sign in with OpenID Connect.
  2. They are then asked to sign in once more with email and password — this is how ContractHero links the OpenID login to their existing account.
  3. The next step completes the link.
  4. From then on they only ever use OpenID Connect; no password needed.


New users can sign in with OpenID Connect straight away — no double confirmation.


Common questions


Which identity providers are supported?
Microsoft Entra ID, Azure AD and Okta, all over OpenID Connect. Others (Google Workspace, JumpCloud) on request.


Do I need SAML, or is OpenID Connect enough?
Custom SSO currently runs exclusively over OpenID Connect. SAML is not part of the standard offering — talk to us if you specifically need it.


Can new users be provisioned automatically (SCIM)?
Today you create users in ContractHero by invitation. Native transfer of user roles from Microsoft into ContractHero is on the development roadmap.


What happens when the client secret expires?
SSO sign-in breaks. You'll need to create a new client secret in Microsoft Entra and save it in ContractHero — best done before it expires, with a calendar reminder.


Can existing users still sign in with email and password?
Once the OpenID link is complete, access runs entirely through your identity platform.


How long does setup usually take?
From the first exchange to going live, typically one to two weeks, depending on your IT admin's availability. The setup work itself takes minutes.


Who can access the Security area in ContractHero?
Only users with the owner role.


Good to know


  • Put the expiry in your calendar before you save. Note the client secret's expiry date, ideally two weeks ahead. An expired secret blocks every SSO login.
  • Test with an IT admin account first. Don't switch SSO on for everyone before one admin login has worked end to end.
  • Warn existing users in advance. The one-off double confirmation on first OpenID login confuses people who weren't told about it. A short internal email before the rollout saves support tickets.
  • Use the setup support. If Microsoft Entra or Okta isn't familiar territory, we'll do the setup together in an onboarding session.
  • Store the client secret safely. Microsoft displays the value once only.



Updated on: 09/04/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!