Breadcrumbs

Enterprise Single-Sign-On (SSO)

Description

Enterprise SSO makes it possible for users to log in to Piano Analytics via their organization's own ID Platform (IdP). A major benefit of using Enterprise SSO is secure access to Piano Analytics only for verified users from your IdP platform.

We support the simplified connectors for the following IdPs:

  • Microsoft Entra ID (former Azure AD)

  • Google Workspace

  • Okta Workforce

We also support the following protocols:

  • OpenID generic (OIDC) - to be preferred

  • SAML 2.0

Please reach out to your Piano Account representative for more information about pricing for this solution. 

Good to know

SSO will be activated on all the email domain names you will provide for activation - note that you must be the owner of the domain emails. Any user with an email using these domains will be SSO users de facto.

Below is a list of the information you will need to provide for SSO activation, depending on your IdP. Feel free to contact our support team if you need help.

Microsoft Entra ID (Azure AD) configuration

You must first register an application on Entra ID with the following information:

Once done, you will need to provide the following information to our support team:

  • Entra ID domain name

  • Entra ID Tenant ID

  • Application's Client ID

  • Application's Client secret value

  • Type of tenant (single, multiple tenants,...)

  • Optional list of secondary email domains for which SSO will be enabled

You will find more information on how to configure Microsoft Entra ID here.

Google Workspace configuration

You will need create and configure your Google application with the following information

Once done, you will need to provide the following information to our support team:

  • The application Client ID

  • The application Client Secret

  • Google Workspace Domain for which SSO will be enabled

You will find more information on how to configure Google Workspace here.

OpenID generic (OIDC) configuration

You will need create and configure your application with the following information:

Once done, you will need to provide the following information to our support team:

  • The application Client ID

  • The application Client Secret

  • Well-known URL

  • List of email domains for which SSO will be enabled

You will find more information on how to configure your OpenID here.

Okta Workforce configuration

You will first need to create an application on your Okta tenant. Your application must be created and configured with the following information:

Once done, you will need to provide the following information to our support team:

  • Okta Domain (domain-name.okta.com or custom domain)

  • The application Client ID

  • The application Client Secret

  • List of email domains for which SSO will be enabled

You will find more information on how to configure Okta Workforce here.

SAML 2.0 configuration

Please provide the metadata URL of your IDP, including this mandatory information:

  • SAML login URL use for start the exchange between SP and IDP

  • X.509 certificate used for sign the exchanges from the IDP

  • You will also need to provide the list of the domain names you'd like to use with SSO.

Testing

Once Piano has deployed its updated configuration, testing can begin.

You will need to test some login actions with our test application accessible at this URL: https://my.piano.io/client-testing-application/

If the test user can see this interface with his email as the connected email, this will assure us that it will work in production.

image-20260506-132436.png

Production activation

If the tests are conclusive, on the date you have specified, we will put the new configuration into production and shut down the old one.

About Client Secret

You are responsible for the validity of your Client Secret Key and its renewal in case of expiration. Please contact us at least one month in advance before expiration, or if you plan to make any changes so we can reflect them on your Piano Analytics configuration.

Login

Clients with Enterprise SSO will use one of the below URLs to log in to the respective Piano Product.

Once the Enterprise SSO is activated, a user who is already logged in to your IdP will be automatically redirected to the appropriate URL (see above).

If a user is not already logged in to your IdP, they will be redirected to the IdP login.

When SSO is active on your email domain, you must log in with the same credentials you use to access other corporate applications, not a Piano Analytics-specific password.

The "Forgot password?" option on the Piano Analytics login page does not work for SSO users — there is no Piano password to reset. If you've forgotten your enterprise password, reset it through your IdP (or with your IT team), not through Piano Analytics.

API Keys

Since SSO users do not have a password, they need to rely on API Keys to authenticate to external API calls. Find out more about API Keys.

Emails

The email sender address for user emails, such as registration and password reset, will be updated based on the IdP provider that has been implemented.

Troubleshouting

"Forbidden" or access errors after SSO redirect

If your IdP authenticates you successfully, but Piano Analytics then shows a Forbidden or "you don't have access" error, the most common causes are:

  • Your account hasn't been registered yet in Piano Analytics for your organization. The IdP recognizes you, but Piano Analytics has not been told you should have access. Contact your organization's Piano administrator to confirm your user record exists in Access Management.

  • Your email domain matches an SSO domain, but your account was created under a different organization. When SSO is enabled on a domain, all users with that email domain become SSO users automatically — including users whose account was provisioned under a different organization. Your administrator may need to adjust your default organization.

HTTPS / certificate errors on SSO redirect

If you see a browser HTTPS or certificate error specifically during the SSO handoff, the cause is usually outside Piano Analytics:

  1. Try disabling your VPN and reattempt the login. Some VPNs install a TLS-inspection certificate that interferes with the SSO redirect.

  2. Try a different network, such as a personal hotspot. If the SSO flow completes there, ask your IT team to allowlist the Piano authentication domains so the inspection doesn't break the handoff.

  3. If the error persists across networks, your IdP configuration may need to be re-verified — contact Piano Support and your IdP administrator together, and share the exact error text from the browser.