SAML

Contents

Where is this feature available?
Free / Open-source
Paid
Boost
Scale
Enterprise

Security Assertion Markup Language (SAML) enables users to access multiple systems with a single set of credentials. This is helpful for growing organizations that require centralized user management in an Identity Provider (IdP).

If you are configuring IdP-based SSO for the first time, we recommend you use OIDC. Many identity providers offer better support for OIDC, because SAML is an older protocol.

Configuring SAML

For SAML to work your IdP and PostHog (SP) need to exchange information. To do this, you need to configure some settings in your IdP and on PostHog. Depending on your IdP you might need to pass PostHog information first, or the other way around. We provide complete examples for OneLogin and Okta below, but the general flow is:

  1. If you are on self-hosted, make sure you have properly set up your SITE_URL environment variable configuration.

  2. If you are on self-hosted, you will need to be running your PostHog instance over TLS.

  3. Register a new SAML 2.0 application with your IdP. If you need to pass PostHog's information to your provider first, set the following values below (alternatively if your IdP supports it, you can obtain our XML metadata from <yourdomain>/api/saml/metadata/ or https://us.posthog.com/api/saml/metadata/ for PostHog Cloud US or https://eu.posthog.com/api/saml/metadata/ for PostHog Cloud EU)

    • Single Sign On URL (also called ACS Consumer URL): <yourdomain>/complete/saml/ or https://us.posthog.com/complete/saml/ for PostHog Cloud US or https://eu.posthog.com/complete/saml/ for PostHog Cloud EU.
    • Audience or Entity ID: Your Site URL value (verbatim), on PostHog Cloud this is https://us.posthog.com or https://eu.posthog.com
    • RelayState: On PostHog cloud, get your RelayState value from the SAML configuration modal in your PostHog Organization settings. For self hosted, empty or default (will be set on every request).

  4. For SAML to work properly with PostHog, we need to receive at least the following information from your IdP in the SAML assertion payload: ID, email and first name. Optionally, you can also pass the last name. By default, PostHog expects these attributes with a certain name.

AttributeDefault name on PostHogOptional?
Permanent IDname_id❌ No
Emailemail❌ No
First (Given) Namefirst_name❌ No
Last Name (Surname)last_name✅ Yes

  1. You will now need to obtain some parameters from your IdP and configure them in PostHog for the appropriate domain in Authentication domains. Depending on your provider, they may only provide this information as an XML metadata file. If this is the case, you can open the file in a text editor and obtain the required values from there.

    • SAML Entity ID: Will be identified as EntityID or IdP issuer. This can vary greatly between providers, but it usually looks like a URL.
      • If using Azure AD the setting to use for this field is called Azure AD Identifier.
    • SAML ACS URL: The endpoint to which the SAML requests are posted. It's usually called SAML endpoint or IdP sign-on URL.
    • SAML X.509 certificate: The public certificate used to validate SAML assertions from your IdP. It must be in X509 (almost all providers will provide it in this format). If your provider gives you the certificate as a file (usually .pem), just open it with a text editor to get the contents. When setting this certificate be sure to keep any spaces and new lines (don't format it). The first and last line of the certificate (e.g. -----BEGIN CERTIFICATE-----) are optional.

    Screenshot: SAML configuration

  2. Once you've configured all the settings above, you can now log out and attempt logging in using SAML (you just need to enter your email address).

  3. For security reasons, we don't output errors directly in your browser when something goes wrong. If you need help debugging on PostHog cloud, please contact support and provide the error ID that is shown at the bottom of the error page. To debug your self-hosted configuration, you have two options:

    • Recommended. Check your app logs (this varies depending on your deployment). Any errors will be logged there.
    • If everything else fails, temporarily set environment variable DEBUG=1, errors will be fully displayed now in the browser. Please be sure to remove this once you're done, ugly things can happen if you don't.

Example: OneLogin

OneLogin quick setup

You can quickly connect OneLogin and PostHog by using the prebuilt integration.

  1. In OneLogin admin, go to Applications and click Add App. Search for PostHog and create your app.

  2. Go to the Configuration tab and where it says "PostHog domain name" enter your PostHog's instance domain (as it's also specified in the SITE_URL environment variable), but don't include any protocol or trailing slashes. Examples: playground.posthog.com, myposthog.mydomain.com, myposthogdomain.com.

  3. Go to the SSO tab. This is where you'll obtain the information you need to pass to PostHog.

    • Issuer URL needs to be set as SAML Entity ID.
    • SAML 2.0 Endpoint (HTTP) needs to be set as SAML ACS URL.
    • On X.509 Certificate click on View Details. Copy the full certificate and set it as SAML X.509 certificate.

  4. You're good to go! Click Login with SSO in PostHog's login page.

OneLogin advanced

Use this option if you want to add additional configurations to your app that are not supported with the default app catalog.

  1. In OneLogin admin, go to Applications and click Add App.

  2. Search for SAML and select SAML Custom Connector (Advanced). Set name to PostHog.

  3. Go to the Configuration tab and edit the following attributes (leave everything else as default)

    • In the Audience (EntityID) enter https://us.posthog.com.
      • If you are using our EU deployment, use https://eu.posthog.com.
      • If you are self-hosting, enter the exact same value as your SITE_URL environment variable.
    • Set the ACS (Consumer) URL Validator to a regex that only matches <yourdomain>/complete/saml/. For instance: ^https:\/\/us.posthog.com\/complete\/saml\/$ (or use eu for an EU instance)
    • Set the ACS (Consumer) URL to https://us.posthog.com/complete/saml/.
      • If you are using our EU deployment, use https://eu.posthog.com/complete/saml/.
      • If you are self-hosting, use <yourdomain>/complete/saml/.

  4. Go to the Parameters tab. You will add the following parameters. Be sure to check "Include in SAML assertion".

    • email to match the user's email ("Email")
    • first_name to match the user's first name ("First Name")
    • last_name to match the user's last name ("Last Name")

  5. Go to the SSO tab. This is where you'll obtain the information you need to pass to PostHog.

    • Issuer URL needs to be set as SAML Entity ID.
    • SAML 2.0 Endpoint (HTTP) needs to be set as SAML ACS URL.
    • On X.509 Certificate click on View Details. Copy the full certificate, removing the first and last lines and set it as SAML X.509 certificate.

  6. You're good to go! Click Login with SSO in the login page.

Example: Okta

  1. In Okta admin, go to Applications and select Create App Integration.

    Okta admin UI showing a Create App Integration button

  2. Select the SAML 2.0 option for sign-in method.

    Okta admin UI showing a Create App Integration button

  3. Select Next, name the configuration PostHog, then select Next again.

    Okta admin UI showing a Create App Integration button

  4. Navigate to your PostHog organization's authentication settings, scroll down to SAML, then select Configure.

    Okta admin UI showing a Create App Integration button

  5. Copy the ACS consumer URL from PostHog into the Okta app's Single sign-on URL field, and copy the Audience / entity ID from PostHog into the Okta app's Audience URI (SP Entity ID) field.

    Okta admin UI showing a Create App Integration button

  6. In Okta, select Next. Check the box that says This is an internal app that we have created, then select Finish.

    Okta admin UI showing a Create App Integration button

  7. Copy the Sign on URL from Okta to the SAML ACS URL field in PostHog, the Issuer from Okta to the SAML entity ID field in PostHog, and the Signing Certificate from Okta to the SAML X.509 certificate field in PostHog.

    Okta admin UI showing a Create App Integration button

  8. Select Save configuration in PostHog.

    Okta admin UI showing a Create App Integration button

  9. In Okta, navigate to the Sign On tab of your SAML app, then select Edit in the Settings section.

    Okta admin UI showing a Create App Integration button

  10. Copy the Relay state from PostHog to the Default Relay State field in Okta. Select Save

    Okta admin UI showing a Create App Integration button

  11. In Okta, scroll down to Attribute Statements add the following statements:

    NameExpression
    emailuser.profile.email
    first_nameuser.profile.firstName
    last_nameuser.profile.lastName

    Okta admin UI showing a Create App Integration button

The next time you enter your email address during login, you will see an option to login using SAML.

Warnings

When using SAML to authenticate users in PostHog, there are a few considerations to keep in mind:

  1. Only use SAML with identity providers you trust and that verify the user's email address. During login we use the email address provided by the identity provider. An untrusted identity provider could spoof a user's email address to impersonate your users.

  2. Enabling or enforcing SAML will not disable Personal API Key usage. Users can authenticate with the PostHog API using their API keys without first authenticating via SAML. You can use ID-JAG (XAA) to programmatically restrict API access using policies defined in your identity provider.

  3. Our SAML integration only handles authentication and user provisioning. It does not handle user removal. You can use SCIM to automatically deprovision users.

  4. When you enable or enforce SAML, any existing user passwords are saved. If you disable SAML SSO in the future, your users will be able to login using their pre-existing password credentials.

Still have questions?

Was this page useful?