Single sign-on (SSO)

Sign your people in through your identity provider, and let it create, update and remove their RepoHelpdesk accounts for you.

• Before you start
• Verify your domain
• Okta
• Microsoft Entra ID
• Google Workspace
• OneLogin
• Other providers
• Require SSO
• Groups and roles
• Who gets in, and for how long
• When your IdP certificate changes
• Troubleshooting

Before you start

An organization stands for your company. It owns your email domains and your SSO connections, and your projects belong to it. If the project doesn't have one yet, the Organization & SSO page asks you to name it — that's the only step. Projects that don't use SSO don't need an organization.

You'll need:

• Admin access to your identity provider (IdP).
• Access to your domain's DNS, to add one TXT record.
• An admin of the project with two-step sign-in turned on (Profile → Two-step sign-in), to be your break-glass admin. See Require SSO.

Verify your domain

1. Add the domain

   On the Domains tab, add the domain your people's addresses are on, like acme.com. Add each one if you have several.

2. Add the TXT record at your DNS provider

   Copy the name and value shown. DNS changes can take a few minutes to show up, sometimes longer.

3. Check the record

   Once it's verified you can delete the record. A domain can belong to only one organization.

Only addresses on your verified domains can sign in through your SSO or be created by your IdP — so your IdP can never sign anyone in as someone outside your company.

Okta

Sign-in (SAML).

1. Start the connection in RepoHelpdesk

   On SSO connections, choose Add SAML connection. Keep the page open — it shows the values Okta needs.

2. Create the app in Okta

   In the Okta Admin Console, go to Applications → Create App Integration → SAML 2.0. Set Single sign-on URL to our ACS URL and Audience URI to our Entity ID. Use Name ID format: EmailAddress and Application username: Email.

3. Give us Okta's metadata

   On the app's Sign On tab, copy the Metadata URL and paste it into the connection. A URL is best: when Okta's certificate changes, we pick up the new one ourselves.

4. Assign people, then turn it on

   Assign the app to your people or groups in Okta. In RepoHelpdesk, choose Turn on, then pick the connection under Sign in through on the Domains tab.

Provisioning (SCIM).

1. Make a token

   On Provisioning, choose New token and copy it — it's shown once. Copy the SCIM base URL too.

2. Turn on SCIM in Okta

   On the app's General tab, set Provisioning to SCIM. Then on Provisioning → Integration: SCIM connector base URL = our SCIM base URL, unique identifier = userName, authentication = HTTP Header with the token. Allow Push New Users, Push Profile Updates and Push Groups.

3. Choose what Okta does

   Under Provisioning → To App, turn on Create Users, Update User Attributes and Deactivate Users. Then push the groups you want to use on the Push Groups tab.

Microsoft Entra ID

Sign-in (SAML).

1. Create the app

   In the Microsoft Entra admin center, go to Enterprise applications → New application → Create your own application and pick Integrate any other application you don't find in the gallery.

2. Set up single sign-on

   Choose Single sign-on → SAML. Under Basic SAML Configuration, set Identifier (Entity ID) to our Entity ID and Reply URL to our ACS URL.

3. Give us Entra's metadata

   Copy the App Federation Metadata Url into an Add SAML connection in RepoHelpdesk. Assign users and groups to the app, then turn the connection on and pick it on the Domains tab.

Prefer OpenID Connect? Register an app under App registrations, add our Redirect URI as a Web redirect, create a client secret, and use Add OIDC connection with the issuer https://login.microsoftonline.com/<tenant-id>/v2.0.

Provisioning (SCIM).

1. Turn on automatic provisioning

   In the same enterprise application, go to Provisioning and set the mode to Automatic. Tenant URL = our SCIM base URL, Secret Token = a new token from our Provisioning tab. Choose Test Connection.

2. Check the mapping, then start

   The default mappings work: userPrincipalName goes to userName. If your sign-in names aren't email addresses on your verified domain, map mail instead. Then Start provisioning. Entra runs about every 40 minutes.

Google Workspace

Sign-in (SAML).

1. Add a custom SAML app

   In the Google Admin console, go to Apps → Web and mobile apps → Add app → Add custom SAML app. Download the IdP metadata file on the second screen.

2. Fill in our values

   Set ACS URL and Entity ID from our connection. Name ID format: EMAIL, Name ID: Basic Information → Primary email.

3. Upload the metadata, and turn the app on

   In RepoHelpdesk, use Add SAML connection with the metadata file. In Google, set the app's User access to ON for everyone (or the groups you want).

With an uploaded file, you'll need to upload Google's new metadata when its certificate changes (every five years). We email you a month before.

Provisioning. Google doesn't send SCIM to apps outside its own catalog, so we read your directory instead:

1. Connect Google Workspace

   On Provisioning, choose Connect Google Workspace and sign in as a super admin. We only ask to read users and groups.

2. That's it

   We re-read your directory every 15 minutes, and Google tells us right away when someone is suspended. Suspended or deleted people are deactivated here too. See what each sync did under Recent syncs.

OneLogin

1. Add the connector

   Go to Applications → Add App and pick SCIM Provisioner with SAML (SCIM v2 Enterprise) — or SAML Custom Connector (Advanced) if you only want sign-in.

2. Fill in our values

   On Configuration: Audience (EntityID) = our Entity ID; Recipient, ACS (Consumer) URL and ACS URL Validator = our ACS URL. For provisioning, SCIM Base URL = our SCIM base URL and SCIM Bearer Token = a new token from our Provisioning tab.

3. Give us OneLogin's metadata

   On the SSO tab, copy the Issuer URL (it's the metadata URL) into an Add SAML connection, then turn it on and pick it on the Domains tab.

4. Turn on provisioning

   On the Provisioning tab, enable provisioning, and allow it to create, update and deactivate users.

Other providers

JumpCloud, Ping Identity, Auth0, Keycloak, Duo, Rippling and others work the same way: any SAML 2.0 or OpenID Connect provider for sign-in, and any SCIM 2.0 client for provisioning. Our Entity ID and ACS URL go in these fields of each console:

The person's address comes from an email attribute (email, mail or the standard email claim) or from a Name ID that's an address. For OpenID Connect we ask for openid email profile. On a SAML connection you can also sign our sign-in requests and require encrypted assertions — set those up at your IdP first.

Require SSO

Once a connection works, turn on Require SSO for the domain. From then on everyone on it signs in only through your IdP: no passwords, no Google or Microsoft sign-in, and their API tokens need an SSO session. Turning it on signs everyone on the domain out, except you.

Turn on Manage accounts on this domain to see every account on it on the People tab — including people who signed up before SSO — and to deactivate them. Deactivating someone signs them out everywhere and ends their API tokens and linked apps at once. People on other domains, like contractors, keep signing in the way they do now.

Groups and roles

Under Groups and roles on the Provisioning tab, map a group from your IdP to a project and a role. People in the group join the project with that role, and leave it when they leave the group or are deactivated.

• Someone in several mapped groups gets the highest role.
• Someone you added by hand stays as they are, until a mapping covers them.
• A project's last admin is never removed.
• Seats follow: adding someone adds a seat, removing them frees it.

Who gets in, and for how long

• Just-in-time access (Access tab): people on your domains who sign in through SSO for the first time join a project you choose, up to a seat limit. Off means only people you invite or provision get in.
• Session and token limits: how long an SSO sign-in lasts before people sign in again, and the longest an API token can live for someone on a domain that requires SSO.
• Every change to these settings is in the Audit log tab, with who made it.

When your IdP certificate changes

SAML providers sign sign-ins with a certificate that expires. We email your project admins 30, 14 and 3 days before it does.

• With a metadata URL: make the new certificate at your IdP and keep both active for a while. We read the metadata again and trust the new one ourselves.
• With an uploaded file: make the new certificate, then edit the connection and upload the new metadata. The old certificate keeps working for 14 days, so there's no gap.

Troubleshooting

• "Not on one of your organization's verified domains" — the person's address is on a domain you haven't verified, or your IdP sends a sign-in name that isn't their email. Verify the domain, or map the email attribute.
• Someone didn't come through from your IdP — the Sync log on the Provisioning tab shows every call your IdP made in the last 30 days, and why any failed.
• "Out of seats" after signing in — just-in-time access reached its seat limit. Raise it on the Access tab, or invite the person.
• A connection won't turn on — we couldn't read your IdP's metadata (SAML) or its OpenID configuration (OIDC). Check the URL is reachable from the internet.