Single sign-on (SSO)

Single sign-on lets the people in your organization reach Coldsea through your own identity provider instead of a separate Coldsea password. When someone signs in, they authenticate with your provider (Microsoft Entra ID, Okta, Google Workspace, or any other OpenID Connect provider), and your provider decides who is allowed in.

SSO is an Enterprise capability. It is configured for one organization at a time, by an administrator of that organization.

What changes for your team

Turning on SSO changes how your members sign in and how you control their access.

• Domain users sign in with SSO. Once a domain such as acme.com is verified, everyone with an email address in that domain signs in through your identity provider. Password sign-in is turned off for those addresses, so your provider becomes the single place that grants access.
• MFA is handled by your provider. People who sign in through SSO are not asked for a separate Coldsea authentication code. Your provider has already performed sign-in and any multi-factor step you require, and Coldsea trusts that result.
• Offboarding happens in your provider. When you disable or remove someone in your identity provider, they can no longer start a new Coldsea session, and a session they already have ends within 12 hours. To end it right away, see Removing access.
• Guests outside your domain keep using passwords. You can still invite people whose email is not in a verified domain, such as an outside contractor, as regular password users. An administrator can stop new guest invitations with Limit to verified domains; guests already in the organization keep their access.

The first time someone signs in through SSO, Coldsea creates their account and adds them to your organization automatically. If they already had a Coldsea account on the same verified email, that account is reused.

Setting it up

Register Coldsea in your identity provider

In your identity provider, create a new OpenID Connect (OIDC) web application for Coldsea. You will need to supply a redirect URI, request a few scopes, and then collect three values to hand back to Coldsea.

1. 1

   Add the redirect URI

   Set the redirect URI (some providers call it the callback URL) to your Coldsea API host followed by /api/v1/auth/sso/callback, for example https://api.your-company.com/api/v1/auth/sso/callback. The path must match exactly, with no trailing slash.

2. 2

   Request the standard scopes

   Request openid, email, and profile. Coldsea uses these to identify the person signing in and match them to your organization.

3. 3

   Collect the connection details

   Your provider gives you an issuer URL (the authority that Coldsea reads settings from), a client ID, and a client secret. Enter these under Settings → Single Sign-On in the Identity provider section, along with the scopes and an optional display name for the login button. The secret is stored encrypted and is never shown again after it is saved; to replace it later, use Rotate.

The issuer URL differs by provider. For Microsoft Entra ID it is https://login.microsoftonline.com/<tenant-id>/v2.0, for Okta it is your Okta domain such as https://your-org.okta.com, and for Google Workspace it is https://accounts.google.com.

Verify your domain

SSO sign-in only works for email domains you have proven you own. This stops anyone else from routing your users' logins through their own provider. You prove ownership by publishing a DNS record for each domain.

In your DNS provider, add a TXT record:

The Email domains section shows you the exact record to publish for each domain you add: the full name is _coldsea-verification.<your-domain> and the value is coldsea-domain-verification=<token>, including the coldsea-domain-verification= prefix. Once the record is live and a connection test has passed (see below), use the Verify button next to the domain. DNS changes can take a few minutes to a few hours to appear, so if verification does not find the record yet, allow time and try again.

Public email domains such as gmail.com and outlook.com cannot be used for SSO.

Test the connection, then verify

Once the identity provider details are saved, use Test connection to confirm Coldsea can reach your provider. Re-enter the client secret to run the test (it is never displayed). A successful test means the issuer and its signing keys are reachable, and it unlocks Verify for the rest of your browser session.

Verifying a domain is the step that turns SSO on for it. From that moment, everyone with an email in the domain, administrators included, signs in only through your identity provider; password sign-in stops working for them. Coldsea asks you to confirm before it verifies.

Guest invitations

People whose email is outside your verified domains are guests: they sign in with a password. Guest invitations controls whether you can invite more of them. Turn on Limit to verified domains to allow invitations only to your verified domains. This does not remove or sign out anyone already in the organization, and it becomes available once a domain is verified.

Removing access

When access is removed in Coldsea, every session that person has ends right away, on every device and in every organization they belong to. They can sign in again wherever they still have access.

• Turning SSO off or deleting the configuration signs out everyone who signs in through your identity provider immediately.
• Removing someone from your organization signs them out immediately.
• Removing someone only in your identity provider stops them from starting a new session, but a session they already have open can keep working for up to 12 hours. After that they must sign in through your provider again, and it refuses them. To cut access at once, also remove them from your organization in Coldsea.

SSO sessions always last at most 12 hours. After that, everyone who uses SSO signs in through your provider again, even if they have been active the whole time.

Troubleshooting

• The DNS record is not found. Confirm the record name is _coldsea-verification.<your-domain> and the value is exactly coldsea-domain-verification=<token>, including the prefix. Give DNS time to propagate, then ask for another check. You can look it up yourself with dig TXT _coldsea-verification.your-domain.com.
• The provider reports a redirect-URI mismatch. The redirect URI registered in your identity provider must match https://api.your-company.com/api/v1/auth/sso/callback exactly, with no trailing slash.
• Sign-in says SSO is not available for that email. The domain is not verified yet, or the email is not in a configured domain. Finish domain verification first.
• A user cannot sign in through SSO. Confirm they exist in your identity provider and are assigned to the Coldsea application there. Coldsea trusts your provider to decide who may sign in for your domain.
• Sign-in shows "Your sign-in session expired. Please try again." The sign-in has to finish in the same browser where it started, within 10 minutes. This message appears when the user took too long at the identity provider, finished in a different browser, or started SSO in a second tab before the first one finished. Start again from the Coldsea sign-in page in one tab. The same-browser rule is deliberate: it stops anyone from sending a user a sign-in link that would sign them in to someone else's account.

Current limits

• One identity provider per organization.
• SAML is not supported yet. Use an OIDC connection (Entra ID, Okta, and Google all support OIDC).
• Single sign-on for the desktop agent is not available yet. Until it is, members whose email is in a verified SSO domain cannot sign in to the desktop agent, because password sign-in is turned off for them everywhere. Technicians who need the agent in the meantime can use an account whose email is outside your SSO domains.

Related

• Managing your team for inviting and removing members.
• Roles and permissions for what each member can do once they are in.