Skip to content
Contracko Logo Documentation
Login
Documentation

Set up single sign-on (SSO)

Single sign-on (SSO) lets your team sign in to Contracko through your existing identity provider, so IT controls access from one place. Contracko supports self-serve OIDC single sign-on on the Big Business plan. You can connect Microsoft Entra, Google Workspace, Okta, Auth0, JumpCloud, Keycloak, or any OIDC-compliant provider. SAML 2.0 is available on request.

This guide walks through the full setup: verify your domain, create an app in your identity provider, connect it in Contracko, test it, and turn on enforcement.

Before you start

You will need:

  • The Big Business plan. SSO settings are only available on Big Business.
  • An admin, owner, or billing-owner role in your Contracko workspace.
  • Two-factor authentication (2FA) enabled on the billing owner's account. The billing owner is the one account that can still sign in with a password if your identity provider is ever unavailable, so Contracko requires that account to have 2FA before you can connect a provider or turn on enforcement. The billing owner can set this up under Settings, or at /totp/setup.
  • Admin access to your identity provider (to create an OIDC app).
  • Access to your DNS records (to verify your domain).

You configure everything under Settings > Security (/account/security).

Step 1: Verify your domain

Before you can connect a provider, verify at least one company domain. A verified domain is what lets you later require SSO for everyone on that domain.

  1. Go to Settings > Security and find the Verified domains card.
  2. Click Add domain and enter your bare company domain, for example yourcompany.com. Do not include https://, www., or a trailing slash. Subdomains count as separate domains.
  3. Contracko shows a DNS TXT record to add, in the form contracko-domain-verification=.... Copy it.
  4. Add that TXT record to your domain at your DNS provider.
  5. Back in Contracko, click Verify next to the domain. DNS changes can take up to 48 hours to propagate; once the record is live, verification succeeds and the domain shows a green Verified badge.

Verifying yourcompany.com also covers its subdomains, such as [email protected] and [email protected].

Step 2: Create an OIDC app in your identity provider

In your identity provider, create a new OIDC (OpenID Connect) web application. You will need the redirect URI that Contracko shows you during Step 3:

https://app.contracko.com/api/auth/sso/callback/<your-provider-id>

Open Settings > Security > Single sign-on > Add provider, pick your provider, and Contracko displays the exact redirect URI to paste. (For the generic "Other" option the redirect URI appears on the test step, after you save, so add it to your provider before running the test.)

From your identity provider you will collect a Client ID and Client secret, plus one provider-specific value below.

Microsoft Entra

  1. In the Azure Portal, go to Microsoft Entra ID > App registrations > New registration.
  2. Under Redirect URI, choose platform Web and paste the redirect URI from Contracko.
  3. On the Overview page, copy the Application (client) ID and the Directory (tenant) ID.
  4. Go to Certificates and secrets > New client secret and copy the secret Value (not the Secret ID).
  5. In Contracko, enter the Directory (tenant) ID. Use your tenant-specific ID, not common, so sign-in is locked to your tenant. Contracko builds the issuer URL for you.

Google Workspace

  1. In the Google Cloud Console, go to APIs and Services > Credentials > Create credentials > OAuth client ID.
  2. Choose application type Web application.
  3. Under Authorized redirect URIs, add the redirect URI from Contracko.
  4. Copy the generated Client ID and Client secret.
  5. In Contracko, enter your Expected hosted domain, which is your Google Workspace primary domain (for example yourcompany.com). Only accounts from that domain are allowed to sign in. Google always uses the same issuer, so there is no issuer URL to enter.

Okta

  1. In the Okta Admin Console, go to Applications > Create App Integration.
  2. Choose OIDC - OpenID Connect and application type Web Application.
  3. Under Sign-in redirect URIs, add the redirect URI from Contracko.
  4. Copy the Client ID and Client secret from the application's General tab.
  5. In Contracko, enter your Okta domain (for example your-company.okta.com). No https://, no trailing slash, no path. Contracko builds the issuer URL for you.

Auth0

  1. In the Auth0 Dashboard, go to Applications > Create Application.
  2. Choose application type Regular Web Application.
  3. Under Settings > Allowed Callback URLs, add the redirect URI from Contracko.
  4. Copy the Client ID and Client Secret from the Settings tab.
  5. In Contracko, enter your Auth0 tenant, which is the part before .auth0.com in your tenant URL. Contracko builds the issuer URL for you.

JumpCloud

  1. In the JumpCloud Admin Portal, go to SSO Applications > Add New Application.
  2. Select Custom OIDC App.
  3. Under Redirect URIs, add the redirect URI from Contracko.
  4. Copy the Client ID and Client Secret from the application's SSO tab. JumpCloud uses the same issuer for all tenants, so there is no issuer URL to enter.

Keycloak

  1. In the Keycloak Admin Console, select your realm, then go to Clients > Create client.
  2. Set the client type to OpenID Connect and enable Client authentication.
  3. Under Valid redirect URIs, add the redirect URI from Contracko.
  4. On the Credentials tab, copy the Client secret. The Client ID is the name you gave the client.
  5. In Contracko, enter your Keycloak host and Realm. Contracko builds the issuer URL for you.

Any other OIDC provider

  1. In your identity provider, create an OIDC (OpenID Connect) web application.
  2. Add the redirect URI from Contracko to the application's allowed redirect URLs.
  3. Copy the Client ID and Client secret.
  4. In Contracko, enter your provider's full Issuer URL and a Provider name. Contracko discovers the authorization, token, and key endpoints automatically from /.well-known/openid-configuration.

Step 3: Connect the provider in Contracko

  1. Go to Settings > Security > Single sign-on (OIDC) and click Add provider.
  2. Choose your identity provider from the list.
  3. Configure the connection: paste the Client ID and Client secret, then fill in the provider-specific field from Step 2 (tenant ID, hosted domain, Okta domain, and so on).
  4. Set the default role new SSO users receive when they first sign in (member, manager, or admin). The default is member.
  5. Click Save and test.

Step 4: Test the connection

Contracko verifies the connection with a real round-trip before you can enforce it.

  1. On the Test sign-in step, click Open test sign-in. Contracko opens your identity provider in a popup.
  2. Sign in with a test account on your tenant.
  3. Contracko detects the successful round-trip, marks the provider Verified, and signs the test account back out.
  4. Click Continue.

If the test fails, check that the redirect URI in your identity provider matches exactly, then click Retry.

Step 5: Turn on enforcement

Enforcement makes SSO the only sign-in method for users on your verified domains.

  1. On the Enforce SSO step (or the provider list), turn on Enforce SSO for this organisation.
  2. When you enable enforcement, Contracko signs out existing password and social sessions for users on your verified domains, so everyone signs back in through your identity provider.

A provider must be Verified before you can enforce it, and the billing owner must have 2FA enabled. You can turn enforcement off again at any time. To remove a provider, disable enforcement first.

Emergency access

If your identity provider is ever unavailable, the billing owner can still sign in with a password or social account, even while enforcement is on. This is why Contracko requires the billing owner to have 2FA enabled.

When the billing owner signs in this way, Contracko shows a short notice, records the event, and emails the billing owner with the IP address and device used. The billing owner can choose to continue with the bypass or switch to signing in through your identity provider.

How accounts and roles work

  • New users are created automatically the first time they sign in through SSO, and added to your workspace with the default role you set on the provider.
  • Existing users with the same email address are linked automatically, so someone who previously used a password keeps their account and history.
  • Role assignment uses the provider's default role. Mapping identity-provider groups to specific Contracko roles is not available yet.

Frequently asked questions

Which plan includes SSO? Self-serve SSO is included on the Big Business plan.

Do you support SAML? Self-serve setup is OIDC today. SAML 2.0 is available on request; contact us and we will help you set it up.

Who can set up SSO? Admins, owners, and the billing owner. The billing owner must have 2FA enabled first.

Can I require SSO for everyone? Yes. Verify your domain, connect and test a provider, then turn on enforcement. Users on your verified domains will then sign in through your identity provider.

What if our identity provider goes down? The billing owner can sign in with a password plus 2FA as an emergency bypass, and receives an email each time this happens.

ennlde