Connect single sign-on

Connecting SSO is a one-time setup with three moves: hand your identity provider two values that identify Viewer, hand Viewer your provider's metadata in return, then verify a real sign-in before turning it on for everyone. Viewer works with any SAML 2.0 provider, including Google Workspace, Microsoft Entra ID, and Okta.

In your identity provider: create the SSO app

First, get the two values that identify Viewer to your IdP:

1. Sign in to Viewer as an administrator at https://<your-organization>.chaviewer.com (your organization's Viewer address).
2. Go to Admin → Identity & Provisioning → Add provider, and choose your identity provider from the list (for example Google Workspace or Microsoft Entra ID), or the generic SAML.
3. In the configuration step you'll see two read-only values with copy buttons — copy both:
   • ACS URL — your IdP may call this the Reply URL or Assertion Consumer Service URL
   • Entity ID — your IdP may call this the Identifier or Audience URI

Then, in your IdP's admin console, create a SAML application for Viewer. The menu names vary by provider, but every IdP needs the same four things:

1. The two values you just copied — put your Viewer Entity ID in the IdP's Identifier field and your ACS URL in the Reply URL field.
2. An immutable Name ID. Map the Name ID to a stable internal identifier (such as the user's directory object ID), with format Persistent — not email or username.

3. The user's email and name. Viewer reads the user's email, first name, and last name from the standard SAML claims, which most providers send by default. The email claim is required — it's how Viewer matches the sign-in to the right account.
4. The IdP metadata — download your IdP's federation metadata (an XML file, or a metadata URL). You'll provide it to Viewer in the next section.

Finally, turn the app on for the right users in your IdP (assign the people, groups, or organizational units who should use Viewer).

Back in Viewer: finish the connection

In the Add Provider form's configuration step:

• Provide your IdP's metadata — Upload XML (recommended) using the metadata file you downloaded from your IdP, or paste the metadata URL / the individual sign-in URL, issuer, and certificate (Manual configuration). Viewer extracts what it needs.
• Attribute mapping — the fields are pre-filled with the standard claim names Viewer expects. Leave them as-is if your IdP sends the standard SAML claims (most do).
• Role assignment — choose the default role that signed-in users receive. Group-based rules are optional and require your IdP to send group membership; most organizations start with just the default role. See Roles & permissions for the role model.
• Run Test configuration (an instant check of your entries — no sign-in involved), then Save. The provider is created in a Draft state — users can't sign in with it yet.

Optional but recommended: on the Identity & Provisioning page, set Allowed email domains for this provider to your organization's email domain(s), so only addresses from your domains can sign in.

Before anyone can sign in, they also need a Viewer account. How accounts are created — pre-invited by an admin, or created automatically on first sign-in — depends on your provisioning mode; see User provisioning.

Test, then enable

1. On the provider's page, click Test sign-in. A pop-up window walks through a real sign-in round trip with your IdP. On success, the provider moves to Verified.
2. Flip the enable toggle. Users can now choose SSO on your organization's Viewer login page.

To route everyone through your IdP and turn off password sign-in entirely, see Sign-in policy.

Hitting a snag? See Troubleshooting.