Minor improvements to Enterprise SSO section

Change-type: patch

pages/learn/accounts/enterprise-sso.md

@@ -9,31 +9,47 @@ __Note:__ This feature is currently available only on [Enterprise plans](https:/
 
 BalenaCloud Enterprise Single Sign-On (SSO) using SAML (Security Assertion Markup Language) allows organizations to manage user access and authentication through their existing Identity Providers (IdP). This integration enables users to use their corporate credentials to log in and access BalenaCloud services. By leveraging SAML, enterprises can simplify the login process, enhance security, streamline user management, and ensure compliance with their internal policies and procedures.
 
-Configuring an Identity Provider (IdP) as a login method requires a one-time setup process within both balenaCloud and the identity provider itself. Refer to our [IdP specific documentation][ms-saml] for detailed instructions on required configurations.
+Configuring an Identity Provider (IdP) as a login method requires a one-time setup process within both balenaCloud and the IdP itself. Refer to our [IdP specific documentation][ms-saml] for detailed instructions on required configurations.
+
+- [Link a SAML Identity Provider](#link-a-saml-identity-provider)
+  - [Associate Organizations and Teams](#associate-organizations-and-teams)
+      - [(Optional) Configure a Default Team](#optional-configure-a-default-team)
+- [Authenticating as a SAML User](#authenticating-as-a-saml-user)
+- [Setting up a new SAML user](#setting-up-a-new-saml-user)
+- [Log in with a SAML account](#log-in-with-a-saml-account)
+- [FAQs](#faqs)
+    - [How do I set up an Identity Provider?](#how-do-i-set-up-an-identity-provider)
+    - [Can I use any identity provider with balena’s Enterprise SSO?](#can-i-use-any-identity-provider-with-balenas-enterprise-sso)
+    - [Can I enforce SAML on all users in my organization?](#can-i-enforce-saml-on-all-users-in-my-organization)
+    - [How can I use API keys if SAML users can't create them?](#how-can-i-use-api-keys-if-saml-users-cant-create-them)
+    - [How do I delete a SAML account?](#how-do-i-delete-a-saml-account)
+    - [How do I delete an Identity Provider in balenaCloud?](#how-do-i-delete-an-identity-provider-in-balenacloud)
+    - [Why do I get an error when enabling 2FA on my SAML account?](#why-do-i-get-an-error-when-enabling-2fa-on-my-saml-account)
+
 
 ## Link a SAML Identity Provider
 
-To enable Single Sign-On (SSO) for balenaCloud organizations, you must establish a connection with your external Identity Provider (IdP). BalenaCloud supports all SAML 2.0 Identity Providers, we have provided examples for Microsoft Entra ID (formerly Azure AD) and Google Workspace. This process assumes that you have already configured a [SAML 2.0 IdP and possess an XML certificate][ms-saml] ready for upload.
+To enable Single Sign-On (SSO) for balenaCloud organizations, you must establish a connection with your external Identity Provider (IdP). BalenaCloud supports all SAML 2.0 Identity Providers, and we provide examples for [Microsoft Entra ID][ms-saml] (formerly Azure AD) and [Google Workspace][google-saml]. This process assumes that you have already configured a [SAML 2.0 IdP and possess an XML certificate][ms-saml] ready for upload.
 
 1. To configure an Identity Provider, you must be logged in as the `Administrator` of an organization subscribed to an [Enterprise plan](https://www.balena.io/pricing).
 2. From the balenaCloud dashboard, select the [Identity Provider](https://dashboard.balena-cloud.com/identity-provider) option from the left sidebar.
-3. Click on the Add Identity Provider button. In the dialog box that opens, either upload the XML file or manually enter the IdP details.
-<!-- TODO: update to latest screenshot -->
-<img alt="Add Identity Provider form" src="/img/common/saml/add-idp-form-filled.png" width="100%">
+3. Click on the Add Identity Provider button. In the dialog that appears, either upload the XML file or manually enter the IdP details.
+
+<img alt="Screenshot of Add Identity Provider form" src="/img/common/saml/add-idp-form-filled.png" width="100%">
 
-To create an Identity Provider (IdP) entity, start by first selecting a unique SSO identifier. This identifier will be part of your team's URL for logging in. For instance, if your organization is `ACME Corp`, you can choose your unique SSO identifier as `acme` with your team's login URL going to be like `https://dashboard.balena-cloud.com/saml/acme`
+To create an Identity Provider entity, start by first selecting a unique SSO identifier. This identifier will be part of your team's URL for logging in. For instance, if your organization is `ACME Corp`, you can choose your unique SSO identifier as `acme` and your team's login URL will be `https://dashboard.balena-cloud.com/saml/acme`.
 
 This identifier must be unique within balenaCloud and can only include lowercase letters (`a-z`), numbers (`0-9`), hyphens (`-`), and underscores (`_`). 
 
 ### Associate Organizations and Teams
 
-BalenaCloud would need a list of organizations to which SAML users will be automatically added upon successful authentication. Only organizations subscribed to an [Enterprise plan](https://www.balena.io/) will appear in the list of available organizations. At least one organization must be provided when setting up the IdP.
+BalenaCloud requires a list of organizations to which SAML users will be automatically added upon successful authentication. Only organizations subscribed to an [Enterprise plan](https://www.balena.io/) will appear in the list of available organizations. At least one organization must be provided when setting up the IdP.
 
 __Note:__ Removing organizations after IdP creation will not revoke access for SAML users who have previously authenticated with this IdP. However, new authentications will no longer include the removed organization. An IdP will always require at least one organization to be associated.
 
-You have successfully configured SAML 2.0 for your balenaCloud Enterprise SSO. Your team can now access the platform securely and seamlessly through the configured Identity Provider. For instructions on how your team can log in, refer to [Authenticating as a SAML/SSO User](#authenticating-as-a-samlsso-user). If you encounter any issues or need further assistance, please contact our support team.
-<!-- TODO: Update to latest screenshot -->
-<img alt="Fully configured IdP with two Orgs associated" src="/img/common/saml/idp-with-two-orgs.png" width="100%">
+You have successfully configured SAML 2.0 for your balenaCloud Enterprise SSO. Your team can now access balenaCloud securely and seamlessly through the configured Identity Provider. For instructions on how your team can log in, refer to [Authenticating as a SAML/SSO User](#authenticating-as-a-samlsso-user). If you encounter any issues or need further assistance, please contact our support team.
+
+<img alt="Fully configured IdP with two organizations associated" src="/img/common/saml/idp-with-two-orgs.png" width="100%">
 
 #### (Optional) Configure a Default Team
 
@@ -46,43 +62,47 @@ __Note__: If you unlink the default team in the Identity Provider configuration,
 ### Setting up a new SAML user
 
 To log in using your enterprise SAML authentication, you must first have or [create](https://dashboard.balena-cloud.com/signup) a standard balenaCloud account using your company email address. Once logged in to this account, navigate to your [user preferences](https://dashboard.balena-cloud.com/preferences/details) and click "Enable" in the "Enterprise SSO" section.
-<!-- TODO: Update to latest screenshot -->
-<img alt="User preferences with enable SSO button highlighted" src="/img/common/saml/merge-account-accept.png" width="100%">
+
+<img alt="User preferences with Enable SSO button highlighted" src="/img/common/saml/merge-account-accept.png" width="100%">
 
 Next, provide the company `SSO Identifier` supplied by your balenaCloud organization administrator.
-<!-- TODO: Update to latest screenshot -->
+
 <img alt="Enable SSO modal with SSO identifier filled in." src="/img/common/saml/add-sso-identifier-merge-modal.png" width="60%">
 
-__Important:__ By activating SAML, you are transferring your personal account to a company account, and this action is non-reversible. The following changes will occur:
+__Important:__ By activating SAML, you are transferring your personal account to a company account. **This action is non-reversible**. The following changes will occur:
 * **Your API keys will be deleted**
-* **This is a non-reversible action**
 * You will no longer be able to create new API keys
 * Ownership of your fleets and devices will be transferred to your company
 * Your company can revoke your access at any time
 * You will no longer be able to log in using `username` and `password`
 
-You will still be subject to balenaCloud's **terms of service** and **master service agreement**, with the following changes:
+You will still be subject to balenaCloud's [**Terms of Service**](https://www.balena.io/terms-of-service) and [**Master Service Agreement**](https://www.balena.io/master-agreement), with the following changes:
+
 * Transfer of Responsibility: The ownership and management of your account will be transferred from you, as an individual user, to the designated company. This means that all rights and obligations under the Terms of Service and the Master Service Agreement will now be governed by the company.
 * Legal Entity: The company will become the legal entity responsible for the account. All contractual obligations, liabilities, and benefits associated with the account will be transferred to the company.
 * Terms and Conditions: The terms and conditions that apply to your account will remain the same. However, the company will now be responsible for ensuring compliance with these terms.
 * Data and Privacy: Your personal data associated with the account will be transferred to the company. The company will be responsible for the protection and use of your data in accordance with the existing privacy policy.
 * Consent: By proceeding with this transfer, you confirm that you have the authority to transfer the account to the company and that you consent to the changes outlined above.
 
-By clicking the "Enable" button, you agree to the above terms. If you have any questions or concerns, please contact our support team before completing the transfer.
+By clicking the Enable button, you agree to the above terms. If you have any questions or concerns, please contact our support team before completing the transfer.
 
 ### Log in with a SAML account
 
-Once you have enabled SAML on your account, you can log in by following the "Enterprise SSO" login button or the login URL provided by your balenaCloud organization administrator, e.g., `https://dashboard.balena-cloud.com/saml/acme`.
+Once you have enabled SAML on your account, you can log in using the Enterprise SSO login button or the login URL provided by your balenaCloud organization administrator, e.g., `https://dashboard.balena-cloud.com/saml/acme`.
+
 <!-- TODO: Update to latest screenshot -->
 <img alt="Login page with Enterprise SSO login highlighted." src="/img/common/saml/login-page.png" width="60%">
 
-Once you have enabled SAML, you can no longer log in using a `password` and should always use the SSO login method.
+Once you have enabled SAML, you can no longer log in using a `username` and `password` combination and you must always use the SSO login method.
 
 ## FAQs
 
 #### How do I set up an Identity Provider?
 Each SAML Identity Provider (IdP) has its own unique implementation and terminology, which can result in variations in the configuration process. While it is not feasible to provide detailed configuration guidelines for every IdP, we have included example guides for two of the major providers: [Microsoft Entra ID (formerly Azure Active Directory)][ms-saml] and [Google Workspace SAML](/learn/accounts/idp-setup/google-workspace-saml-setup/). These examples are designed to help you understand the necessary steps and how to configure your own provider effectively.
 
+#### Can I use any identity provider with balena’s Enterprise SSO?
+We support any identity provider as long as they are compliant with the SAML 2.0 protocol specification such as Okta, [Microsoft Entra ID][ms-saml] (formerly Azure AD) and [Google Workspace][google-saml]. We have provided examples for using Microsoft Entra ID and Google Workspace in our documentation. To setup your IdP, get the Federation Metadata XML as we have setup for Microsoft/Google IdP's and then follow the [instructions to link that IdP](https://docs.balena.io/learn/accounts/enterprise-sso/#link-a-saml-identity-provider) to balenaCloud's SSO.
+
 #### Can I enforce SAML on all users in my organization?
 It is not yet possible to enforce SAML authentication across your entire organization, but this is a feature we plan to add in the near future.
 
@@ -91,7 +111,7 @@ Currently, SAML authentication users cannot create API keys. If you require API
 
 <!-- NOTE: we link to this FAQ in the dashboard -->
 #### How do I delete a SAML account?
-To delete a SAML account, you need to use the `sdk`. This step is only required if you intend to [delete your IdP](#how-do-i-delete-an-identity-provider-in-balenacloud). **Removing the user from your IdP will block their access to balenaCloud**, but their current session will remain active for up to 12 hours after their last login.
+To delete a SAML account, you need to use the [balena SDK](https://docs.balena.io/reference/sdk/node-sdk/). This step is only required if you intend to [delete your IdP](#how-do-i-delete-an-identity-provider-in-balenacloud). **Removing the user from your IdP will block their access to balenaCloud**, but their current session will remain active for up to 12 hours after their last login.
 
 __Warning:__ Ensure that there is at least one non-SAML admin user in your organization before deleting all SAML users in the Identity Providers (IdPs). Failure to do so may result in being locked out of your organization.
 
@@ -115,4 +135,5 @@ An IdP can only be removed once all associated SAML accounts are removed from th
 If you continually get an error when trying to enable 2FA on your SAML user account, it is recommended to log out, re-login, and immediately try to enable 2FA again.
 
 
-[ms-saml]:/learn/accounts/idp-setup/microsoft-entra-saml-setup/
+[ms-saml]:/learn/accounts/idp-setup/microsoft-entra-saml-setup/
+[google-saml]:/learn/accounts/idp-setup/google-workspace-saml-setup/

pages/learn/accounts/idp-setup/google-workspace-saml-setup.md

@@ -14,31 +14,42 @@ This guide will walk you through the steps to create a SAML Identity Provider (I
 ## Steps
 
 1.	Access the Google Admin Console
-	* Go to [Google Admin Console Apps](https://admin.google.com/ac/apps/unified) using your Google Workspace admin account.
+    * Go to [Google Admin Console Apps](https://admin.google.com/ac/apps/unified) using your Google Workspace admin account.
+
 2.	Create a New Custom SAML App
-	* Click on Add app.
-	* Select Add custom SAML app.
+    * Click on Add app.
+    * Select Add custom SAML app.
+
 3.	Configure the SAML App
-	* Name Your App: Provide a meaningful name for the SAML app (e.g., “balenaCloud SSO”).
-	* Download the Metadata: After naming your app, download the metadata file provided by Google. This file will be used later to set up the IdP in balenaCloud.
+    * Name Your App: Provide a meaningful name for the SAML app (e.g., “balenaCloud SSO”).
+    * Download the Metadata: After naming your app, download the metadata file provided by Google. This file will be used later to set up the IdP in balenaCloud.
+
 4.	Set Up Service Provider Details
-	* ACS URL: Fill in the Assertion Consumer Service (ACS) URL with:
+
+    * ACS URL: Fill in the Assertion Consumer Service (ACS) URL with:
+
     ```
     https://dashboard.balena-cloud.com/saml/acme/callback
     ```
+
     Replace `acme` with the name you will give your IdP in balenaCloud.
 
-	* Entity ID: Fill in the Entity ID with:
+    * Entity ID: Fill in the Entity ID with:
+
     ```
     https://dashboard.balena-cloud.com/saml/acme
     ```
+
     Again, replace `acme` with the name you will give your IdP.
+
 5.	Skip Attribute Mapping
-	* Ignore any mapping configuration. Currently, balenaCloud does not make use of these mappings.
+    * Ignore any mapping configuration. Currently, balenaCloud does not make use of these mappings.
+
 6.	Enable the SAML App
-	* In the Service Status section, ensure the new SAML app is set to `ON` for everyone or specific groups. This will those users in your organization access to login to balenaCloud via SSO.
+    * In the Service Status section, ensure the new SAML app is set to `ON` for everyone or specific groups. This will those users in your organization access to login to balenaCloud via SSO.
+
+7. Finally, you should a custom SAML app in your Google Workspace that looks similar to this
 
-7. Finally, you should a custom SAML app in your Google Workspace that looks similar to this:
 <img alt="Download XML" src="/img/common/saml/google-workspace-saml-app-final.png" width="100%">
 
 ## Conclusion