Merge pull request #3675 from replicatedhq/sc-129903_saml-docs

SAML Authentication for Enterprise Portal

Author: marcw-replicated

docs/vendor/enterprise-portal-invite.mdx

@@ -42,6 +42,26 @@ To configure allowed domains for a customer's Enterprise Portal invitations:
 
 1. In the text box, enter a domain to add to the allowlist. Click **Add domain**. Add more domains as needed.
 
+## Enable SAML Authentication (Alpha) {#enable-saml}
+
+:::note
+SAML Authentication to the Enterprise Portal is Alpha and subject to change. To access this feature, a feature flag must be enabled for your team. For more information, reach out to your Replicated account representative.
+:::
+
+You can enable and disable SAML authentication for the Enterprise Portal on a per customer basis. When SAML authentication is enabled, the customer can set up SAML SSO logins for the Enterprise Portal using their identity provider (IdP). When SAML authentication is disabled, Enterprise Portal users are not able  to log in using SAML, even if the customer had already configured SAML for their Enterprise Portal previously. For more information, see [About SAML Logins (Alpha)](enterprise-portal-use#about-saml) in _Log In and Use the Enterprise Portal_.
+
+To enable SAML authentication:
+
+1. In the Vendor Portal, go to **Customers** and select the target customer.
+
+1. On the customer's page, go to **Enterprise Portal access**. In the **Authentication** section, enable the **SAML Authentication** toggle.
+
+   ![Enterprise Portal SAML authentication](/images/enterprise-portal-saml-authentication.png)
+
+   [View a larger version of this image](/images/enterprise-portal-saml-authentication.png)
+
+   After you enable SAML authentication, the customer can configure SAML in the Enterprise Portal using their IdP. For more information, see [Configure SAML Authentication (Alpha)](/vendor/enterprise-portal-use#saml) in _Log In and Use the Enterprise Portal_.
+
 ## Invite Users
 
 This section describes how to invite users to the Enterprise Portal from the Vendor Portal. Your customers can also invite users to the Enterprise Portal from the Enterprise Portal **Team settings** page. For more information about using the **Team settings** page, see [Manage Users](enterprise-portal-use#manage-users) in _Access and Use the Enterprise Portal_.

docs/vendor/enterprise-portal-use.mdx

@@ -6,7 +6,11 @@ For information about how to access the Enterprise Portal for a customer from th
 
 ## Log In To the Enterprise Portal
 
-### Log in From the Invitation Email
+:::note
+If SAML authentication has been enabled and configured for the Enterprise Portal it will be the preferred login method and attempted automatically. See [Configure SAML Authentication (Alpha)](#saml) below.
+:::
+
+### Log In From the Invitation Email
 
 Users can log in to the Enterprise Portal after they are invited to join a team. See [Invite or Delete Users](#invite-or-delete-users) below.
 
@@ -40,7 +44,21 @@ To sign up for a self-service account and log in to the Enteprise Portal:
 
     [View a larger version of this image](/images/self-serve-signup-screen.png)
 
-1. Go to your email account and open the automated account creation email. Follow the link provided in the email to log in.    
+1. Go to your email account and open the automated account creation email. Follow the link provided in the email to log in.
+
+### About SAML Logins (Alpha) {#about-saml}
+
+:::note
+SAML Authentication to the Enterprise Portal is Alpha and subject to change. To access this feature, a feature flag must be enabled for your team. For more information, reach out to your Replicated account representative.
+:::
+
+When SAML authentication is enabled and configured for your Enterprise Portal team, you can log in with your single sign-on (SSO) credentials either through your SAML Identity Provider (IdP) or the Enterprise Portal. For more information about how to configure SAML, see [Configure SAML Authentication (Alpha)](#saml) below.
+
+#### Just-In-Time User Provisioning
+
+The first time that you attempt to log in with SAML using your SSO credentials, if you do not already have an Enterprise Portal account, then your account is automatically created using just-in-time (JIT) user provisioning. JIT is handled differently depending on if you attempt to log in through your IdP or the Enterprise Portal:
+* IdP-initiated SAML login attempts always allow for JIT user provisioning
+* Enterprise Portal-initiated SAML login attempts allow for JIT user provisioning if your email address has already been invited to the team. See [Invite or Delete Users](#invite-or-delete-users) below.
 
 ## View Install and Update Instructions
 
@@ -197,7 +215,7 @@ To manage licenses in the Enterprise Portal:
 
 ## Manage Team Settings
 
-This section includes information about how to manage users and service accounts in the Enterprise Portal.
+This section includes information about how to manage users, service accounts, and SAML authentication in the Enterprise Portal.
 
 ### Invite or Delete Users
 
@@ -221,7 +239,7 @@ To manage invite and manage users in the Enterprise Portal:
 
 To manage service accounts in the Enterprise Portal:
 
-1. In the Enterprise Portal, openthe user account dropdown in the top right of the page and select **Team settings**.
+1. In the Enterprise Portal, open the user account dropdown in the top right of the page and select **Team settings**.
 
    ![enterprise portal team settings](/images/enterprise-portal-user-account.png)
 
@@ -234,6 +252,48 @@ To manage service accounts in the Enterprise Portal:
    * To view a service account token, find the target service account in the table and click **View** under **Token**.
    * The revoke a service account's token, find the target service account in the table and open the menu under **Actions**. Select **Revoke**.
 
+### Configure SAML Authentication (Alpha) {#saml}
+
+:::note
+SAML Authentication to the Enterprise Portal is Alpha and subject to change. To access this feature, a feature flag must be enabled for your team. For more information, reach out to your Replicated account representative.
+:::
+
+:::note
+SAML authentication must be enabled for the customer in the Vendor Portal before they can configure SAML for their Enterprise Portal team. For more information, see [Enable SAML Authentication (Alpha)](enterprise-portal-invite#enable-saml).
+:::
+
+To configure SAML authentication for your account:
+
+1. In the Enterprise Portal, open the user account dropdown in the top right of the page and select **Team settings**.
+
+   ![enterprise portal team settings](/images/enterprise-portal-user-account.png)
+   
+   [View a larger version of this image](/images/enterprise-portal-user-account.png)
+
+1. Click **SAML Authentication**.
+
+1. For **Service provider information**, copy the values provided and use them to configure your identity provider (IdP).
+
+   ![enterprise portal SAML service provider information](/images/enterprise-portal-saml-sp-info.png)
+   
+   [View a larger version of this image](/images/enterprise-portal-saml-sp-info.png)
+
+1. Upload the required metadata XML and public certificate from your IdP.
+
+   ![enterprise portal SAML configuration](/images/enterprise-portal-saml-config.png)
+   
+   [View a larger version of this image](/images/enterprise-portal-saml-config.png)
+
+1. After the file upload is complete, the **Enable SAML authentication** toggle is automatically enabled.
+
+   ![enterprise portal SAML enablement](/images/enterprise-portal-saml-enable.png)
+   
+   [View a larger version of this image](/images/enterprise-portal-saml-enable.png)
+
+   :::note
+   If you disable SAML authentication, the SAML configuration details that you added to the Enterprise Portal are saved.
+   ::: 
+
 ## Manage User Settings
 
 Each user can manage their settings in the Enterprise Portal, including enabling and disabling email notifications for various system events.