Skip to main content

How to configure SSO with PingOne

Do not map users to untrusted attributes

passbolt relies on the identity provider to authenticate users and to assert their identity, and matches users to existing passbolt accounts by their email address. Only use an identity provider that guarantees users can authenticate only as email addresses they legitimately own and that you administer. If the provider lets users self-assign or modify unverified email addresses, an attacker may be able to impersonate another user.

Attention

This feature requires HTTPS to work.

Since version 5.11, passbolt Pro Edition supports SSO with PingOne, Ping Identity's cloud identity platform, through a dedicated PingOne provider.

PingOne only

This provider works with PingOne's regional authentication domains (auth.pingone.com and its regional variants). It does not cover PingFederate or PingID, which are different Ping Identity products, and it does not accept a PingOne custom domain. For those, use the generic OpenID provider instead.

How does it work?​

passbolt SSO uses PingOne's OpenID Connect endpoints alongside the existing challenge-based authentication. When a user logs in through PingOne, they unlock a server-side key needed to decrypt their secret key passphrase.

passbolt discovers the PingOne endpoints from your regional authentication domain and environment ID, at https://auth.pingone.com/<environment-id>/as/.well-known/openid-configuration. PingOne asserts the user's identity through the email claim by default, so each user's PingOne email must be the same address as their passbolt account.

Prerequisites​

You need the following to configure PingOne SSO with passbolt:

  • A PingOne environment where you can create applications
  • Administrative access to both the PingOne admin console and passbolt
  • Each user's PingOne email set to the email address of their passbolt account

Configuration​

danger

Email addresses must match exactly between the SSO provider and Passbolt. Users can only sign in with SSO if their email address exists in both systems.

Step 1: Create a PingOne application​

In the PingOne admin console, create an OpenID Connect web application for passbolt.

  1. Go to Applications > Applications and click the + button.
  2. Give the application a name (for example, "passbolt SSO"), select OIDC Web App as the application type, then click Save.
  3. On the application's Configuration tab, click the pencil icon and set:
    • Response Type: Code
    • Grant Type: Authorization Code
    • Redirect URIs: the passbolt redirect URL. You will find the exact value on the passbolt SSO administration screen in Step 2; it has the form https://passbolt.example.com/sso/pingone/redirect.
    • Token Endpoint Authentication Method: Client Secret Post. passbolt sends the client credentials in the body of the token request, which matches this method.
    • PKCE Enforcement (in the Grant Type section): Optional. passbolt does not send a PKCE code challenge, so Required or S256_required makes PingOne reject the token request.
  4. Click Save.
  5. On the Resources tab, click the pencil icon and grant the openid, profile and email scopes.
  6. Enable the application with the toggle at the top of the application panel.
  7. On the Configuration tab, copy the Environment ID, Client ID and Client Secret.

Step 2: Configure passbolt​

  1. Sign in to passbolt with an administrator account.
  2. Select ⚙ > Organisation settings > Single Sign-On in the top right corner.
  3. Select PingOne as the provider.
  4. Copy the Redirect URL shown on this screen and add it to your PingOne application's redirect URIs (Step 1) if you have not already.
  5. Fill in the configuration:
FieldValue
URLSelect the authentication URL for your region from the dropdown: https://auth.pingone.com (default), https://auth.pingone.eu, https://auth.pingone.ca, https://auth.pingone.asia, https://auth.pingone.com.au or https://auth.pingone.sg
Environment IDThe environment ID (a UUID) from your PingOne application's Configuration tab
Application (client) IDThe client ID from your PingOne application
SecretThe client secret from your PingOne application
Email claimThe claim carrying the user's email address, email by default

The Scope field is fixed to openid profile email and cannot be changed.

  1. Click Save to run a test authentication, and complete the PingOne login flow.
  2. If the test succeeds, save the settings permanently.

Step 3: Test the configuration​

  1. Sign out from passbolt.
  2. On the login page, select Sign in with PingOne.
  3. Confirm you can authenticate through PingOne and reach your passbolt account.

Troubleshooting​

Authentication fails: verify the environment ID, client ID and secret, that the redirect URI in PingOne matches the passbolt redirect URL exactly, and that the application is enabled.

The sign-in fails after the PingOne login step: check that the application's Token Endpoint Authentication Method is Client Secret Post and its PKCE Enforcement is Optional, and that the openid, profile and email scopes are granted on the Resources tab.

The user cannot sign in: confirm the user's PingOne email is exactly the email address of their passbolt account, and that the user is allowed to access the application in PingOne.

Your region or custom domain is not in the URL list: the URL dropdown only offers the six regional authentication URLs above. If your organisation uses a PingOne custom domain or PingFederate, configure the generic OpenID provider instead.

The PingOne provider does not appear: check that both your passbolt server and browser extension are on 5.11 or later, and that the environment variable PASSBOLT_PLUGINS_SSO_PROVIDER_PINGONE_ENABLED is not set to false. The provider tile comes from the browser extension, so a 5.11 server with an older extension will not show it.

To enable SSO debug logging, set the environment variable:

PASSBOLT_PLUGINS_SSO_DEBUG_ENABLED=true

Important notes​

  • Users must sign in with their passphrase after SSO is activated for the SSO option to appear on later logins.
  • HTTPS is required for SSO to function.
  • passbolt does not track the expiry date of the PingOne client secret and does not send a reminder before it expires. If you set an expiry on the secret in PingOne, plan the rotation yourself: SSO login stops working as soon as the secret expires.
SSO account recovery

Once an SSO provider is active, users can also authenticate with it to recover access to their account on a new browser, instead of using the email verification link. See how a user recovers an account with SSO.

There is no toggle in the administration interface. To turn the feature off, select your installation method:

Open /etc/passbolt/passbolt.php and edit the plugins block:

[...]
'passbolt' => [
  'plugins' => [
      'sso' => [
          'ssoRecover' => [
              'enabled' => false,
          ],
      ],
  ],
],
[...]