Single Sign-On

Single sign-on lets the people in your GitComet Pro organization sign in through your company's identity provider instead of a GitComet Pro password. You connect the provider yourself from the account app, prove that you own your company email domain, and can then require single sign-on for every member.

GitComet Pro supports any identity provider that speaks OpenID Connect (OIDC), including Microsoft Entra ID, Okta, Google Workspace, and Keycloak. SAML is not supported.

Before you start

You need:

• an Organisation licence with seats (see plans). The single sign-on page shows what it offers until the organization has seats, and every change needs them.
• to be an admin of the organization. Members do not see the single sign-on page.
• a second factor (an authenticator app or a security key) on your own account. Changes to single sign-on ask you to confirm it, and you cannot require single sign-on without one.
• access to your identity provider's admin console, to register an application.
• access to your domain's DNS, to add one TXT record.

Open the account app at pro.gitcomet.dev/app, go to Organisation, and choose the Single sign-on tab. The direct address is pro.gitcomet.dev/app/organisation/sso.

How it works

1. You register GitComet Pro as an application with your identity provider and enter its details on the Single sign-on page.
2. You add your company email domain, such as example.com, and prove you own it with a DNS TXT record.
3. When somebody signs in with an address at a verified domain, GitComet Pro sends them to your identity provider. Your provider authenticates them and tells GitComet Pro who they are.
4. Optionally, people at a verified domain join the organization automatically on their first sign-in, while seats last.
5. Optionally, you require single sign-on, so members at a verified domain can no longer sign in with a password.

A domain routes nobody until it is verified. A verified domain belongs to exactly one GitComet Pro organization.

Step 1: Register GitComet Pro with your identity provider

Create an application (often called an app registration, app integration, or client) in your identity provider with these settings:

Copy the redirect URL with the copy button next to it, so no whitespace or line break comes with it. Public clients (no client secret) and the implicit flow are not supported.

When you are done, note three values from your provider: the issuer URL, the client ID, and the client secret.

Claims and token configuration

This is where most single sign-on setups go wrong, so it is worth reading before you test.

Where GitComet Pro reads the claims

GitComet Pro reads the person's claims from your provider's userinfo endpoint, the one named userinfo_endpoint in the provider's discovery document at <issuer>/.well-known/openid-configuration. It does not read profile claims from the ID token.

So a claim that you add only to the ID token, for example through an "optional claims" or "token configuration" screen, is not seen by GitComet Pro. Make sure the claims below come back from userinfo when the openid, profile, and email scopes are granted.

The claims

A few consequences follow from this:

• The address must match exactly. At a verified domain, a person cannot type a different address than the one your provider sends. If they try, they see "the address must be the one your identity provider signed in with."
• No email, no account. If your provider sends no email for somebody, they cannot finish signing in at a verified domain. Check that every person who will use GitComet Pro has an email address in your directory.
• Keep sub stable. Many providers issue a different sub per application. If you delete the application and register a new one, existing people can get a new sub and no longer reach their accounts. To change credentials, create a new client secret on the same application instead.
• Names are imported once. GitComet Pro copies the names when the account is created. Later changes at your provider are not copied over, so people can edit their own names in GitComet Pro.

Issuer URL

The issuer must be an https:// URL that serves an OpenID Connect discovery document at /.well-known/openid-configuration, and its issuer value must match what you enter exactly. GitComet Pro refuses an issuer whose host resolves to a private network address, so the provider must be reachable from the internet.

Step 2: Save the connection in GitComet Pro

On the Single sign-on page, under Connection, enter:

• Display name: what people see on the sign-in page, for example "Example Microsoft".
• Issuer URL (https): from step 1.
• Client ID: from step 1.
• Client secret: from step 1.

Select Save connection and confirm your second factor. The connection shows Waiting for the first sign-in until somebody signs in through it.

The client secret is passed once to GitComet Pro's identity service and is never shown again. To change the display name, issuer, or client ID later, edit the fields and save; leave Client secret empty to keep the current secret. To rotate the secret, create a new one at your provider, paste it in, and save before the old one expires.

Step 3: Verify your email domain

Under Company email domains, enter your domain, for example example.com, and select Add domain. GitComet Pro shows a TXT record to publish:

Use the copy buttons to copy each value exactly. Add the record in your DNS provider, then select Verify. If the record is not visible yet, the page shows Verification failed and keeps the record on screen. DNS changes can take a while to propagate; wait and try again.

Some things to know:

• An organization can verify up to 20 domains. Add each domain your people's addresses use, for example example.com and example.co.uk.
• Your zone can hold other TXT records at the same name. GitComet Pro looks for an exact match of its value.
• Keep the record in place. GitComet Pro checks every verified domain again every 30 days. If the record is gone, the domain loses its verification, automatic joining and required single sign-on are switched off, and the organization's admins are emailed.

Step 4: Test the sign-in

Once a connection is saved, the page shows a Test sign-in link. It opens your organization's sign-in page in a new tab. Sign in with an account from your identity provider whose email address is at a verified domain.

The first successful sign-in marks the connection Verified. If it fails, see Common problems.

Step 5: Choose who can join and how members sign in

Under Access there are two switches.

Let people at a verified domain join automatically

Off by default. When it is on, a person who signs in through your provider for the first time with an address at a verified domain joins the organization as a member, as long as a seat is free. Automatic joining never buys a seat: when all seats are taken, the person signs in but holds no licence until you add seats or free one.

When it is off, invite people from the Invitations tab as usual.

Require single sign-on for members

When it is on, members with an address at a verified domain must sign in through your identity provider. GitComet Pro refuses their password, passkey, password registration, and password recovery, and hides those options on the sign-in page. Members' current sessions that did not come through your provider end when you switch it on.

You can switch it on only after:

• somebody has signed in through the connection (step 4),
• at least one domain is verified, and
• you have a second factor on your own account.

The page lists whichever of these is still missing.

Admins keep a fallback. Admins can still sign in with their password and second factor, so an outage at your identity provider cannot lock your organization out. For the same reason, while single sign-on is required, a member can be made an admin only if they have a second factor, and the last verified domain cannot be removed.

Provider guides

Microsoft Entra ID

1. In the Microsoft Entra admin center, go to Identity → Applications → App registrations → New registration.

2. Enter a name, for example "GitComet Pro".

3. Under Supported account types, choose Accounts in this organizational directory only (single tenant).

4. Under Redirect URI, choose the platform Web and paste the redirect URL from the single sign-on page. Select Register.

5. Go to Certificates & secrets → Client secrets → New client secret. Copy the secret's Value (not the Secret ID). Entra secrets expire, after at most 24 months; put a reminder in your calendar to rotate it.

6. From Overview, copy the Application (client) ID and the Directory (tenant) ID.

7. In GitComet Pro, use the issuer:

   https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0

   Do not use common or organizations in place of the tenant ID. Those endpoints publish an issuer template rather than your tenant's issuer, and the sign-in fails validation.

Claims in Entra ID. Entra's userinfo endpoint returns sub, name, given_name, family_name, and email. It returns email only for a user who has an email address. Microsoft documents that the userinfo response cannot be customized:

• Check the Email field of every user who will sign in: in Users, open the user, then Properties → Contact information → Email. Users with a mailbox usually have it already; accounts without a mailbox often do not.
• Optional claims under Token configuration do not help. They change the ID and access tokens, which GitComet Pro does not read for profile claims. You do not need to add any optional claims.
• Entra does not send email_verified. At a verified domain this does not matter. Someone whose Entra email is at a domain you have not verified receives a confirmation code instead.
• sub is specific to the app registration. Keep the same app registration for as long as you use single sign-on, and rotate its secret instead of replacing it.

The default delegated Microsoft Graph permission User.Read is enough; no admin consent for extra permissions is needed. To limit who can use GitComet Pro, open Enterprise applications, find the app, set Properties → Assignment required? to Yes, and assign users or groups under Users and groups.

Okta

1. In the Okta Admin Console, go to Applications → Applications → Create App Integration.
2. Choose OIDC - OpenID Connect and Web Application.
3. Under Grant type, keep Authorization Code.
4. Under Sign-in redirect URIs, paste the redirect URL from the single sign-on page. Remove the example sign-out URI if you do not need it.
5. Under Assignments, choose who may use the app, then save.
6. Copy the Client ID and a Client secret from the app's General tab.
7. Use your Okta organization's URL as the issuer, for example https://example.okta.com. If you use a custom authorization server, use its issuer instead, such as https://example.okta.com/oauth2/default.

Okta's userinfo endpoint returns email, email_verified, and the profile names when the email and profile scopes are granted. Make sure each user's Primary email is their address at your verified domain.

Google Workspace

1. In the Google Cloud console, choose or create a project owned by your Workspace organization.
2. Open Google Auth Platform (the OAuth consent screen). Under Audience, choose Internal, so only accounts in your Workspace can sign in.
3. Under Clients, select Create client, choose Web application, and add the redirect URL from the single sign-on page under Authorized redirect URIs.
4. Copy the Client ID and Client secret.
5. Use the issuer https://accounts.google.com.

Google's userinfo endpoint returns email, email_verified, and the profile names for Workspace accounts. No extra configuration is needed.

Keycloak

1. In the realm your people sign in to, go to Clients → Create client.
2. Choose OpenID Connect and enter a client ID, for example gitcomet-pro.
3. Turn Client authentication on, and keep only Standard flow enabled.
4. Under Valid redirect URIs, paste the redirect URL from the single sign-on page.
5. Optionally, under Advanced → Proof Key for Code Exchange Code Challenge Method, choose S256. GitComet Pro always sends a PKCE challenge.
6. Copy the secret from the client's Credentials tab.
7. Use the realm's issuer: https://<keycloak host>/realms/<realm>.

Keep the profile and email client scopes assigned as Default to the client. Every user needs an Email. Turn on Email verified for users whose addresses are not at a verified domain, or they receive a confirmation code.

Common problems

Somebody signing in with a company address is not sent to the identity provider. The domain is not verified yet, or the address is at a different domain. Check that the domain shows Verified under Company email domains.

Verify shows "Verification failed". GitComet Pro could not find the TXT record yet. Check the record name and value against the page, without extra quotes or whitespace, and try again after your DNS has propagated. You can check it yourself with dig TXT _gitcomet-verify.example.com or nslookup -type=TXT _gitcomet-verify.example.com.

"The address must be the one your identity provider signed in with." The person typed a different address than the email your provider sent, or your provider sent no email. In Entra ID, check the user's Email field. Elsewhere, check that the email scope is granted and that userinfo returns email.

People are asked to confirm their email with a code. Their address is not at a verified domain, and your provider did not send email_verified: true. Verify the domain, or have them complete the code once.

Require single sign-on cannot be switched on. The page lists what is missing: a successful test sign-in, a verified domain, or a second factor on your own account.

A person was removed at the identity provider but can still use GitComet Pro. Removing someone at your provider stops their next sign-in. A session that is already open runs until it expires. Remove them from the organization in GitComet Pro as well, which also frees their seat.

The sign-in fails after you recreated the application at the provider. The new application can give people a new sub, which no longer matches their accounts. Go back to the original application if you can. Otherwise, contact support.

If you are stuck, contact gitcomet@gitcomet.dev with the organization name and the reference shown in the error, if there is one.