Merge pull request #1175 from Hacker0x01/update-sso-documentation

Updated SAML/SSO documentation
Hacker0x01 · Sep 28, 2023 · 65c452f · 65c452f
2 parents cfb49a2 + 87053e5
commit 65c452f
Show file tree

Hide file tree

Showing 28 changed files with 83 additions and 87 deletions.
diff --git a/docs/organizations/images/saml-daisy-1.png b/docs/organizations/images/saml-daisy-1.png
diff --git a/docs/organizations/images/saml-daisy-2.png b/docs/organizations/images/saml-daisy-2.png
diff --git a/docs/organizations/images/saml-daisy-3.png b/docs/organizations/images/saml-daisy-3.png
diff --git a/docs/organizations/images/saml-daisy-4.png b/docs/organizations/images/saml-daisy-4.png
diff --git a/docs/organizations/images/saml-daisy-verify-settings.png b/docs/organizations/images/saml-daisy-verify-settings.png
diff --git a/docs/organizations/images/saml-disable-modal.png b/docs/organizations/images/saml-disable-modal.png
diff --git a/docs/organizations/images/saml-enable-modal.png b/docs/organizations/images/saml-enable-modal.png
diff --git a/docs/organizations/images/saml-sso-setup-1.png b/docs/organizations/images/saml-sso-setup-1.png
diff --git a/docs/organizations/images/saml-sso-setup-10.png b/docs/organizations/images/saml-sso-setup-10.png
diff --git a/docs/organizations/images/saml-sso-setup-11.png b/docs/organizations/images/saml-sso-setup-11.png
diff --git a/docs/organizations/images/saml-sso-setup-12.png b/docs/organizations/images/saml-sso-setup-12.png
diff --git a/docs/organizations/images/saml-sso-setup-13.png b/docs/organizations/images/saml-sso-setup-13.png
diff --git a/docs/organizations/images/saml-sso-setup-2.png b/docs/organizations/images/saml-sso-setup-2.png
diff --git a/docs/organizations/images/saml-sso-setup-3.png b/docs/organizations/images/saml-sso-setup-3.png
diff --git a/docs/organizations/images/saml-sso-setup-4.png b/docs/organizations/images/saml-sso-setup-4.png
diff --git a/docs/organizations/images/saml-sso-setup-5.png b/docs/organizations/images/saml-sso-setup-5.png
diff --git a/docs/organizations/images/saml-sso-setup-6.png b/docs/organizations/images/saml-sso-setup-6.png
diff --git a/docs/organizations/images/saml-sso-setup-7.png b/docs/organizations/images/saml-sso-setup-7.png
diff --git a/docs/organizations/images/saml-sso-setup-8.png b/docs/organizations/images/saml-sso-setup-8.png
diff --git a/docs/organizations/images/saml-sso-setup-9.png b/docs/organizations/images/saml-sso-setup-9.png
diff --git a/docs/organizations/images/saml-start-test.png b/docs/organizations/images/saml-start-test.png
diff --git a/docs/organizations/images/verified-domains-1.png b/docs/organizations/images/verified-domains-1.png
diff --git a/docs/organizations/images/verified-domains-4.png b/docs/organizations/images/verified-domains-4.png
diff --git a/docs/organizations/images/verified-domains-5.png b/docs/organizations/images/verified-domains-5.png
diff --git a/docs/organizations/single-sign-on-sso-via-saml.md b/docs/organizations/single-sign-on-sso-via-saml.md
@@ -21,112 +21,121 @@ HackerOne supports Single Sign-On (SSO) through Security Assertion Markup Langua
 ### Set Up
 
 To configure Single Sign-On via SAML:
-1. Go to **Program Settings > General > Authentication**.
+1. Go to **Organization Settings > Authentication > SAML (SSO)**.
 
-><i>Note: You must have User Management permissions to setup SAML.</i>
+><i>Note: You must be an organization administrator to setup SAML.</i>
 
-2. Click **Setup SAML** in the *Single Sign-on with SAML* section.
+2. Click **Add SAML Provider**.
 
-![saml setup](./images/saml-daisy-1.png)
+![saml setup_1](./images/saml-sso-setup-1.png)
 
-3. Click **Enter Configuration** on the *SAML Configuration* page.
-
-![Image?](./images/saml-daisy-2.png)
-
-4. Enter information for these fields:
+3. Enter information for these fields:
 
 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](domain-verification.html) 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 | Chheck this box if new users with emails matching the verified domain are required to sign up with SAML.
 
-![setup SAML Configuration modal](./images/saml-daisy-3.png)
+![SAML setup 2](./images/saml-sso-setup-2.png)
 
-5. Click **Save**.
-6. Click **Start Test** in the *Test it* section of the SAML Configuration page.
+4. Click **Save**.
+5. Click **Start Test** in the *Test settings* section of the SAML Configuration page.
+
+![SAML setup 3](./images/saml-sso-setup-3.png)
+
+6. Click **Start test now**.
+
+![SAML setup 4](./images/saml-sso-setup-4.png)
 
-![Start Test button](./images/saml-daisy-4.png)
+7. Enter your login credentials to 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 step 5 above.
+8. Click **Verify settings**. Once you verify your settings, you won't be able to change your settings or run tests on the domain anymore.
 
-7. Click **Run test** in the *SAML Settings Test* modal that pops up.
-8. Click **Start test now**.
+![SAML setup 5](./images/saml-sso-setup-5.png)
 
-![SAML start test](./images/saml-start-test.png)
+9. Click **Enable SAML** once you're ready to migrate user accounts to SAML authentication.
 
-9. Enter your login credentials to 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 step 6 above.
-10. Click **Verify Settings**.  
+![SAML setup 6](./images/saml-sso-setup-6.png)
 
-![Verify Settings](./images/saml-daisy-verify-settings.png)
+10. 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 belong to your organization matching the configured domain(s). 
 
-11. Click **Verify** in the *Verify SAML Settings* modal. Once you verify your settings, you won't be able to change your settings or run tests on the domain anymore.
+11. Click **Enable and migrate**.
 
-12. Click **Enable SAML** once you're ready to migrate all user accounts to SAML authentication.
-13. Click **Enable** in the *Enable SAML* modal that pops up.
+![SAML setup 7](./images/saml-sso-setup-7.png)
 
 Once you've successfully enabled SAML, all users that 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:
 
-![saml1](./images/saml-1.png)
+![SAML setup 8](./images/saml-1.png)
 
-![saml_2](./images/saml-2.png)
+![SAML setup 9](./images/saml-2.png)
 
 ### 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 the admin of the program has the ability to configure the alternative certificate.
+> **Note:** Only an organization administrator has the ability to configure the alternative certificate.
 
 To configure an alternative certificate:
 
-1. Go to **Program Settings > General > Authentication**.
-2. Click **configure** next to **X509 alternative certificate**.
+1. Go to **Organization Settings > Authentication > SAML (SSO)**.
+2. Click **View SAML provider** from the context menu.
 
-![Authentication settings page with SAML configured](./images/alt-certificate-1.png)
+![SAML setup 10](./images/saml-sso-setup-8.png)
 
-3. Enter the alternative certificate in the **Configure alternative certificate** window.
+3. Click **configure** next to *X509 ALTERNATIVE CERTIFICATE* 
 
-![configure alternative certificate modal ](./images/alt-certificate-2.png)
+![SAML setup 11](./images/saml-sso-setup-9.png)
 
-4. Click **Save**.
+4. Enter the alternative certificate in the **Configure alternative certificate** window.
+
+![SAML setup 12](./images/saml-sso-setup-10.png)
+
+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.
 
-![authentication settings page with alt certificate configured](./images/alt-certificate-3.png)
+![SAML setup 13](./images/saml-sso-setup-11.png)
 
 ### 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:
 
- 1. Copy this information from your prior identity provider configuration:
+1. 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.
 
- 2. 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](sso-faqs.html).
+2. 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](sso-faqs.html).
      * If you're using [Google](google-sso-saml-setup.html), [Okta](okta-sso-saml-setup.html), or [OneLogin](onelogin-sso-saml-setup.html), you can use the resources on our docs site for configuring those identity providers (more links are at the top of this page).
 
-3. Go to **Program Settings > General > Authentication** in HackerOne.
+3. Go to **Organization Settings > Authentication > SAML (SSO)** in HackerOne.
+4. Click **View SAML provider** from the context menu.
 
-> **Note:** Steps 4 - 7 will make your SAML authentications temporarily unavailable. Be sure to communicate this to your program members as needed.
+![SAML setup 14](./images/saml-sso-setup-8.png)
 
- 4. Disable your current configuration by clicking **Yes, disable SAML**.
+> **Note:** Steps 4 - 7 will make your SAML authentications temporarily unavailable. Be sure to communicate this to your program members as needed.
 
- 5. Uncheck the check box for **Send password reset emails to affected users**.
+5. Click on **Disable SAML provider**
+6. Uncheck the check box for **Notify existing users and send password reset instructions**.
+7. Click on **Disable SAML provider**
 
-![SAML Disable modal](./images/saml-disable-modal.png)
+![SAML setup 15](./images/saml-sso-setup-12.png)
 
- 6. Re-configure your SAML configuration with the new identity provider information by following steps 1-12 [here](single-sign-on-sso-via-saml.html#set-up).
+8. Re-configure your SAML configuration with the new identity provider information by following steps 1-12 [here](single-sign-on-sso-via-saml.html#set-up).
 
- 7. Make sure the checkbox for **Notify existing users that SAML is enabled** is unchecked when the **Enable SAML** window pops up.
+9. Make sure the checkbox for **Notify existing users about the new log in process using SAML** is unchecked when the **Enable SAML** window pops up.
 
- 8. Click **Enable**.
+10. Click **Enable and migrate**.
 
-![SAML Enable modal](./images/saml-enable-modal.png)
+![SAML setup 16](./images/saml-sso-setup-13.png)
 
  If at anytime testing doesn't work or you encounter issues, revert to the recorded information for the prior identity provider.
diff --git a/docs/organizations/sso-jit.md b/docs/organizations/sso-jit.md
@@ -4,7 +4,7 @@ path: "/organizations/sso-jit.html"
 id: "organizations/sso-jit"
 ---
 
-HackerOne offers Just-in-time (JIT) provisioning with [SSO via SAML](single-sign-on-sso-via-saml.html) with System for Cross-domain Identity Management(SCIM). JIT provisioning enables you to automatically create user accounts by using the information from the SAML protocol.
+HackerOne offers Just-in-time (JIT) provisioning with [SSO via SAML](single-sign-on-sso-via-saml.html). JIT provisioning enables you to automatically create user accounts by using the information from the SAML protocol.
 
 When SSO via SAML has been set up, each time a new user from your organization logs in to HackerOne, their account will automatically be created. There are 2 types of provisioning that are associated in the creation of each account: Attribute Provisioning and Program Membership.
 
@@ -22,23 +22,5 @@ Option Type | Details
 ----------- | -------
 None | You can invite users to your program and manage their membership and permission level within the user management interface.
 Basic | Enables any user attached to your SAML configuration to join the program automatically without an invitation at login. This works for multiple programs if your SAML settings are attached to all programs. <br><br>To configure this provisioning, contact support@hackerone.com after your SAML configuration is enabled and HackerOne will turn it on for you.
-Advanced | *Only for Enterprise programs* <br><br>Enables organizations to control membership and permission level from their SSO provider. When configured, the attributes for the users membership and group will be used to assign the user to your program and the appropriate group in HackerOne with the associated permissions. You can confirm the memberships are being added properly by viewing your program [audit log](audit-logs.html).<br><br>To configure this provisioning, HackerOne needs to establish a mapping between the SSO provider (your system) and the HackerOne system. HackerOne does this by utilizing the attribute statements on the SSO provider side, which you will point to groups defined in your HackerOne program. <br><br>The assertion should provide an attribute with the following name: `Program.<handle>.groups` and the value should be a semi-colon delimited list of the program Group names the user should belong to. If no groups are specified the user will not be added to the program. <br><br> Take, for example, this set of configured Groups in HackerOne:<br><br> ![sso-okta](./images/sso-jit-groups-example.png) <br><br>A correlating SSO configuration (for Okta) would look like this: <br><br>![sso-okta](./images/sso-jit-okta-example.png)
+Advanced | *Only for Enterprise programs* <br><br>Enables organizations to control membership and permission level from their SSO provider. When configured, the attributes for the users membership and group will be used to assign the user to your program and the appropriate group in HackerOne with the associated permissions. You can confirm the memberships are being added properly by viewing your program [audit log](audit-logs.html).<br><br>To configure this provisioning, contact support@hackerone.com after your SAML configuration is enabled, and HackerOne will assist in the setup.
 
-The assertion can confirm the mapping between the SSO provider and HackerOne is done correctly by inspecting the assertion statement in the SAML Response:
-
-```
-<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
-   <saml2:Attribute Name="user.firstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
-     <saml2:AttributeValue xmlns:xs="<snip>" xsi:type="xs:string">Ben</saml2:AttributeValue>
-   </saml2:Attribute>
-   <saml2:Attribute Name="User.lastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
-     <saml2:AttributeValue xmlns:xs="<snip>" xmlns:xsi="<snip>" xsi:type="xs:string">Willis</saml2:AttributeValue>
-   </saml2:Attribute>
-   <saml2:Attribute Name="Program.security.groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
-     <saml2:AttributeValue xmlns:xs="<snip>" xmlns:xsi="<snip>" xsi:type="xs:string">Admin;Standard</saml2:AttributeValue>
-   </saml2:Attribute>
-   <saml2:Attribute Name="Program.hackerone_program_2.groups" NameFormat="<snip>">
-     <saml2:AttributeValue xmlns:xs="<snip>" xmlns:xsi="<snip>" xsi:type="xs:string">Standard</saml2:AttributeValue>
-   </saml2:Attribute>
- </saml2:AttributeStatement>
- ```
diff --git a/docs/organizations/verified-domains.md b/docs/organizations/verified-domains.md
@@ -7,31 +7,36 @@ id: "organizations/domain-verification"
 In order to configure [single sign-on via SAML](single-sign-on-sso-via-saml.html), you need to verify ownership of the domain for your program.
 
 To verify your domain:
-1. Go to **Program Settings > General > Verified Domains**.
+1. Go to **Organization Settings > Authentication > Verified Domains**.
 
-![verified domains](./images/verified-domains-1.png)
+><i>Note: You must be an organization administrator to add a verified domain.</i>
 
-2. Click **Verify new domain**.
-3. Choose the **Verification Method** of your domain. You can choose from:
+![verified domains1](./images/verified-domains-1.png)
+
+2. Click **Add verified domain**.
+3. Enter the domain name you want to verify in the **Domain name** field.
+4. Choose the **Verification Method** of your domain. You can choose from:
 
 Option | Details
 ------ | -------
 DNS TXT record | You'll be prompted to add a TXT record to the DNS configuration of your domain to allow HackerOne to verify you have ownership over the domain.
 HTML meta-tag | You'll be prompted to add an HTML meta-tag to the index page of your domain to allow HackerOne to verify you have ownership over the domain.
 Web file | You'll be prompted to upload a text file to allow HackerOne to verify if you have ownership over the domain.
 
-4. Enter the domain name you want to verify in the **Domain name** field.
-5. Click **Next step**.
-6. Follow the instructions on the page to allow HackerOne to verify you have ownership over the domain. Instructions will vary depending on the verification method you chose in step 3 above. You'll have to go to your DNS provider to manage settings on the domain.
+5. Click **Add domain**.
+
+![verified domains2](./images/verified-domains-5.png)
+
+6. Follow the instructions on the page to allow HackerOne to verify you have ownership over the domain. Instructions will vary depending on the verification method you chose in step 4 above. You'll have to go to your DNS provider to manage settings on the domain.
 
 Here's an example of using the DNS TXT record on Cloudflare to allow HackerOne to verify your domain:
 
 ![domain verification example of using DNS TXT](./images/verified-domains-3.png)
 
 7. Click **Verify**
 
-Once your domain is successfully verified, the status of your domain will be changed to *Verified*. You can continue to verify your [SAML settings](single-sign-on-sso-via-saml.html).
+Once your domain is successfully verified, the status of your domain will be changed to *Verified*. You can continue to set up your [SAML settings](single-sign-on-sso-via-saml.html).
 
 ![verified domains list](./images/verified-domains-4.png)
 
-If your verification has failed, you can choose to **Cancel verification**
+If your verification has failed, you can choose to **Cancel verification**.
diff --git a/src/pages/organizations/organizations-nav.yaml b/src/pages/organizations/organizations-nav.yaml
@@ -56,6 +56,21 @@
         path: /organizations/asset-types.html
       - title: External Attack Surface Management Solution
         path: /organizations/external-asm.html
+    - title: Single Sign-On via SAML
+      path: /organizations/single-sign-on-sso-via-saml.html
+      items:
+        - title: JIT Provisioning
+          path: /organizations/sso-jit.html
+        - title: Domain Verification
+          path: /organizations/domain-verification.html
+        - title: Google
+          path: /organizations/google-sso-saml-setup.html
+        - title: Okta
+          path: /organizations/okta-sso-saml-setup.html
+        - title: OneLogin
+          path: /organizations/onelogin-sso-saml-setup.html
+        - title: FAQs
+          path: /organizations/sso-faqs.html
 - title: Your Program
   items:
     - title: General Settings
@@ -131,21 +146,6 @@
       items:
         - title: Signal Requirements
           path: /organizations/signal-requirements.html
-    - title: Single Sign-On via SAML
-      path: /organizations/single-sign-on-sso-via-saml.html
-      items:
-        - title: JIT Provisioning
-          path: /organizations/sso-jit.html
-        - title: Domain Verification
-          path: /organizations/domain-verification.html
-        - title: Google
-          path: /organizations/google-sso-saml-setup.html
-        - title: Okta
-          path: /organizations/okta-sso-saml-setup.html
-        - title: OneLogin
-          path: /organizations/onelogin-sso-saml-setup.html
-        - title: FAQs
-          path: /organizations/sso-faqs.html
     - title: Two-Factor Authentication
       path: /organizations/two-factor-authentication.html
       items: