How it works
Two systems take part in every sign-in:- Your identity provider (IdP), such as Okta, holds your company accounts. It checks the password and any multi-factor step.
- OpenWhispr is the service provider (SP): the app people sign in to. It never sees the password. It trusts your IdP’s signed answer about who the person is.
Before you start
You need:- an active OpenWhispr Enterprise workspace with owner or admin access. Enterprise is set up with our team: you create an OpenWhispr account and a workspace in the desktop app, and we activate it as Enterprise
- a company email domain, such as
acme.com. Personal email domains like Gmail or Outlook are refused - administrator access to your identity provider
- access to your domain’s DNS, to add one TXT record
Values to give your identity provider
Every URL below includes your Provider ID, so choose it first. Use lowercase letters, numbers,-, and _, for example acme-okta. When you enter a Provider ID in Add provider, the admin portal shows these URLs filled in. Copy them from there; the patterns here are for reference.
Once the provider is saved, the SP Entity ID URL also serves OpenWhispr’s SAML service-provider metadata, which some identity providers, such as Microsoft Entra ID, can import.
Connect your identity provider
1
Start adding the provider
In the admin portal, open Security > Single sign-on and select Add provider. Choose SAML or OIDC, then enter:
- Provider ID, for example
acme-okta - Email domain, for example
acme.com
2
Create the app in your identity provider
- Okta (SAML)
- Okta (OIDC)
- Microsoft Entra ID (SAML)
In the Okta Admin Console, create a new app integration and choose SAML 2.0. On the SAML settings page:
Leave Okta’s signature settings at their defaults (Response and Assertion signed).Attribute statements are optional. OpenWhispr reads
email, givenName, and surname, or displayName for the full name. Without an email attribute, the Name ID is used as the email.So employees can start from their Okta dashboard, set Login initiated by to Either Okta or App. See Sign in from an app tile.Assign the people or groups who should use OpenWhispr. Then open the app’s Sign On tab and view the SAML setup instructions. You need three values from there:- Identity Provider Issuer, which looks like
http://www.okta.com/exk… - Identity Provider Single Sign-On URL
- X.509 Certificate
3
Finish adding the provider
Back in the admin portal dialog, enter the values from your identity provider.
Save the provider.
4
Verify your domain
On the new provider, select Get DNS record. Add the TXT record it shows to your domain’s DNS. Its name has the form
_better-auth-token-{providerId}.{domain}, for example _better-auth-token-acme-okta.acme.com. Then select Verify domain.Until the domain is verified, nobody from that domain is sent through SSO. DNS changes can take a while to appear, so try again later if verification fails right away.5
Test with a pilot employee
Have an assigned employee open the OpenWhispr desktop app, select Sign in with SSO, and enter their work email. They finish sign-in in the browser and return to the app.
6
Require SSO and connect directory sync (optional)
Once sign-in works, you can turn on Require SSO under Security > Single sign-on. It blocks password and social sign-in for the verified domain. The workspace owner is exempt, so a misconfigured identity provider can always be undone.To create and remove workspace members from your directory, set up SCIM provisioning. If you plan to use it, read its rollout order before you enable Require SSO.
How people sign in
- Employees open the OpenWhispr desktop app, select Sign in with SSO, and enter their work email.
- Admins sign in to the admin portal at admin.openwhispr.com/sign-in with Continue with SSO.
Who joins your workspace
The first time someone signs in through SSO, OpenWhispr adds them to your workspace as a member, and they take a seat. You don’t invite them first. So your identity provider decides who gets OpenWhispr. Only people assigned to the OpenWhispr app in your IdP can finish signing in. For a pilot, assign just the pilot group, then assign more people when you’re ready to roll out. If you use SCIM provisioning, your directory decides instead: people are added when your IdP sends them over, and removed when it deactivates them.Sign in from an app tile
With the Okta settings above, an employee can click the OpenWhispr tile on their Okta dashboard. The tile starts a normal sign-in and opens the OpenWhispr desktop app, so the app must be installed on that computer.Signing in from an app tile requires the latest OpenWhispr service update. If a tile click doesn’t open the app, employees can sign in from the desktop app as described above.
Troubleshooting
Rotate a SAML signing certificate
The admin portal cannot edit an existing provider. To use a new signing certificate, remove the provider, add it again, and re-verify the domain:- If directory sync uses this provider, pause sync and move its connection to another verified provider first. Pausing alone does not allow removal.
- If this is the last verified provider, turn off Require SSO before removing it.
- Under Security > Single sign-on, remove the provider, then add it again with the same Provider ID and the new signing certificate.
- Select Get DNS record, update the TXT record with the new value, and select Verify domain.
- Test sign-in with a pilot employee before restoring Require SSO or moving directory sync back and resuming it.