SAML

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, because it is generally considered more secure and simpler to operate than SAML.

Prerequisites

1. If you are using PostHog cloud, your organization must be subscribed to a platform package that offers SAML. If you are self-hosting PostHog, your instance must have an enterprise license that supports SAML.

2. You need to verify domains for any email address that you want to allow users to log in with. For example, if you want to allow users with an @example.com email address to log in, like john@example.com, you need to add and verify example.com as an authentication domain.

3. If you are self-hosting PostHog, make sure you have properly set up your SITE_URL environment variable configuration.

4. If you are self-hosting PostHog, your PostHog instance must be accessible from the public internet over TLS.

Configuring SAML

1. Navigate to your organization's authentication settings page in PostHog.

2. Scroll down to the SAML section, and select Configure.

3. In your IdP, create a new SAML app for PostHog.

   a. Copy the "ACS Consumer URL", "Audience / entity ID", and "Relay state" displayed in PostHog into your SAML app's configuration in your IdP.

   b. Copy the following values from your SAML app's configuration in your IdP into PostHog:

   • ACS URL (also called Sign-on URL or SAML endpoint)

   • Entity ID (also called Issuer, IdP issuer, or Azure AD Identifier)

   • X.509 certificate used to verify SAML assertions

     Your IdP might provide these values in an XML metadata file. If the certificate is provided as a file, open it in a text editor and copy its contents without changing the spaces or line breaks. The BEGIN CERTIFICATE and END CERTIFICATE lines are optional.

   c. Verify that your IdP shares the following attributes in the SAML assertion with PostHog:

   Attribute	Default name in PostHog	Optional?
   Permanent ID	name_id	❌ No
   Email	email	❌ No
   First (given) name	first_name	❌ No
   Last name (surname)	last_name	✅ Yes

4. Select Save.

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 select Add App.

   

2. Search for "PostHog". Select the option that appears with that exact name, and which shows "OneLogin, Inc." as the author.

   

3. Confirm the app details are correct, then select Save.

   

4. Navigate to the Configuration tab. In "PostHog domain name" enter the domain name you use to access PostHog. For example, if you use PostHog cloud, this will either be "us.posthog.com" or "eu.posthog.com".

   

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

   

6. In OneLogin admin, go to the SSO tab.

   a. Copy the Issuer URL from OneLogin into the Entity ID configuration field in PostHog.

   b. Copy the SAML 2.0 Endpoint (HTTP) from OneLogin into the SAML ACS URL configuration field in PostHog.

   c. On X.509 Certificate click on View Details. Copy the full certificate into the SAML X.509 certificate configuration field in PostHog.

   

7. Select Save configuration in PostHog.

   

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

OneLogin advanced

Use a custom SAML connector if you need app configurations that the prebuilt integration doesn't support.

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

   

2. Search for "SAML" and select SAML Custom Connector (Advanced).

   

3. Name the app "PostHog" and select Save.

   

4. Navigate to the Configuration tab. Set the following fields, and leave everything else at its default value:

   a. Enter https://us.posthog.com in Audience (EntityID). For the EU deployment, use https://eu.posthog.com. For a self-hosted instance, use the exact value of your SITE_URL environment variable.

   b. Set ACS (Consumer) URL Validator to a regular expression that only matches <yourdomain>/complete/saml/. For example, use ^https:\/\/us.posthog.com\/complete\/saml\/$ for the US deployment, or replace us with eu for the EU deployment.

   c. Enter https://us.posthog.com/complete/saml/ in ACS (Consumer) URL. For the EU deployment, use https://eu.posthog.com/complete/saml/. For a self-hosted instance, use <yourdomain>/complete/saml/.

   

5. Navigate to the Parameters tab. Add the following parameters, and select Include in SAML assertion for each one:

   a. Map email to the user's Email.

   b. Map first_name to the user's First Name.

   c. Map last_name to the user's Last Name.

   

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

   

7. In OneLogin admin, go to the SSO tab.

   a. Copy the Issuer URL from OneLogin into the Entity ID configuration field in PostHog.

   b. Copy the SAML 2.0 Endpoint (HTTP) from OneLogin into the SAML ACS URL configuration field in PostHog.

   c. On X.509 Certificate, select View Details. Copy the certificate without its first and last lines into the SAML X.509 certificate configuration field in PostHog.

   

8. Select Save configuration in PostHog.

   

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

Example: Okta

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

   

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

   

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

   

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

   

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.

   

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

   

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.

   

8. Select Save configuration in PostHog.

   

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

   

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

    

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

    Name	Expression
    email	user.profile.email
    first_name	user.profile.firstName
    last_name	user.profile.lastName
    

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.