> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://support.contracthero.com/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # 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 `.`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. ![](https://storage.crisp.chat/users/helpdesk/website/-/1/2/5/2/12522a019f980500/image1_17e0s68.png) ### 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**. ![](https://storage.crisp.chat/users/helpdesk/website/-/1/2/5/2/12522a019f980500/image-2_tadugn.png) ![](https://storage.crisp.chat/users/helpdesk/website/-/1/2/5/2/12522a019f980500/image3_oezvpq.png) Back in Microsoft: choose **Web** as the platform and paste the redirect URL into the field. ![](https://storage.crisp.chat/users/helpdesk/website/-/1/2/5/2/12522a019f980500/image4_1w1ji5m.png) 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. ![](https://storage.crisp.chat/users/helpdesk/website/-/1/2/5/2/12522a019f980500/5_18reyqp.png) ### 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. ![](https://storage.crisp.chat/users/helpdesk/website/-/1/2/5/2/12522a019f980500/6_zj5aok.png) ### 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. ![](https://storage.crisp.chat/users/helpdesk/website/-/1/2/5/2/12522a019f980500/7_1rgn4ah.png) ### 7. Create a client secret In the left-hand menu choose **Certificates & secrets**, open the **Client secrets** tab and click **New client secret**. ![](https://storage.crisp.chat/users/helpdesk/website/-/1/2/5/2/12522a019f980500/8_18mpb2b.png) 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 (`.app.contracthero.com`) and test the login. ![](https://storage.crisp.chat/users/helpdesk/website/-/1/2/5/2/12522a019f980500/9_jfqlag.png) ## 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. ## Related articles * [Microsoft Entra SSO fails: Client secret expired — how to fix it](https://support.contracthero.com/en-us/article/microsoft-entra-sso-fails-client-secret-expired-how-to-fix-it-r6n21w/) * [How can I create new roles?](https://support.contracthero.com/en-us/article/how-can-i-create-new-roles-14s3bj/) * [Invite users and manage permissions](https://support.contracthero.com/en-us/article/invite-users-and-manage-permissions-1yk66eu/)