docs: simplify SSO and SAML docs (#669)

* docs: simplify SSO and SAML docs * Update docs/infracost_cloud/sso.md Co-authored-by: Owen <[email protected]> --------- Co-authored-by: Owen <[email protected]>
infracost · Sep 11, 2024 · f90076d · f90076d
1 parent 8db2d90
commit f90076d
Showing 1 changed file with 98 additions and 45 deletions.
diff --git a/docs/infracost_cloud/sso.md b/docs/infracost_cloud/sso.md
@@ -5,14 +5,14 @@ title: Single sign-on (SSO)
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-Infracost Cloud supports authenticating with Enterprise SSO providers.
+Infracost Cloud supports authenticating with Enterprise SSO providers; furthermore, users can automatically be provisioned based on your SAML user groups and permissions.
 
 ## Setup SSO
 
 Assuming you have already purchased Infracost Cloud, you can setup SSO by following these steps. Email [[email protected]](mailto:[email protected]) if you would like to enable SSO for proof-of-concept projects where many people are involved.
 1. Go to [Infracost Cloud](https://dashboard.infracost.io) and sign up with your email and a password. You will delete this user after SSO is enabled.
 2. From the top dropdown menu, switch to your company organization or create a new organization for your company.
-3. Follow the applicable sections below to setup SSO, each option ends with a form where you enter your SSO details.
+3. Follow the applicable sections below to setup SSO, each option ends with you emailing us your SSO details.
     <details>
       <summary>Microsft Entra ID</summary>
       <ol style={{'list-style-type': 'decimal'}}>
@@ -31,11 +31,22 @@ Assuming you have already purchased Infracost Cloud, you can setup SSO by follow
         <li>Click <code>Add identifier</code> and enter <code>urn:auth0:infracost:&lt;YOUR INFRACOST ORG ID&gt;</code></li>
         <li>Click <code>Add reply URL</code> and enter <code>https://login.infracost.io/login/callback?connection=&lt;YOUR INFRACOST ORG ID&gt;</code></li>
         <li>Click <code>Save</code></li>
-        <li>Download 'Certificate (Base64)'. You will need to provide this to Infracost in a future step.</li>
+        <li>Download 'Certificate (Base64)'. You will need to provide this to Infracost.</li>
         <li>Copy the 'Login URL'. You will need to provide this to Infracost in the next step.</li>
-        <li>Fill out the <a href="https://forms.gle/W9Hjm8xBgqQEtnwd7" target="_blank" rel="noopener noreferrer">SSO
-            setup form here</a>, providing the Login URL, certificate and the domains you want
-          enabled for SSO.</li>
+        <li>Email us the following information with the certificate attached:
+          <pre>
+            To: [email protected]<br/>
+            Subject: Enable SSO<br/>
+            Body:<br/><br/>
+            Please enable SSO for our organization.<br/><br/>
+            - Company name or Infracost Org ID: xxx<br/>
+            - SSO provider: Microsoft Entra ID<br/>
+            - Login URL: xxx<br/>
+            - Tenant domains, either the email domain (example.com) or Microsoft tenant domain (example.onmicrosoft.com): xxx<br/>
+            - The certificate is attached.<br/><br/>
+            Thanks!
+          </pre>
+        </li>
       </ol>
     </details>
     <details>
@@ -61,9 +72,20 @@ Assuming you have already purchased Infracost Cloud, you can setup SSO by follow
         <li>In the Sign on tab, scroll down to the SAML Signing Certificates section. On the right-hand side click the
           button to View SAML setup instructions.</li>
         <li>Copy the Identity Provider Single Sign-On URL and download the certificate.</li>
-        <li>Fill out the <a href="https://forms.gle/W9Hjm8xBgqQEtnwd7" target="_blank" rel="noopener noreferrer">SSO
-            setup form here</a>, providing the Identity Provider Single Sign-On URL, certificate and the domain you
-          want enabled for SSO.</li>
+        <li>Email us the following information with the certificate attached:
+          <pre>
+            To: [email protected]<br/>
+            Subject: Enable SSO<br/>
+            Body:<br/><br/>
+            Please enable SSO for our organization.<br/><br/>
+            - Company name or Infracost Org ID: xxx<br/>
+            - SSO provider: Okta<br/>
+            - Identity Provider Single Sign-On URL: xxx<br/>
+            - SSO domains (comma separated list of domains to enable for this SSO connection): xxx<br/>
+            - The public certificate is attached.<br/><br/>
+            Thanks!
+          </pre>
+          </li>
         <li>In the Okta Admin dashboard assign any users to the Infracost Cloud app. You can also add an Infracost
           button to your SSO portal as we support IdP-Initiated logins from Okta too.</li>
       </ol>
@@ -95,8 +117,20 @@ Assuming you have already purchased Infracost Cloud, you can setup SSO by follow
         <li>Add the following Attributes and click Finish:<img loading="lazy"
             src="/docs/img/sso/google-workspace-attributes.png" alt="Google Workspace Service Provider form"
             class="img_ev3q" /></li>
-        <li>Fill out the <a href="https://forms.gle/W9Hjm8xBgqQEtnwd7" target="_blank" rel="noopener noreferrer">SSO
-            setup form here</a>, providing the SSO URL, Certificate and the domain you want enabled for SSO.</li>
+        <li>Email us the following information with the certificate attached:
+          <pre>
+            To: [email protected]<br/>
+            Subject: Enable SSO<br/>
+            Body:<br/><br/>
+            Please enable SSO for our organization.<br/><br/>
+            - Company name or Infracost Org ID: xxx<br/>
+            - SSO provider: Google Workspace<br/>
+            - SSO URL: xxx<br/>
+            - SSO domains (comma separated list of domains to enable for this SSO connection): xxx<br/>
+            - The certificate is attached.<br/><br/>
+            Thanks!
+          </pre>
+        </li>
       </ol>
     </details>
     <details>
@@ -105,48 +139,67 @@ Assuming you have already purchased Infracost Cloud, you can setup SSO by follow
         <li>In the <a href="https://dashboard.infracost.io" target="_blank" rel="noopener noreferrer">Infracost Cloud
             dashboard</a> go to <code>Org Settings</code> and copy your <code>Org ID</code>. You will need to
           provide this in the next step.</li>
-        <li>Fill out the <a href="https://forms.gle/W9Hjm8xBgqQEtnwd7" target="_blank" rel="noopener noreferrer">SSO
-            setup form here</a>, providing the SSO URL, certificate and the domain you want enabled for SSO.</li>
+        <li>Email us the following information with the certificate attached:
+          <pre>
+            To: [email protected]<br/>
+            Subject: Enable SSO<br/>
+            Body:<br/><br/>
+            Please enable SSO for our organization.<br/><br/>
+            - Company name or Infracost Org ID: xxx<br/>
+            - SSO service provider: xxx<br/>
+            - SSO URL: xxx<br/>
+            - SSO domains (comma separated list of domains to enable for this SSO connection): xxx<br/>
+            - The SSO certificate is attached.<br/><br/>
+            Thanks!
+          </pre>
+        </li>
       </ol>
     </details>
-4. Once we receive the form, we will email you to schedule a quick screenshare call to enable SSO. On the call, we will verify your SSO connection is configured correctly and delete the initial user that was created without SSO.
-
-## SAML group mapping
+4. Once we receive your email, we will email you to schedule a quick screenshare call to enable SSO. On the call, we will verify your SSO connection is configured correctly and delete the initial user that was created without SSO.
 
-Infracost Enterprise supports SAML group mapping, which allows you to map SAML groups to Infracost Cloud groups. This allows you to manage access to Infracost Cloud by managing SAML groups in your SAML provider.
+### SSO login notes
 
-To enable this feature you will need to provide the following information:
-1. The full list of group names set up in your SAML provider, and how they should map to Infracost organizations and roles, e.g:
-
-  | SAML group | Infracost organization slug | Infracost role |
-  |------------|-----------------------------|----------------|
-  | InfracostOwner | my-org | Org Owner |
-  | InfracostAdmin | my-org | Org Admin |
-  | InfracostEditor | my-org | Org Editor |
-  | InfracostViewer | my-org | Org Viewer |
+After SSO is configured:
+- SSO is enabled on your company domain name(s), such as acme-inc.com. So anyone who enters an email address that contains your company domain names in the [Infracost log in page](https://dashboard.infracost.io) will be redirected to your SSO provider for authentication.
+- Once SSO is enabled, users logging-in with Github/Google can continue to use those methods until you request us to enable the "Enforce SSO login" option. After that point, SSO will be the only way to login.
+- You can invite users to your Infracost Cloud organization from the Org Settings > Members page. They will also need to be added to the corresponding group in your SSO provider so they can login.
+- If a user had already logged-in prior to SSO being enabled, on their first login after SSO is enabled, they will be asked to confirm if they want to link their login accounts. They must click "Continue" do this to be able to access your company's Infracost Cloud organization, otherwise a new empty organization will be created for them. If they skip this step, email [[email protected]](mailto:[email protected]) so we can assist you.
+    <img src={useBaseUrl("img/infracost-cloud/auth0-account-link.png")} alt="Linking login accounts" width="80%" />
 
-  This supports all the Infracost roles listed in the [roles documentation](/docs/infracost_cloud/key_concepts/#team-management) for specific organizations.
-  Where customers have multiple organizations under an enterprise organization, the SAML groups can be treated as global roles that span all orgs in the enterprise, eg;
+## SAML group mapping
 
-  | SAML Group                | Infracost role    |
-  | ------------------------- | ----------------- |
-  | InfracostEnterpriseOwner  | Enterprise Owner  |
-  | InfracostEnterpriseAdmin  | Enterprise Admin  |
-  | InfracostEnterpriseEditor | Enterprise Editor |
-  | InfracostEnterpriseViewer | Enterprise Viewer |
+Infracost can also **provision users automatically** based on your SAML user groups. This allows you to manage access to Infracost Cloud by managing SAML groups in your SAML provider, instead of inviting users individually to your Infracost Cloud account. With SAML groups, users are automatically provisioned when they sign-in for the first time; their roles are updated every time they sign-in.
 
-  In an enterprise with 10 organizations, if a user is assigned the `InfracostEnterpriseViewer` SAML group, they will be a viewer in all 10 organizations.
+To enable this feature you should:
+1. Follow the above instructions to [Setup SSO](#setup-sso) first.
+2. Create SAML user groups in your SAML provider and put users in those groups. Infracost supports [four roles](/docs/infracost_cloud/key_concepts/#team-management) (Viewer, Editor, Admin, Owner) so we recommend four user groups.
 
-2. The attribute name in the SAML assertion that will contain the group names, for example `memberOf`.
-3. If possible, an example of the SAML assertion that will be sent.
+  If you already have a SAML group that most engineers are part of, you should consider re-using that for the Infracost Viewer role. This enables them to see their repo's pre-existing issues and fix them.
 
-To enable SAML group mapping, please reach out to [[email protected]](mailto:[email protected]).
+  Users that are part of multiple groups will get the highest role from their group. For example, if a user is part of the InfracostViewer and InfracostEditor groups, they'll get the Editor role.
 
-## SSO login notes
+  If you have multiple organizations under an Infracost enterprise, the SAML groups can also be treated as global roles that span all orgs in the enterprise. For example, your engineering user group can be given the Viewer role, and your central FinOps team can be given the Owner role in all organizations that are part of your enterprise.
+3. Email us the following information
 
-After SSO is configured:
-- SSO is enabled on your company domain name(s), such as acme-inc.com. So anyone who enters an email address that contains your company domain names in the [usual log in page](https://dashboard.infracost.io) will be redirected to your SSO provider for authentication.
-- Once SSO is enabled, users logging-in with Github/Google can continue to use those methods until you request us to enable the "Enforce SSO login" option. After that point, SSO will be the only way to login.
-- You can invite users to your Infracost Cloud organization from the Org Settings > Members page. They will also need to be added to the corresponding group in your SSO provider so they can login.
-- If a user had already logged-in prior to SSO being enabled, on their first login after SSO is enabled, they will be asked to confirm if they want to link their login accounts. They must click "Continue" do this to be able to access your company's Infracost Cloud organization, otherwise a new empty organization will be created for them. If they skip this step, email [[email protected]](mailto:[email protected]) so we can assist you.
-    <img src={useBaseUrl("img/infracost-cloud/auth0-account-link.png")} alt="Linking login accounts" width="80%" />
+  <details>
+    <summary>Email template</summary>
+    <pre>
+      To: [email protected]<br/>
+      Subject: Enable SAML groups<br/>
+      Body:<br/><br/>
+      Please enable SAML groups for our organization.<br/><br/>
+      - Company name or Infracost Org ID: xxx<br/><br/>
+      - SSO service provider: [Microsoft Entra ID, Okta, Google Workspace, Other SAML Provider]<br/><br/>
+      - SAML group role mapping:<br/>
+        | SAML group name | Infracost Org slug | Infracost role |<br/>
+        |-----------------|--------------------|----------------|<br/>
+        | AllEngineers    | my_org             | Org Viewer     |<br/>
+        | InfracostEditor | my_org             | Org Editor     |<br/>
+        | InfracostAdmin  | my_org             | Org Admin      |<br/>
+        | InfracostOwner  | all orgs           | Org Owner      |<br/><br/>
+      - The attribute name in the SAML assertion that will contain the group names, for example `memberOf`.<br/><br/>
+      - If possible, an example of the SAML assertion that will be sent.<br/><br/>
+      Thanks!
+    </pre>
+  </details>
+4. Once we receive your email, we will email you to schedule a quick screenshare call to enable the SAML groups. On the call, we will verify that users are automatically provisioned correctly.