Setting up single sign-on

The wizard in your dashboard runs the same four steps in about ten minutes. This page is the long form: what each value is, what each setting changes, and what every error message means when the short version stops working.

Two constraints up front. Guard.ch single sign-on speaks to Microsoft Entra ID, the sign-in service behind Microsoft 365 (formerly Azure Active Directory). And it is a workspace feature: you need a plan with more than one seat and the workspace manager role.

The shorter path: Microsoft tenant auto-join

Before you register anything in Microsoft, know that there is a shorter path. If all you want is that colleagues signing in with their Microsoft work account land in your workspace, you do not need this guide: turn on Microsoft auto-join in your workspace settings and you are done.

It works because a Microsoft sign-in tells Guard.ch which tenant the account belongs to. You sign in with Microsoft once yourself, Guard.ch records your tenant, and one click claims it for the workspace. From then on every sign-in from that tenant joins as a member: while seats are free, never as a manager, and without touching the subscription. Nothing is configured on the Microsoft side, which is also what keeps it safe: only someone who has actually signed in from that tenant can claim it.

Full single sign-on adds what auto-join deliberately leaves out: one shareable sign-in link, sign-in restricted to your tenant, and a domain hint that skips Microsoft's account picker. The two run side by side, so starting with auto-join costs you nothing later.

What single sign-on does

Without SSO, every person creates their own Guard.ch account, invents another password, and waits to be added to the workspace. With SSO that collapses into one round trip:

1. A colleague opens your workspace's sign-in link, something like guard.ch/sso?workspace=acme.
2. Guard.ch forwards them to Microsoft, where they sign in with their normal work account. If they are already signed in there, which at work they usually are, this step passes without a single keystroke.
3. Microsoft confirms to Guard.ch who they are, and they land in your workspace, signed in.

The password never passes through Guard.ch: it is typed, if at all, on Microsoft's own sign-in page. Guard.ch receives three things back: the person's name, their email address, and Microsoft's confirmation that they belong to your tenant.

Before you start

Works with

Microsoft Entra ID, the sign-in service of Microsoft 365

On the Guard.ch side

A plan with more than one user, and the workspace manager role

On the Microsoft side

Permission to register applications, typically an IT administrator

Time

About ten minutes, plus a test run

Cost

None. Registering an app is included in every Microsoft plan.

Everything on the Guard.ch side happens in one place: your workspace settings, under Advanced options, in the Single sign-on section. Keep this guide open beside it; the chapters below match the wizard's four steps.

Step 1: name your sign-in link

The sign-in link is the address your team will open, and the name you pick becomes its last part: guard.ch/sso?workspace=acme. The rules are short: 3 to 50 characters, lowercase letters, numbers and hyphens, and it cannot begin or end with a hyphen. Names are unique across all of Guard.ch, so if another workspace got there first you will be asked for a different one, and a handful of technical names are reserved.

Your company name is usually the right choice. Enter it and save; the wizard reserves the name and shows the finished link with a copy button.

Step 2: register Guard.ch in Microsoft Entra

This step happens in the Microsoft Entra admin center. The bureaucratic name is app registration; the meaning is that you add an entry to your directory saying this application may ask us to sign people in. The wizard has a button that opens the right page; here is the same walk in more detail.

1. In App registrations (the admin center lists it under Entra ID), choose New registration and give the app a name your team will recognise, for example Guard.ch sign-in. The name is purely cosmetic; it appears in your own admin lists and in consent prompts, nowhere else.
2. Under Supported account types, pick Single tenant only, the single-company option: only accounts in your own organisation can use this sign-in. Older portals call the same option Accounts in this organizational directory only.
3. Select Register. Microsoft creates the app and drops you on its Overview page; you will come back here for step 3.
4. Open the app's Authentication page, choose Add redirect URI, pick the platform Web, and paste your sign-in link exactly as the wizard shows it, for example https://guard.ch/sso?workspace=acme. Confirm with Configure. (Older portals offer the same Redirect URI field directly on the registration form.)
5. Open API permissions once, only to confirm there is nothing to do: the defaults already cover the only things Guard.ch reads, a person's name and email address. You add no permission and grant no admin consent, and Guard.ch cannot see mail, files, calendars or anything else.

Step 3: enter the three values in Guard.ch

Guard.ch now needs to know which directory and which app it is talking to, plus a way to prove itself: three values. The first two sit together on the app's Overview page in Microsoft, the Directory (tenant) ID and the Application (client) ID. Copy each into its matching field in the wizard.

The client secret

The third value is the client secret: a machine password Microsoft issues so Guard.ch can prove it is the app you registered. It is also where setups go wrong, so take it slowly. In your app, open Certificates & secrets, choose New client secret, give it a description and an expiry, and confirm. Then three things matter:

• Copy the Value column, not the Secret ID. The value is the actual secret; the ID next to it is merely its label. Pasting the ID is the most common mistake in this step, and the connection test will report it as an invalid secret.
• Copy it immediately. Microsoft shows the value exactly once. Leave the page and it is hidden forever. If that happens, no harm done: create a new secret and copy that one.
• It expires. You choose the lifetime when you create it, up to 24 months, and the longest option means the fewest renewals. Put a reminder in your calendar for the week before it runs out; the renewal itself takes two minutes and is described under day-two care below.

Paste the secret into the wizard and save. Guard.ch encrypts it before storing it and never displays it again, not even to you: when you edit the configuration later, an empty secret field means keep the one you have.

Optional settings

Email domain

Optional, and purely a convenience. If the team shares one email domain, enter it (say acme.com) and two things get smoother: Microsoft skips its account picker and goes straight to your tenant's sign-in, and the normal Guard.ch sign-in form offers SSO on its own when someone types an address at that domain. Spanning several domains? Leave it empty; sign-in works the same, with one extra click at the account picker.

Create accounts automatically

This toggle decides what happens when someone from your tenant opens the link for the first time. Switched on, the default, Guard.ch creates the account on the spot and adds it to the workspace, taking a seat. The team onboards itself: send the link, done.

Switched off, the link only signs in people who already have a Guard.ch account in the workspace; everyone else is turned away with an account-not-found message. Choose this when you want to decide personally who gets a seat, or when seats are scarce and you would rather not have them claimed first-come.

Step 4, optional: limit who can sign in

Out of the box, anyone with an account in your directory can use the link (each newcomer still needs a free seat). To limit Guard.ch to a security team or a named few, restrict it on the Microsoft side, in the same admin center:

1. Go to Entra ID › Enterprise apps (older admin centers list it under Identity › Applications › Enterprise applications) and open the app you registered; it carries the same name.
2. On the Properties tab, switch Assignment required? to Yes and save.
3. On Users and groups, choose Add user/group and assign the people, or the group, who should have access.

Testing the setup

Back in the wizard, the finished configuration carries a Test connection button. It runs a live rehearsal against Microsoft without signing anyone in: does the directory exist, is the app known there, does the secret open the door. When it fails, it names the culprit:

• Invalid Tenant ID. Microsoft has no directory under that ID. Re-copy the Directory (tenant) ID from the app's Overview page; it is easy to grab a neighbouring value by accident.
• Invalid Client ID. The directory exists, but no app with that ID lives in it. Re-copy the Application (client) ID, and make sure the app was registered in the same directory your tenant ID points to.
• Invalid Client Secret. Nine times out of ten this is the Secret ID pasted where the Value belongs. Create a fresh secret under Certificates & secrets and copy the Value column this time.
• Client Secret has expired. The secret's lifetime ran out. Create a new one and paste it into the wizard; everything else stays as it is.
• Could not connect to Azure AD. Guard.ch could not reach Microsoft at all. Usually a hiccup that passes on retry; if it persists, double-check the tenant ID, because a malformed one produces the same symptom.

When the test passes, run the real thing once: open your sign-in link in a private window and sign in with your own work account. The private window matters, because an everyday browser is probably signed in everywhere already and would skip the interesting parts. Landing in the dashboard means the setup is done.

Deploying to the team

Rollout is one link. Put it on the intranet, pin it in the team chat, push it as a managed bookmark. Whoever opens it goes straight to Microsoft, signs in or already is, and lands in the workspace. Nothing to install, no invitation to wait for.

If the team runs the Guard.ch browser extension on managed devices, IT can push your workspace's slug alongside it. The extension then routes launches through SSO by itself, silently where possible: a colleague with a live Microsoft session in the browser never sees a form. When Microsoft does need a human moment, multi-factor for instance, the silent attempt steps aside and the interactive sign-in takes over.

Every member occupies one seat of the plan, however they arrived. Who holds a seat is visible, and manageable, in the members list of your workspace settings.

Troubleshooting

Sign-in problems speak with one of two voices. Messages on the Guard.ch sign-in page come from us. Error pages on microsoftonline.com come from Microsoft and always carry a code starting with AADSTS. Both are listed here, each with its fix.

Messages from Guard.ch

“SSO is not available.” The address does not lead to an active SSO setup. Three causes cover almost every case: a typo in the link (or an old bookmark from before a rename), the SSO configuration was removed, or the workspace no longer sits on a multi-user plan.

“SSO for this workspace is not fully configured yet.” The setup was started, the link name exists, but the Microsoft credentials were never saved. Whoever manages the workspace needs to finish step 3.

“Your account was not found.” Automatic account creation is switched off and this person has no Guard.ch account in the workspace yet. Either add them first, or switch Create accounts automatically on.

“Workspace is at maximum capacity.” The sign-in itself succeeded, but every seat is taken, so there was no room to add the newcomer. Free a seat by removing a member, or upgrade the plan, and have the person simply sign in again.

“This user already belongs to another workspace.” A Guard.ch account can only be a member of one workspace at a time, and an account with this email already belongs to a different one. The person leaves that workspace first (or its manager removes them); after that the sign-in goes through.

“Your account has been disabled.” The account was blocked on the Guard.ch side. This is not an SSO problem; contact support.

“Microsoft authentication failed.” The handshake between Guard.ch and Microsoft broke mid-flight, most often a stale or half-finished attempt in an old tab. Close the tab, open the sign-in link fresh, and it usually passes. A browser set to block all site data can also cause this, because the sign-in keeps a one-time security token in the tab for the trip to Microsoft and back.

Error codes from Microsoft

AADSTS50011 Redirect URI mismatch. The address registered in step 2 does not exactly match your sign-in link. Open the app's Authentication page in the admin center and make the redirect URI character-for-character identical, including https and the workspace name. This is also the error you will meet after renaming your link without updating Microsoft.

AADSTS700016 Application not found. The directory has no app under your Application (client) ID. Either the ID was copied wrongly, or the app was registered in a different directory than your Directory (tenant) ID points to. Compare both values against the app's Overview page.

AADSTS7000215 Invalid client secret. The same culprit as the failed connection test: the stored secret is wrong or expired, typically because the Secret ID was pasted instead of the Value. Create a new secret and save its value in step 3 of the wizard.

AADSTS50105 User not assigned. Assignment required is switched to Yes and this person is not on the list. Add them, or their group, under Users and groups in the enterprise application.

AADSTS90094 Need admin approval. Sometimes worded Approval required. Your organisation requires administrator consent even for basic sign-in permissions. An administrator opens the app under Enterprise applications and grants consent for the organisation once; after that the prompt disappears for everyone.

Maintenance

A finished setup mostly runs itself. Four situations will eventually knock:

The secret expires

One day the connection test, and every sign-in with it, starts reporting an expired secret. The renewal is undramatic: create a new client secret on the app's Certificates & secrets page, open the SSO section in the dashboard, edit, continue to the credentials step, paste the new value and save. Leave every other field alone. No existing session is interrupted; the secret is only used at the moment of signing in.

Someone leaves the company

Offboarding happens in two places. Disabling the account in Microsoft, which IT does anyway, shuts the SSO door: Microsoft stops vouching for the person, so they cannot sign in again. Their seat, though, stays occupied until you remove them from the members list. Do both and the seat is free for a successor.

The link needs to change

Company renamed? Edit the SSO configuration, change the name in step 1, and update the redirect URI in the Microsoft app to match immediately; until you do, every sign-in fails with the redirect mismatch error. Then tell the team, and expect a few weeks of stale bookmarks.

Turning SSO off

Remove deletes the configuration and the link stops working at once. Nothing else is touched: accounts, membership and past investigations all stay. The team signs in another way from then on, and you can set SSO up again whenever you like.

Security

• Passwords never touch Guard.ch. They are entered on Microsoft's own page, if they are entered at all.
• Guard.ch receives a person's name and email address, and nothing else. No mail, no files, no calendar.
• The client secret is encrypted before storage and can be written but never read back out, not even by you.
• Every sign-in round trip carries a signed one-time token, so a forged or replayed attempt is rejected.
• Your Microsoft policies keep applying: multi-factor, device rules and conditional access gate Guard.ch exactly as they gate any other company app.

Next steps

That is the whole system: one registration at Microsoft, three values in the dashboard, and a link the team can keep. Open your workspace settings to set it up; to give the same people a one-right-click way into investigations, the browser extensions are the natural companion.