Single sign-on with your identity provider
Let your team sign in to Guard.ch through your organisation's identity provider: Microsoft Entra ID, Okta or any OpenID Connect or SAML provider.
With single sign-on, your people use the work account they already have. Guard.ch never sees their password, your provider's policies apply, and when someone leaves, disabling them at the provider stops their next sign-in.
Setup has four parts, all on one page of your workspace settings: prove the email domains you own, connect your provider, run a test sign-in and, if you want, make single sign-on the only way in.
How it works
Once a domain is verified and the connection saved, a sign-in goes like this:
- Someone enters their work address, for example
ada@acme.com, on the Guard.ch sign-in page, or opens your workspace's sign-in link. - Guard.ch sends them to your identity provider, where they sign in unless they already are.
- Your provider confirms who they are, and they land in Guard.ch, signed in and in your workspace.
Guard.ch receives what it needs to sign the person in: an identifier for the person, their email address and their name. It asks for the standard OpenID Connect scopes openid, email and profile, nothing else. A SAML provider sends the same three: a persistent identifier and the attributes email and name.
Before you start
- Works with
- Microsoft Entra ID, Okta and any OpenID Connect or SAML provider
- On the Guard.ch side
- Business or Enterprise, and the workspace manager role
- On the provider side
- Permission to register an application
- DNS
- Permission to add a TXT record to your domain
- Time
- About fifteen minutes, plus DNS propagation
Open your workspace settings and choose Single sign-on. Keep this guide open alongside the page; its sections follow the page's cards.
Step 1: verify your domains
Add each email domain your people use, for example acme.com. For each one, the page shows a TXT record: add it at your DNS provider under the name _guard-verify.acme.com with the value shown, then choose Check now.
Guard.ch checks the record again every day. If it is missing three days in a row, the domain is no longer verified, and sign-ins on it are no longer routed to your provider until it is back.
Step 2: register Guard.ch at your provider
Register Guard.ch as a web application. It needs the redirect URI the settings page shows, which ends in your sign-in name, for example https://guard.ch/sso?workspace=acme.
Microsoft Entra ID
- In the Microsoft Entra admin center, open App registrations and choose New registration, for accounts in this organisational directory only.
- Add the redirect URI as a Web platform.
- Under Certificates & secrets, create a client secret and copy its Value. Note when it expires.
- Copy the Application (client) ID and the Directory (tenant) ID. The issuer is
https://login.microsoftonline.com/tenant-id/v2.0.
Okta
- In the Okta admin console, create an app integration of type OIDC and Web Application.
- Enter the redirect URI as the Sign-in redirect URI and assign the people or groups who may sign in.
- Copy the Client ID and Client secret. The issuer is your org address, for example
https://acme.okta.com.
Any other provider
Any provider that speaks OpenID Connect works: register a confidential web client with the redirect URI and use its issuer URL, the address under which /.well-known/openid-configuration answers.
Step 3: connect the provider
In the Identity provider card, enter the sign-in name, the issuer URL, the client ID and the client secret, then save. Guard.ch checks the issuer at once and refuses an address that does not answer as an OpenID Connect provider.
The secret is encrypted on our server and never shown again. To replace it, enter a new one; leave the field empty to keep the saved secret.
SAML instead of OpenID Connect
If your provider speaks SAML 2.0, choose SAML in the Identity provider card before you save the first connection. The card then shows the values your provider needs: the identifier (entity ID), the reply URL (ACS) and the sign-on URL of each site. Paste your provider's metadata URL, or the XML of its metadata file, and save.
- Microsoft Entra ID: in Enterprise applications, create your own non-gallery application, open Single sign-on and choose SAML. Enter the identifier, the reply URL and the sign-on URL, keep the default claims, assign the people and copy the App Federation Metadata Url.
- Okta: create a SAML 2.0 app with the reply URL as single sign-on URL and the identifier as audience URI, Name ID format Persistent, application username Custom with
user.getInternalProperty("id")(the Okta user ID: Guard.ch refuses a Name ID that is an email address, since an address can change or pass to someone else), and two attribute statements,emailandname. Assign the people and copy the metadata URL. - Any other provider (ADFS, SimpleSAMLphp): it needs a Name ID of format Persistent that is a stable user ID, not the email address, the attributes
emailandname, and assertions signed with SHA-256. Providers that import service provider metadata find ours at the identifier's URL.
Guard.ch starts every SAML sign-in itself and leaves assertion encryption off. A click on the app's tile in your provider's portal opens the Guard.ch sign-in page, where one more click signs in. Switching between OpenID Connect and SAML means deleting the connection and creating the other one.
Step 4: test the sign-in
Choose Test sign-in and sign in at your provider, as yourself or as a colleague. The test signs nobody in: it shows what your provider sent, the address, the name and whether the domain is verified.
A passed test is recorded. Requiring single sign-on needs one since the last change of the connection.
Accounts and members
Someone without a Guard.ch account who signs in through your provider with an address on a verified domain gets an account at once and joins your workspace, as long as it has a free seat.
Someone who already has a Guard.ch account under such an address is linked to your provider at the first sign-in. If their account uses two-step verification, they confirm it once; they get an email about the link and join the workspace.
When you remove a member in the workspace settings, or they leave, their account becomes a personal account outside the workspace and is no longer linked to your provider.
Provisioning with SCIM
With SCIM your identity provider manages who is in your workspace: it creates accounts for the people you assign, keeps their name and address up to date and removes them when you unassign them. Guard.ch provisions users only, not groups; you choose managers in the workspace settings.
Turn it on in the Provisioning card of the single sign-on settings. You get the SCIM endpoint and a token, shown only once; a new token replaces the old one at once.
Microsoft Entra ID
In the enterprise application, open Provisioning, choose the mode Automatic, enter the endpoint as Tenant URL and the token as Secret Token, then Test Connection. Under Mappings set "Provision Microsoft Entra ID Groups" to No, and keep the scope on assigned users only.
Okta
On the app's General tab choose Provisioning SCIM. On the Provisioning tab enter the endpoint as base URL, userName as unique identifier field, Push New Users and Push Profile Updates, and the authentication mode HTTP Header with the token. Under To App turn on Create Users, Update User Attributes and Deactivate Users.
SCIM never takes over an existing account: someone who already has a Guard.ch account is refused until they join by invitation or by signing in through your provider once; from then on your provider manages them. Removing a person in your provider removes them from the workspace and frees their seat; their account stays as a personal account, and browsers they started keep running until they close them.
Require single sign-on
Switch on Require single sign-on and every account on your verified domains signs in only through your provider. Their sessions from other sign-in methods end when you switch it on.
Workspace managers keep a way in for the day the provider fails or a client secret expires: they may still use their other sign-in methods, but only with two-step verification or a passkey that is enough on its own.
Roll it out
Nothing changes for your people until they sign in: entering their work address on the Guard.ch sign-in page sends them to your provider. You can also share your workspace's sign-in link.
On managed devices, IT can roll out the Guard.ch browser add-on with your workspace sign-in name, so every launch from the add-on signs in through your provider.
When a sign-in fails
“Your organisation's sign-in cannot be used for this email address.” The address the provider sent is not on a domain your workspace verified. Verify the domain, or check which address the provider sends for this person.
“Your identity provider sent no verified email address.” The provider sent no email address, or one it marks as unverified. In Entra ID, make sure the person has an email address; in Okta, that their primary email is verified.
“Single sign-on did not work.” The sign-in took too long, was opened in another browser or was refused by the provider. Start again from the sign-in page.
“Your organisation's identity provider cannot be reached.” Guard.ch could not reach your provider, or it refused our client. Check the issuer URL and whether the client secret has expired.
“The identity provider signs with a certificate this connection does not know.” Your SAML provider changed its signing certificate. Save its metadata again in the Identity provider card.
Keeping it running
When the client secret expires
Create a new secret at your provider, then enter it in the Identity provider card and save. Run the test again: a new secret clears the recorded test and switches the requirement off until you switch it on again.
When someone leaves
Disable the person at your provider: their next sign-in fails. Then remove them from your workspace's members to free their seat.
Changing the issuer
Saving another issuer removes the links between accounts and the old provider. People are linked again at their next sign-in, by their verified domain.
Turning single sign-on off
Delete the connection in the Identity provider card. Accounts stay; people sign in with their other methods again.
Security at a glance
- Passwords never reach Guard.ch. People enter them only at your provider, if at all.
- Every sign-in uses PKCE, a signed state, a nonce and checks the issuer and audience of the ID token.
- Accounts are created or linked only on domains you proved by DNS.
- Your provider's policies still apply to Guard.ch, including multi-factor authentication and conditional access.
- The client secret is stored encrypted and never shown again.
Ready?
Open your workspace settings and start with your first domain. For the rest of what Guard.ch connects to, see all integrations.