Merge pull request #3019 from balena-io/enterprise-sso

Enterprise SSO (SAML) documentation

.cspell/computer-terms.txt

@@ -137,6 +137,7 @@ encodeurl
 endevour
 endianity
 endmacro
+entra
 envinfo
 eoan
 esbuild

config/navigation.txt

@@ -71,6 +71,10 @@ Learn
 
   ACCOUNTS & BILLING
     [/learn/accounts/account]
+    [/learn/accounts/enterprise-sso]
+      Identity Provider Setup
+        [/learn/accounts/idp-setup/microsoft-entra-saml-setup]
+        [/learn/accounts/idp-setup/google-workspace-saml-setup]
     [/learn/accounts/billing]
     [/learn/accounts/fleet-members]
     [/learn/accounts/fleet-types]

pages/learn/accounts/enterprise-sso.md

@@ -0,0 +1,118 @@
+---
+title: Enterprise Single Sign-On
+excerpt: Setup balenaCloud SSO authentication using SAML 2.0
+---
+
+# Enterprise Single Sign-On (SSO)
+
+__Note:__ This feature is currently available only on [Enterprise plans](https://www.balena.io/pricing).
+
+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.
+
+## 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.
+
+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%">
+
+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`
+
+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.
+
+__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%">
+
+#### (Optional) Configure a Default Team
+
+You can configure a default team for each organization to which SAML users will be automatically added upon authentication.
+
+__Note__: If you unlink the default team in the Identity Provider configuration, it will not remove team access for SAML users who have already authenticated. However, new SAML users will no longer be automatically added to this team.
+
+## Authenticating as a SAML User
+
+### 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%">
+
+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:
+* **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:
+* 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.
+
+### 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`.
+<!-- 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.
+
+## 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 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.
+
+#### How can I use API keys if SAML users can't create them?
+Currently, SAML authentication users cannot create API keys. If you require API keys for automated processes, we suggest creating a new non-SAML account to act as a "service" account. We plan to add the ability to create fleet and organization-level API keys as a follow-up feature to address this limitation.
+
+<!-- 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.
+
+__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.
+
+If you really want to delete your SAML users, execute the following command: 
+```JS
+await sdk.pine.delete({
+    resource: 'saml_account',
+    options: {
+        $filter: {
+            remote_id: '<USER_EMAIL_GOES_HERE>'
+        }
+    }
+})
+```
+**Important:** This action is irreversible and the account cannot be recovered once deleted.
+
+#### How do I delete an Identity Provider in balenaCloud?
+An IdP can only be removed once all associated SAML accounts are removed from the organizations connected to the IdP.
+
+#### Why do I get an error when enabling 2FA on my SAML account?
+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/

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

@@ -0,0 +1,46 @@
+---
+title: SAML app for Google Workspace
+excerpt: Configure your Google Workspace organization with balenaCloud to enable SAML
+---
+
+# Configure a SAML app for Google Workspace
+
+This guide will walk you through the steps to create a SAML Identity Provider (IdP) using Google Workspace to integrate with balenaCloud. At the end of this guide, you can start using Single Sign-On functionality from your IdP in balenaCloud.
+
+## Prerequisites
+
+1. Access to a Google Workspace admin account capable of creating apps and users for the organization.
+
+## 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.
+2.	Create a New 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.
+4.	Set Up Service Provider Details
+	* 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:
+    ```
+    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.
+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.
+
+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
+
+Congratulations! You should now have your Identity Provider (IdP) setup, head over to the balenaCloud dashboard and follow the [instructions to link an IdP](/learn/accounts/enterprise-sso/#link-a-saml-identity-provider) by uploading the XML metadata file. Your team can then start using the Single Sign-On (SSO) functionality, allowing them to securely and seamlessly access the platform using their enterprise credentials.

pages/learn/accounts/idp-setup/microsoft-entra-saml-setup.md

@@ -0,0 +1,63 @@
+---
+title: Configure a SAML app for Microsoft Entra ID
+excerpt: prepare your Microsoft Entra ID organization to integrate with balenaCloud
+---
+
+# Microsoft Entra ID (formerly Azure Active Directory)
+
+This section provides step-by-step instructions for setting up SAML 2.0 with Microsoft Entra ID (formerly Azure AD) for use with balenaCloud. Follow the steps below and refer to the accompanying screenshots for visual guidance.
+
+#### Create a New Enterprise Application
+1.	Go to: [Microsoft Entra ID Home](https://entra.microsoft.com/#home).
+2.	On the left hand menu expand `Identity > Applications > Enterprise Applications`.
+4.	Select Enterprise Applications.
+5.	Click the `+ New application` button.
+<img alt="Create new enterprise app in Microsoft entra ID" src="/img/common/saml/microsoft-entra-id/create-new-app.png" width="100%">
+
+#### Create Your Own Application
+
+1.	You should now be presented with a gallery of enterprise apps. Click the `+ Create your own application button` at the top left.
+2.	In the right-hand form that opens, give your app a name.
+3.	Leave the default option selected.
+4.	Click `Create`.
+<img alt="Create a custom app" src="/img/common/saml/microsoft-entra-id/create-your-own-application.png" width="100%">
+
+#### Configure Single Sign-On
+
+1.	In the left menu, click Single sign-on.
+2.	Select SAML.
+<img alt="Configure SSO" src="/img/common/saml/microsoft-entra-id/configure-single-sign-on.png" width="100%">
+
+#### Basic SAML Configuration
+
+1.	In the Basic SAML Configuration section, click `Edit`.
+2.	Paste your Entity ID and Sign-on URL. To obtain this, you must first decide on a “SSO Identifier” for your enterprise, e.g. `acme`.
+* Identifier: https://api.balena-cloud.com/auth/saml/`< sso-identifier >`
+* Reply URL: https://api.balena-cloud.com/auth/saml/`< sso-identifier >`/callback
+3.	Click Save.
+<!-- TODO: update screenshots with production URLS -->
+<img alt="Configure SSO" src="/img/common/saml/microsoft-entra-id/basic-saml-configuration.png" width="100%">
+
+#### Set Unique User Identifier
+
+1.	On the “Set up Single Sign-On with SAML” page, click `Edit` on the Attributes & Claims section.
+2.	On the Unique User Identifier row, click it.
+3.	Change the Source attribute field to `user.mail`.
+4.	Click Save.
+<img alt="Edit Unique User Identifier row" src="/img/common/saml/microsoft-entra-id/unique-user-identifier.png" width="100%">
+<img alt="Change source attribute" src="/img/common/saml/microsoft-entra-id/change-source-attribute.png" width="100%">
+
+#### Assign Users and Groups
+
+1.	Go to Users & Groups in the Manage section of the SAML app.
+2.	Add the users or groups you want to assign access to the SAML app.
+3.	Click Assign at the bottom left.
+<img alt="Assign Users or Groups" src="/img/common/saml/microsoft-entra-id/assign-users-and-groups.png" width="100%">
+
+#### Download Federation Metadata XML
+
+1.	On your SAML-based Sign-on app page, look for the Download link for Federation Metadata XML.
+2.	Download this XML file to use later in [setting up your SAML IdP in balenaCloud](#link-a-saml-identity-provider).
+<img alt="Download XML" src="/img/common/saml/microsoft-entra-id/download-metadata-xml.png" width="100%">
+
+Congratulations! You should now have your Identity Provider (IdP) setup, head over to the balenaCloud dashboard and follow the [instructions to link an IdP](/learn/accounts/enterprise-sso/#link-a-saml-identity-provider) by uploading the XML metadata file. Your team can then start using the Single Sign-On (SSO) functionality, allowing them to securely and seamlessly access the platform using their enterprise credentials.