Set up Microsoft Entra ID single sign-on

Before you start

• Enterprise SSO is enabled for your workspace. If it is not, Settings → Security shows the banner “Enterprise SSO is available on Enterprise plans and is not included in your current plan.” In that case contact us first.
• You are a ZipLogger Admin and you can sign in at your workspace address, https://<workspace>.ziplogger.ai. Do every ZipLogger step from that address, not from app.ziplogger.ai: the test sign-in has to start where the redirect URI points.
• You can register applications in Microsoft Entra, for example as an Application Administrator or Cloud Application Administrator.
• Your ZipLogger account uses your work email address, the same address your Entra account reports. The first sign-in links your Entra account to your existing ZipLogger account by that address.
• Have a place to keep recovery codes that does not depend on signing in through Entra.

1. Copy the redirect URI from ZipLogger

Sign in to ZipLogger at https://<workspace>.ziplogger.ai as an Admin and open Settings → Security. The page is a series of cards. The top one, Single sign-on, shows your progress: Configured, Tested, Sign-in button and Required for everyone.

In 1 · Choose your provider, set Provider to Microsoft Entra ID. The card below it, 2 · Register this application with your provider, shows the redirect URI for your workspace with a Copy button. It has this form:

https://<workspace>.ziplogger.ai/sso/callback

Copy the value ZipLogger shows rather than typing it. Every character has to match, including the host and the path. Keep this tab open: you will come back to it.

2. Register the application in Microsoft Entra

In the Microsoft Entra admin center, go to Entra ID → App registrations and choose New registration. Give it a name your people will recognise, for example ZipLogger; Microsoft shows the name on its sign-in and consent screens.

3. Choose the supported account type

Under Supported account types, choose Accounts in this organizational directory only, the option that limits the registration to your own directory. This is the recommended choice, and the one ZipLogger is built around:

• ZipLogger connects your workspace to one specific directory, identified by its Directory (tenant) ID, and checks on every sign-in that the account comes from that directory. Accounts from other directories are refused.
• A multitenant or personal-account registration adds nothing for this connection and widens what the registration can be used for. Do not choose one.
• ZipLogger refuses common, organizations, consumers or a domain name in place of the directory ID.

4. Add the redirect URI under the Web platform

Still on the registration page, under Redirect URI, choose the platform Web and paste the redirect URI you copied in step 1. Then choose Register.

If you already registered the application, open it, go to Authentication, and add the URI there under the Web platform.

Leave Front-channel logout URL empty, and leave the Implicit grant and hybrid flows options unticked: ZipLogger uses the authorization-code flow, and it does not sign people out of Microsoft.

5. Copy the Directory (tenant) ID and the Application (client) ID

On the application’s Overview page, copy these two values. Both are GUIDs:

Do not use the Object ID; ZipLogger does not use it.

6. Create a client secret and copy its Value

Open Certificates & secrets and choose New client secret. Enter a description such as ZipLogger SSO, choose an expiry date, and add the secret.

• Entra secrets expire. Choose an expiry that matches how often your team is willing to rotate, and put the expiry date in your calendar or ticketing system now. ZipLogger warns you on the Security page from 30 days before a recorded expiry date, but it does not send a reminder. A secret that expires without being replaced stops every Microsoft sign-in to your workspace. See Rotate the client secret.
• Treat the Value like a password. Do not paste it into chat, tickets or screenshots.

7. Optional: the email claim, and who may use the application

Both of these are optional and can be done later.

Make sure Entra sends each person’s email address

ZipLogger identifies a first sign-in by the person’s email address. It asks Entra for the email scope, so Entra sends the address when the account has one: set Email on each person’s Entra account. If no email is sent, ZipLogger falls back to the preferred_username claim (the sign-in name), but only when it contains an @, and a name ending in .onmicrosoft.com will not match your own domains.

If the address is still missing for some people, add the claim explicitly: go to Token configuration → Add optional claim, choose the ID token type, and tick email.

Limit who can sign in to ZipLogger

In Enterprise applications, open the ZipLogger application, go to Properties and set Assignment required? to Yes, then add the people or groups who may use it under Users and groups. Without this, any account in your directory can start a sign-in, and ZipLogger applies your allowed email domains only to a person’s first sign-in.

If your tenant does not let users consent to applications, an administrator can grant consent once under API permissions → Grant admin consent.

8. Enter the values in ZipLogger

Back in Settings → Security on your workspace address, scroll to 3 · Provider settings. The provider you chose in step 1 is already set. Under Connection, fill in:

Choose Save. On a first setup, saving stores the configuration; it does not switch anything on and does not change how anyone signs in. The secret is stored encrypted and is never shown again. Once a configuration is saved, the button reads Save changes, and you leave Client secret (Value) empty to keep the stored secret.

The directory, the application (client) ID, the secret and the allowed domains decide who can sign in. Saving a change to any of them has three effects: the earlier test no longer counts, so you test again; the sign-in button is switched off until you test and turn it back on (if it was on, ZipLogger first asks “Save and switch the sign-in button off?”); and a pending secret, if you have one, is discarded. While the button is off, people sign in with a password. People whose account was created automatically on first sign-in have no password yet: they choose one with Forgot password on the sign-in page first.

While single sign-on is required, the Connection settings are locked: use Rotate the client secret to change the secret without turning anything off, and Stop requiring single sign-on first to change anything else.

9. Allowed email domains, just-in-time accounts and the default role

Allowed email domains

In Connection. Required. List the domains your people’s email addresses use, separated by commas, for example example.com, example.co.uk, without the @.

• The list decides whose first sign-in may be linked to an existing account or create a new one.
• Matching is exact. example.com does not include eng.example.com; list every domain you use.
• Someone who is already linked is not checked against the list again. To remove a person, follow offboarding.

Just-in-time accounts

Under Sign-in behaviour, Create accounts automatically on first sign-in is off by default. Leave it off if you prefer to add people yourself under Team: they sign in through Entra afterwards and are linked by email. When it is on, a person from your directory with an email in an allowed domain gets an account the first time they sign in, subject to your plan’s seat limit; when no seat is free, the sign-in is refused.

Role for new accounts

Also under Sign-in behaviour, and available once automatic account creation is on, choose Viewer (read-only) or Editor for Role for new accounts. ZipLogger never grants Admin automatically: an existing Admin promotes people under Team. Accounts created this way have no password of their own.

Sign-in button label

The Sign-in button label field does not change the Microsoft button: with Microsoft Entra ID the sign-in page always shows Sign in with Microsoft. The label is used only in places that name your organization.

10. Test the configuration

Scroll to 4 · Test, turn on, require. Its first block is Test the configuration: choose Test the configuration, from your workspace address. You are sent to Microsoft; sign in with your own work account. (If you are on another address, the button is disabled and the page links you to your workspace address.)

• The test signs you in through Entra with the saved settings. Nobody else is affected and no ZipLogger session is created. If the form above has changes you have not saved, the page reminds you that the test does not use them.
• ZipLogger asks Microsoft to ask you to sign in even if you already have a Microsoft session. That is intended.
• It links your Entra account to your ZipLogger account, which requiring single sign-on later needs. Your Entra email address has to match your ZipLogger account’s email.
• A successful test shows Last successful test with the time, the Tested step at the top of the page reads “done”, and the button now reads Test again. Only then can you turn the sign-in button on. If anything fails, the page explains the likely cause; see also troubleshooting.

11. Check Linked identities

Scroll to the bottom card, Linked identities. Its table lists, for each person, when they were Linked and their Last sign-in. After the test you should see yourself, with your email address. This is also where an Admin chooses Unlink for a person. While single sign-on is required you cannot unlink your own sign-in.

12. Turn the sign-in button on

In 4 · Test, turn on, require, the second block is Sign-in button. Choose Turn the sign-in button on. The sign-in page at your workspace address now offers the Microsoft button (Sign in with Microsoft) beside the password form. Everyone can still sign in with a password: nothing is required yet.

13. Test from a fresh private window

Before you require anything, prove that sign-in works for someone other than you.

1. Open a private (incognito) window and go to https://<workspace>.ziplogger.ai.
2. Choose Sign in with Microsoft and sign in as a second member of your team, ideally one who is not an Admin.
3. Confirm they land in the workspace with the role you expect. Their first sign-in links their Entra account to their existing ZipLogger account by email, or creates an account if you turned on just-in-time accounts.
4. Optionally try an account outside your allowed domains and confirm it is refused.

14. Require single sign-on (optional), after a successful test and with the recovery codes saved

Requiring single sign-on is what makes SSO a policy. Do it only when all of these are true: the test succeeded, at least one other member has signed in through Entra, and you have somewhere safe to store the recovery codes.

1. In 4 · Test, turn on, require, find the last block, Required for everyone. It lists what requiring single sign-on does. Under Before you require single sign-on, confirm each of these, tick all three confirmations: that you tested in a private window, that the recovery codes are shown once, and that you know the recovery page. If a step is missing, the block says “Not available yet. First:” and lists it.
2. Choose Require single sign-on for everyone. It takes effect immediately.
3. ZipLogger shows eight one-time recovery codes, once, in a card titled Save your recovery codes. Use Copy or Download as a text file and store them offline, outside Entra. Tick I have stored these codes somewhere that does not depend on the identity provider. Then choose Done: sign me out.
4. Your own password session ends, and you are signed out. Sign in again with Sign in with Microsoft.

From now on, password sign-in is refused for everyone in the workspace, administrators included, and existing password sessions end. Know what this does and does not reach:

• API keys keep working. Ingestion, read keys, Grafana and webhooks are credentials for systems, not people, so they are not affected.
• ZipLogger staff support access is not subject to enforcement. It is a separate, time-limited, audited grant given only to ZipLogger staff. It is not a sign-in by a member, and it is recorded in our platform audit log.
• AI assistants on the MCP server that connected through OAuth are disconnected, and cannot reconnect that way while single sign-on is required; connect them with a read API key instead.

Recovery

With a recovery code

If nobody can sign in through Entra, go to https://<workspace>.ziplogger.ai/sso/recover (the sign-in page links to it as Lost access to your identity provider?). Enter an Admin’s email address, for example [email protected], in Administrator email and one unused code in Recovery code, then choose Stop requiring single sign-on.

• The requirement ends and password sign-in works again. The sign-in button stays on. Recovery does not sign anyone in.
• We email every Admin in the workspace when a code is used. The recovery itself does not depend on that email being sent.
• Each code works once, and a valid code entered with the wrong email is spent anyway. A refused attempt never says which part was wrong.
• People whose account was created automatically on first sign-in have no password yet: they choose one with Forgot password on the sign-in page first.
• After you have fixed the cause, require single sign-on again. That issues a new set of codes and replaces the old ones.

Generate new codes

While single sign-on is required, an Admin signed in through Entra can open 4 · Test, turn on, require, find Required for everyone, and choose Generate new recovery codes. The screen asks “Generate new recovery codes?”; confirm with Replace the codes. The new set replaces the whole old set, and every earlier code stops working immediately. This is not under Linked identities.

Without a code

Write to [email protected] from an Admin’s email address and name the workspace. If we turn enforcement off for you, the change is recorded in your workspace audit log. There is no bypass address, header or request parameter for members.

Stop requiring single sign-on safely

Signed in through Entra as an Admin, open Settings → Security, go to 4 · Test, turn on, require, and in Required for everyone choose Stop requiring single sign-on. Password sign-in then works again for everyone who has a password.

• People whose account was created automatically on first sign-in have no password yet. They can use Forgot password on the sign-in page to choose one, or keep signing in with Microsoft.
• The sign-in button stays on, so the Microsoft button remains. To remove it, choose Turn the sign-in button off. That button is offered only while sign-in is not required: while it is required, the page tells you to stop requiring single sign-on first.
• Do this before you change anything you cannot test, such as retiring the Entra application. Remove configuration (under the provider settings, and not offered while sign-in is required) deletes the configuration and unlinks every identity; people keep their accounts. It does not sign anyone out: sessions people already have keep working until they lapse, so unlink the people who must lose access first.

Rotate the client secret

Entra client secrets expire, and you may want to replace one sooner. ZipLogger rotates a secret without an outage and without stopping the requirement: the new secret is saved as a pending secret, tested on its own, and only then replaces the working secret. Sign-in keeps working with the old secret the whole time, even while single sign-on is required. The controls are in the card titled Rotate the client secret, between 4 · Test, turn on, require and Linked identities.

1. Create the new secret in Entra. In Certificates & secrets, choose New client secret and copy its Value. Leave the old secret in place, and note the new secret’s expiry date.
2. Add it as pending in ZipLogger. In Settings → Security, go to Rotate the client secret. Paste <SECRET_VALUE> into New client secret (Value), optionally enter the expiry date Entra shows in Expires on (optional), and choose Save as pending secret. The working secret does not change, and nobody notices.
3. Test the pending secret. Choose Test the new secret, from your workspace address, and sign in with your work account. The check uses the new secret only; no session is created. When it passes, the card says “The new secret works.”
4. Replace the working secret. After a successful test, choose Replace the working secret. ZipLogger swaps the secrets in one step. The sign-in button stays on, whether single sign-on is required stays as it was, and sign-in is not interrupted.
5. Delete the old secret in Entra, now that ZipLogger no longer uses it.

• A pending secret has to be tested before it can replace the working one, and one saved more than seven days ago can no longer replace it: choose Discard the pending secret and save the new secret again.
• With a pending secret saved, the form in the card offers Replace the pending secret instead: saving another one replaces the first and clears its test. Discard the pending secret throws one away, and the working secret stays as it was.
• If the test of the new secret fails, the working secret was not changed. Save a corrected secret with Replace the pending secret and test again. Do not use Save changes under 3 · Provider settings for this: changing the secret there switches the sign-in button off and discards the pending secret (see step 8).
• ZipLogger refuses a GUID-shaped value here too, because that is the Secret ID.
• Every step is recorded in the workspace audit log. The secret itself never is.
• Set a reminder at least two weeks before the expiry date. If a secret expires first, every Microsoft sign-in fails (invalid_client in the audit log). An Admin who is still signed in can rotate straight away; otherwise use a recovery code to stop requiring single sign-on, rotate, and require it again.

Offboarding and sign-out

ZipLogger does not check Entra again after a person has signed in. A ZipLogger session lasts as long as it keeps being used: its refresh token is valid for 14 days, and each use issues a new one, so a session in regular use does not expire on its own. Disabling someone in Entra therefore stops new sign-ins but does not end a session that already exists. To remove someone, in this order, and then review API keys:

1. Disable the account in Entra. If you unlink before this, the person could link again at their next sign-in.
2. Unlink their identity under Linked identities. Their provider-issued browser sessions and their AI-assistant (MCP) connections can no longer be renewed.
3. Remove them under Team with Remove. Removal deletes their refresh tokens so they cannot renew a session; access already issued lapses within about 30 minutes for a browser session and within about 60 minutes for an AI-assistant connection.
4. Revoke any API key the person created or knew. API keys belong to the workspace, not to a person, so unlinking, removing and requiring single sign-on do not revoke them. Revoke those keys under Settings → API keys, and create replacements for the systems that still need one.

Signing out of ZipLogger ends the ZipLogger session only; it does not sign the person out of Microsoft. SCIM is not available, so nothing is deprovisioned automatically.

Troubleshooting

When a test or a sign-in fails, ZipLogger shows a short reason and records the precise cause in the workspace audit log (Settings → Workspace → Audit log): SSO_CONFIGURATION_TEST_FAILED for a test and SSO_LOGIN_FAILED for a sign-in. The audit entry never contains the secret.

Not supported

• SAML 2.0. Not available.
• SCIM provisioning and group-to-role mapping. Not available. People are added under Team or by just-in-time accounts, and roles are set in ZipLogger.
• Starting sign-in from Entra’s app launcher (provider-initiated sign-in). Sign-in starts at your workspace address.
• Single sign-out. Signing out of ZipLogger does not sign out of Microsoft.
• More than one identity provider per workspace.
• Google Workspace and other OpenID Connect providers are available on request. They are built but not yet validated with a live provider, so contact us before relying on them. See supported providers.