Single Sign-On (SSO) via SAML

Steps to setup Single Sign-On (SSO) through Security Assertion Markup Language 2.0 (SAML 2.0)

Updated over a week ago

HackerOne supports Single Sign-On (SSO) through Security Assertion Markup Language 2.0 (SAML 2.0) for these providers:

Contact HackerOne if you have another SAML provider.

Setup

Step 1 - Configure

  1. Go to Organization Settings > Authentication > SAML (SSO).
    Note: You must be an organization administrator to set up SAML.

  2. Click Add SAML Provider.

  3. Enter information for the fields below and click Save.

Field

Details

Name

The name of the SAML provider

Domain

The domain for users that will be required to use SAML authentication. The domain must be verified before entering. If you don't have a verified domain, see Domain Verification to set up a verified domain. Note: Please use your own domain, not the HackerOne domain.

Single Sign-On URL

The URL from your SAML provider to initiate a single sign-on attempt, sometimes called the login URL.

X509 Certificate

The certificate from your SAML provider to verify the single sign-on response.

Require new users to use SAML

Check this box if new users with emails matching the verified domain are required to sign up with SAML.

Step 2 - Test

  1. Click Start Test in the Test settings section of the SAML Configuration page.

  2. Click Start test now.

  3. Enter your login credentials in the test window. After your login attempt, the test will either succeed or fail and provide warning messages about your test login. If your test fails, run another test by going back to the previous step.

Step 3 - Verify & Enable

  1. Click Verify settings. Once you verify your settings, you won't be able to change your settings or run tests on the domain anymore.

  2. Click Enable SAML once you're ready to migrate user accounts to SAML authentication.

  3. Select the initial set of users you want to migrate to SAML in the Enable SAML modal that pops up. You can choose from all users matching the configured domain(s), or only the users belonging to your organization matching the configured domain(s).

  4. Click Enable and migrate.

Once you've successfully enabled SAML, all users who are part of the domain will be required to authenticate using SAML. The passwords associated with those accounts will be removed. Users will receive instructions on their first log-in informing them of the change.

Additional Information

Here are some screenshots that provide additional details on Service Provider and Attribute mapping:

Configure an Alternative Certificate

If you need to switch your identity provider or if your current SAML certificate is expiring, you can configure an alternative SAML certificate to avoid having to disable your SSO integration during the update.

Note: Only an organization administrator has the ability to configure the alternative certificate.

To configure an alternative certificate:

  1. Go to Organization Settings > Authentication > SAML (SSO).

  2. Click View SAML provider from the context menu.

  3. Click configure next to X509 ALTERNATIVE CERTIFICATE

  4. Enter the alternative certificate in the Configure alternative certificate window.

  5. Click Save.

After the alternative certificate has been configured, users will be able to authenticate through the new SAML certificate.

When the primary certificate isn't used anymore, you can promote the alternative certificate to the primary by clicking Promote alternative certificate to primary certificate. This will enable your primary certificate to be replaced with the alternative.

Changing Identity Providers

If you need to change your identity provider at any time, to provide a more seamless self-service configuration, you can follow these steps:

To start, copy this information from your prior identity provider configuration:

Field

Details

Domain

The domain for users that was required to use SAML authentication.

Single Sign-On URL

The URL from your SAML provider to initiate a single sign-on attempt, sometimes called the login URL.

X509 Certificate

The certificate from your SAML provider to verify the single sign-on response.

  1. Preconfigure your new identity provider on your provider's site with information from HackerOne. Depending on your provider, you may need HackerOne's metadata endpoint and ACS URL. You can find that along with other helpful information here.

    • If you're using Google, Okta, or OneLogin, you can use the resources on our docs site for configuring those identity providers (more links are at the top of this page).

  2. Go to Organization Settings > Authentication > SAML (SSO) in HackerOne.

  3. Click View SAML provider from the context menu.

    1. Note: Steps 3-6 will make your SAML authentications temporarily unavailable. Be sure to communicate this to your program members as needed.

  4. Click on Disable SAML provider

  5. Uncheck the check box for Notify existing users and send password reset instructions.

  6. Click on Disable SAML provider

  7. Re-configure your SAML configuration with the new identity provider information by following the steps here.

  8. Make sure the checkbox for Notify existing users about the new login process using SAML is unchecked when the Enable SAML window pops up.

  9. Click Enable and migrate.

If at any time testing doesn't work or you encounter issues, revert to the recorded information for the prior identity provider.

Did this answer your question?