Set up single sign-on (SSO)

With single sign-on, the people in your organization sign in to Polzy through your own identity provider instead of with a password. You set it up once for the whole organization, every workspace included, over SAML 2.0 or OpenID Connect (OIDC). This guide takes you from nothing to a tested, working sign-in: in Polzy, at your DNS host, and in your identity provider, with a section for each provider.

How it works

• Your domains. Single sign-on applies to email addresses on the domains you verify, and on their subdomains. An organization connects one identity provider and verifies as many domains as its people use.
• Signing in. Someone who types an address on your domain on the Polzy sign-in page sees Continue with and the name on your sign-in button, such as Okta, in place of Google and Microsoft.
• New people. You choose what happens the first time someone from your domain signs in: Polzy makes them a member at once, or lets in only people already invited or synced.
• Require SSO. If you choose, people on your domains can then sign in only through your identity provider.

SAML single logout, and more than one identity provider per organization, are not offered.

Before you start

You need:

• An organization on Enterprise, and to be its Owner.
• Access to your domain's DNS, to add one TXT record. See Add the TXT record at your DNS host.
• An administrator account at your identity provider, to add Polzy as an application.

Keep two browser tabs open, one on Polzy and one on your identity provider: you copy values both ways.

Let your IT team do it

If someone else looks after your identity provider, send them a setup link instead of sharing your own sign-in.

1. Open Organization settings → Security. In the Single sign-on section, find IT setup links and choose Send a link.
2. Under Send a setup link, enter Their email and the Language of the email and the page, then choose Send link.

The link opens the setup steps (provider, domain, connection, people and the test sign-in) and the SCIM token, and nothing else in Polzy. It needs no Polzy account and uses no seat, and everything done through it is recorded in the audit log. Turning single sign-on on, and requiring it, stay with you.

• A link works for 7 days, until you choose Revoke, or until you turn single sign-on on. Up to 5 can work at once, and up to 20 can be sent a day.
• Once single sign-on has been on, a link you send shows the setup and can make the SCIM token; only you can change the domains and the connection.
• A link can make the SCIM token but not replace it. Revoking a link also stops a SCIM token made through it.

Start the setup

1. Open the account menu at the bottom of the sidebar, choose Organization settings, then Security.
2. In the Single sign-on section, choose Set up single sign-on. The setup opens in six steps: Provider, Domain, Connect, People, Test and Turn on. What you enter is saved as you move on: close the setup at any point, and Continue setup brings you back to the first step with something left to do.
3. Choose your identity provider: Okta, Microsoft Entra ID, Google Workspace, OneLogin, JumpCloud, Ping Identity, Other SAML 2.0 provider or Other OpenID Connect provider. The choice sets the protocol and the field names the next steps show. Okta, Microsoft Entra ID and Google Workspace start on SAML; choose Use OpenID Connect instead to connect them with OIDC.
4. Under Name on the sign-in button, keep your provider's name or type another, such as your organization's. People on your domains see Continue with and that name.

Single sign-on

Which identity provider do you use?

1. 1Provider
2. 2Domain
3. 3Connect
4. 4People
5. 5Test
6. 6Turn on

Pick the provider your team signs in with. It decides the field names you see in the next steps, and you can change it later.

OktaSAML or OpenID ConnectMicrosoft Entra IDSAML or OpenID ConnectGoogle WorkspaceSAML or OpenID ConnectOneLoginSAMLJumpCloudSAMLPing IdentitySAMLOther SAML 2.0 providerSAMLOther OpenID Connect providerOpenID Connect

Connects with SAML.Use OpenID Connect insteadStep-by-step guide for Okta

Name on the sign-in button

People at your domain see “Continue with Okta” on the sign-in page.

Next

Step-by-step guide for your provider, beside each step, opens that provider's section of this page.

Verify your domain

Polzy trusts your identity provider only for addresses on a domain you have shown is yours.

1. In the Domain step, type the domain your people's addresses use, such as acme.com, and choose Add domain.
2. Polzy shows the record to add: type TXT, name @ (or the full domain, if your DNS host asks for it), and a value that starts with polzy-domain-verification=. Copy the value.
3. Add the record at your DNS host, at the root of the domain, not on a subdomain. See Add the TXT record at your DNS host.
4. Back in Polzy, choose Check now. The domain moves from Waiting for DNS to Verified. A new record can take from a few minutes to an hour to be seen; check again later if it is not found yet.

You can go on to the next steps while DNS catches up: only turning single sign-on on waits for a verified domain. Add each domain your people use, such as acme.com and acme.eu; each has its own record. A verified domain also covers its subdomains, such as eu.acme.com.

Add the TXT record at your DNS host

Your DNS host is where your domain's records are kept: often the company you bought the domain from, sometimes a separate service. Every host asks for the same three things: the type (TXT), the name or host (@ for the root of the domain), and the value Polzy showed. Leave the time to live (TTL) at its default.

Connect your identity provider

Connecting takes both sides: your identity provider needs Polzy's addresses, and Polzy needs your identity provider's.

Polzy's side, for SAML. Under Paste these into your identity provider, Polzy shows two values to copy, each labelled with the name your provider gives that field, and the attributes it should send.

Your identity provider's side. Under Details from your identity provider, give Polzy its settings in one of three ways:

• Metadata URL: paste the address of its metadata and choose Import. Once single sign-on is on, Polzy reads it again every day, so a new signing certificate reaches Polzy by itself.
• Upload file: the metadata XML file it offers, up to 1 MB.
• Enter manually: its Identity provider entity ID (sometimes called the issuer), its Sign-in URL, and its Signing certificate, including the BEGIN and END lines.

The attributes Polzy reads (SAML). The names are matched without regard to capitals.

If your identity provider uses other names, change them in the People step under Advanced: attribute names. The assertion must be signed with SHA-256 or stronger: a response signed with SHA-1 is refused.

For OpenID Connect, copy Polzy's Redirect URI into your identity provider, then enter its Issuer URL, the Client ID and the Client secret in Polzy. The client secret is stored encrypted; leave the field empty later to keep it. Polzy asks for the openid, email and profile scopes, and reads email, given_name, family_name and, if you use group rules, groups.

The sections below say where each value goes in each identity provider, with a link to that provider's own guide.

Okta

1. In the Okta Admin Console, go to Applications → Applications and choose Create App Integration. If Okta asks which wizard to use, choose Classic experience. Select SAML 2.0 and choose Next.
2. Name the app Polzy and choose Next.
3. Paste Polzy's Single sign-on URL into Single sign-on URL and keep Use this for Recipient URL and Destination URL selected. Paste its Audience URI (SP Entity ID) into Audience URI (SP Entity ID).
4. Set Name ID format to EmailAddress and Application username format to Email.
5. Under Attribute Statements, add email with the value user.email, firstName with user.firstName and lastName with user.lastName. To place people by group, add a Group Attribute Statement named groups with a filter such as Starts with polzy.
6. Choose Next, select I'm an Okta customer adding an internal app, and choose Finish.
7. On the app's Sign On tab, copy the Metadata URL and paste it into Polzy under Metadata URL, then choose Import.
8. On the Assignments tab, choose Assign and assign the people or groups who use Polzy.

For OpenID Connect, create the integration with OIDC - OpenID Connect and Web Application, paste Polzy's address into Sign-in redirect URIs, and give Polzy the Client ID, the Client secret and your Okta address, such as https://acme.okta.com, as the issuer.

Okta's guides: Create SAML app integrations, Create OpenID Connect app integrations and Assign an app integration to a group.

Microsoft Entra ID

1. In the Microsoft Entra admin center, go to Entra ID → Enterprise apps → All applications, choose New application, then Create your own application.
2. Name it Polzy, choose Integrate any other application you don't find in the gallery (Non-gallery) and choose Create.
3. Open Single sign-on and choose SAML.
4. Under Basic SAML Configuration, choose Edit. Paste Polzy's Identifier (Entity ID) into Identifier (Entity ID) and its Reply URL (Assertion Consumer Service URL) into Reply URL (Assertion Consumer Service URL), then save.
5. Under Attributes & Claims, the default claims already carry the names and send the user principal name as the Name ID, which Polzy uses as the email address. If your people's user principal names are not their email addresses, choose Add new claim, name it email and pick the source attribute user.mail: Polzy reads a claim named email first. To place people by group, choose Add a group claim and Groups assigned to the application.
6. Under SAML Certificates, copy the App Federation Metadata Url and paste it into Polzy under Metadata URL, then choose Import.
7. Under Users and groups, choose Add user/group and assign the people or groups who use Polzy.

Entra sends each group as its object ID unless you choose another format, so a group rule in Polzy names the group exactly as Entra sends it. The test sign-in shows you what that is.

For OpenID Connect, register an app under App registrations with the account type for your own tenant only, add Polzy's address as a Web redirect URI, and create a client secret under Certificates & secrets. The issuer is https://login.microsoftonline.com/<tenant ID>/v2.0, with your tenant's ID.

Microsoft's guides: Enable SAML single sign-on for an enterprise application, Customize SAML token claims, Configure group claims, Manage users and groups assignment to an application, Register an application, Add a redirect URI and Add credentials.

Google Workspace

1. In the Google Admin console, go to Apps → Web and mobile apps and choose Add App → Add custom SAML app.
2. Name the app Polzy and continue.
3. On Google Identity Provider details, choose Download IDP metadata and keep the file for Polzy.
4. On Service Provider Details, paste Polzy's ACS URL into ACS URL and its Entity ID into Entity ID. Set Name ID format to EMAIL and Name ID to Basic Information > Primary email.
5. Under Attribute mapping, map First name to firstName and Last name to lastName. To place people by group, add the groups under Group membership with the app attribute groups; Google sends up to 75.
6. Choose Finish, then upload the metadata file to Polzy under Upload file.
7. Open the app's User access and turn it on for everyone, or for the organizational units or groups who use Polzy. Google can take up to 24 hours to apply it.

For OpenID Connect, create an OAuth client of the type Web application in the Google Cloud console, add Polzy's address under Authorized redirect URIs, and give Polzy the client ID and secret with the issuer https://accounts.google.com. Only accounts in your Google Workspace, on one of your verified domains, can sign in this way.

Google's guides: Set up your own custom SAML app, Manage OAuth clients and OpenID Connect.

OneLogin

1. In OneLogin, go to Applications → Applications and choose Add App. Find SAML Custom Connector (Advanced), name it Polzy and save.
2. On the Configuration tab, paste Polzy's Entity ID into Audience (EntityID), and its ACS URL into Recipient and ACS (Consumer) URL. For ACS (Consumer) URL Validator, enter the ACS URL with ^ before it and $ after it.
3. Set SAML nameID format to Email and SAML signature element to Assertion, then save.
4. On the Parameters tab, add email, firstName and lastName with the values Email, First Name and Last Name, each included in the SAML assertion. To place people by group, add groups with the value User Roles as a multi-value parameter.
5. On the SSO tab, copy the Issuer URL and paste it into Polzy under Metadata URL, then choose Import.
6. Give the people who use Polzy access to the app, through their roles or under Users.

OneLogin's guide: Advanced SAML Custom Connector.

JumpCloud

1. In the JumpCloud Admin Portal, go to Access → SSO Applications, choose Add New Application, then Custom Application, and choose Manage Single Sign-On (SSO) with Configure SSO with SAML. Name it Polzy.
2. Enter a unique IdP Entity ID, such as your domain. Paste Polzy's Entity ID into SP Entity ID and its ACS URL under ACS URLs.
3. Set SAMLSubject NameID to email and SAMLSubject NameID Format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, and sign the assertion.
4. Under User Attributes, add email, firstName and lastName, mapped to the user's email, first name and last name. To place people by group, select Include Group Attribute; Polzy reads JumpCloud's default name, memberOf, as well as groups.
5. Activate the application, choose Export Metadata and upload the file to Polzy under Upload file. Or choose Copy Metadata URL and import it.
6. On the User Groups tab, add the groups who use Polzy.

JumpCloud's guides: SSO using custom SAML application connectors and SSO application connector fields.

Ping Identity

1. In PingOne, go to Applications → Applications and add an application. Name it Polzy and choose SAML Application, then Configure.
2. Choose Manually Enter: paste Polzy's ACS URL under ACS URLs and its Entity ID into Entity ID. Or choose Import from URL with Polzy's metadata URL. Save.
3. On the Attribute Mappings tab, map saml_subject to Email Address, and add email (Email Address), firstName (Given Name) and lastName (Family Name). To place people by group, add groups, mapped to Group Names.
4. On the app's Overview tab, copy the IDP Metadata URL and paste it into Polzy under Metadata URL, then choose Import.
5. Turn the application on, and on its Access tab give the groups who use Polzy access.

In PingFederate, create an SP connection from Polzy's metadata URL, with the email address as the subject, and give Polzy the metadata of the connection.

Ping Identity's guides: Adding an application, Editing a SAML application, IdP metadata for SAML applications and Accessing SP connections.

Another SAML 2.0 provider

Any identity provider that supports SAML 2.0 works. Choose Other SAML 2.0 provider in the first step, then in your identity provider:

• Add a SAML application with Polzy's ACS URL and Entity ID, or let it read Polzy's metadata URL.
• Send the email address as the NameID, in the email address format, or as an email attribute.
• Sign the assertion with SHA-256 or stronger. Polzy accepts several signing certificates at once, so a certificate can be replaced without a gap.
• Add the attributes firstName and lastName and, to place people by group, groups.

Then give Polzy its metadata, by URL or as an XML file, or enter its settings by hand.

OpenID Connect

Use OpenID Connect with any identity provider that offers it. Choose Other OpenID Connect provider in the first step, or Use OpenID Connect instead for Okta, Microsoft Entra ID or Google Workspace.

1. In your identity provider, create a web application that signs in with the authorization code flow and has a client secret.
2. Add Polzy's Redirect URI as its sign-in redirect URI.
3. Allow the scopes openid, email and profile. A groups claim in the ID token is optional, to place people by group.
4. In Polzy, enter the Issuer URL: the address your provider's /.well-known/openid-configuration is found under. Then the application's Client ID and Client secret.

An address your identity provider marks as not verified is refused. With Microsoft Entra ID, the issuer must name your tenant: https://login.microsoftonline.com/<tenant ID>/v2.0. The shared issuers common, organizations and consumers are refused, because any Microsoft account could sign in through them.

Guides: OpenID Connect Discovery (the OpenID Foundation's specification of the issuer address) and Microsoft: OpenID Connect on the Microsoft identity platform.

Choose who gets in

The People step decides what happens the first time someone from your domain signs in through your identity provider.

• Create a member automatically. Choose the Workspace they join and their Role in it, Viewer to begin with. A new member takes a seat; while none is free, their sign-in is refused.
• Only people already invited or synced. Someone who is not yet a member is turned away and asked to contact an admin, even with a valid sign-in at your identity provider.

People who are already members keep their workspaces and roles. Their first sign-in through your identity provider links their Polzy account to it. A deactivated member stays deactivated.

Group rules (optional) place people by group: add a rule for each group, with the group's name as your identity provider sends it, a workspace and a role. At someone's first sign-in, Polzy reads the groups attribute: the new member joins the workspace each of their groups names, with the role its rule gives. Later sign-ins change no workspace or role, so without SCIM a rule reaches people only when they first arrive. Your identity provider has to send the groups attribute.

Under Advanced: attribute names, change the names Polzy reads the email address, first name, last name and groups from. Under Workspace fields, an attribute your identity provider sends, such as a department or a country, fills a field of the workspace: it is written when someone joins and brought up to date each time they sign in.

If you will also use SCIM provisioning, it places people with this same workspace, role and group rules: SCIM has no rules of its own, and its Edit group rules opens this step. With SCIM the groups come from your directory rather than from the sign-in, and the rules are applied each time it adds someone to a group or takes them out of one, including people who first arrived by signing in.

Test the sign-in

1. In the Test step, choose Test sign-in. Your identity provider opens in a new tab; if your browser blocks it, choose Open the test sign-in.
2. Sign in at your identity provider as someone on a verified domain.
3. Back in Polzy, the result appears by itself; if it does not, choose Check for the result.

Polzy shows exactly what your identity provider sent: under What a sign-in would use, the email address, the names and the groups, each Received or Not sent; and under Everything your provider sent, every attribute with its value.

When the test fails, Polzy says why in plain words and where to fix it. Change the setting at your identity provider and choose Test again.

A test signs nobody in and creates no session. Each test opens through an address that works once, for 10 minutes, and the page waits up to two minutes for the answer. A passing test counts for 7 days: turning single sign-on on, and requiring it, need one from the last 7 days.

Turn it on

The Turn on step lists what is still needed: a domain verified, your identity provider connected, the first sign-in settled, and a test sign-in passed in the last 7 days. When each is ticked, choose Turn on single sign-on.

From then on, people on your verified domains sign in through your identity provider:

• On the sign-in page, they type their email address and choose Continue with and the name on your button.
• A link into one of your workspaces, and the Polzy tile in your identity provider, take them through the same sign-in.
• For a bookmark, use app.polzy.ai/login?sso= followed by your workspace's address, such as app.polzy.ai/login?sso=acme.

Until you require single sign-on, people can also still sign in the way they did before. Turning it on ends every IT setup link that still works.

While single sign-on is on, your domains stay yours: signing up for Polzy with an address on them, with the form or with Google or Microsoft, is refused, and the page offers your organization's sign-in instead.

Your identity provider vouches for people in your organization's workspaces only. Someone who signed in through it and then opens a workspace of another Polzy organization is first asked for their own two-step verification code, if they have it on, unless they chose Trust this device for 30 days on that device.

Require SSO

With Require single sign-on on, people on your verified domains can sign in only through your identity provider. A password, an emailed sign-in link, and Google or Microsoft sign-in are refused for them.

1. Open Manage in the Single sign-on section. The last step is now Manage single sign-on.
2. Switch on Require single sign-on. Polzy says how many members will then sign in only through your identity provider.
3. Choose Require it. The sessions of those members who signed in another way end at once, never yours.

• It needs a verified domain, a test sign-in passed in the last 7 days, and a way back in for you: be signed in through single sign-on yourself, or have two-step verification on.
• If your plan no longer includes single sign-on, it stops applying and members sign in the other ways again. Nobody is locked out.
• It applies to addresses on your verified domains only. A member on another domain, a contractor for example, still signs in with a password, a link, or Google or Microsoft.

Who can still sign in without it. So the organization is never locked out while your identity provider is down, the Owner can always sign in another way, and so can each admin you add with Add an admin. Each of them needs two-step verification on to use it: the list shows who has it. Taking someone off the list while single sign-on is required ends their other sessions at once.

Manage, turn off or delete

Admins see the state of single sign-on under Organization settings → Security: your verified domains, the identity provider with its last sign-in, whether single sign-on is required, the IT setup links and SCIM. Only the Owner sees Manage.

Under Danger zone, in Manage single sign-on:

• Turn off single sign-on (Turn off): people sign in with their password or a sign-in link again, and requiring single sign-on stops too. The settings are kept, to turn it on again later.
• Delete the connection (Delete): removes the connection and all its settings; your verified domains stay. A connection that is on cannot be deleted: turn it off first. Switching between SAML and OpenID Connect also needs it off.

Certificates

A SAML signing certificate has an expiry date, shown with your connection under Organization settings → Security. Polzy warns the organization's admins, in the app and by email, 30, 7 and 1 days before the soonest one expires, and again once every saved certificate has expired. Several certificates can be active at once: add the new one at your identity provider, give Polzy the updated metadata, and only then retire the old one.

If you gave Polzy a metadata URL, Polzy reads it again every day while single sign-on is on and saves a new certificate by itself. If the address stops answering, the certificates already saved keep working; the Security tab says for how many days, and the admins are told after three days in a row.

Polzy never switches single sign-on off over a certificate, but once your identity provider signs with one Polzy does not have, sign-ins fail until you give Polzy the updated metadata.

Troubleshooting

Run a test sign-in first: it shows what your identity provider sent, and the message says what to fix.

Two more causes the test does not name:

• The wrong address arrives. In Okta, the application username is the Okta username unless you set Application username format to Email. In Entra, the Name ID is the user principal name. When that is not the address people use in Polzy, send the right one in an email attribute.
• Group rules do nothing. The group's name in the rule must match what your identity provider sends: Entra sends object IDs unless you change the format. Copy the value from Everything your provider sent in the test.

Useful links

• Okta: Create SAML app integrations
• Microsoft: Enable SAML single sign-on for an enterprise application
• Google: Set up your own custom SAML app
• OneLogin: Advanced SAML Custom Connector
• JumpCloud: SSO using custom SAML application connectors
• Ping Identity: Adding an application
• Next: Provision members with SCIM, and Organization security for session length and two-step verification.