From 03feae9f767af84d689a5dc27e679432399d8280 Mon Sep 17 00:00:00 2001 From: dfunckt Date: Wed, 10 Jul 2024 21:43:05 +0300 Subject: [PATCH] Minor improvements to Enterprise SSO section Change-type: patch --- pages/learn/accounts/enterprise-sso.md | 64 +++++++++++++------ .../idp-setup/google-workspace-saml-setup.md | 31 ++++++--- .../idp-setup/microsoft-entra-saml-setup.md | 23 ++++--- 3 files changed, 79 insertions(+), 39 deletions(-) diff --git a/pages/learn/accounts/enterprise-sso.md b/pages/learn/accounts/enterprise-sso.md index d37a759752..3b1977449c 100644 --- a/pages/learn/accounts/enterprise-sso.md +++ b/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. - -Add Identity Provider form +3. Click on the Add Identity Provider button. In the dialog that appears, either upload the XML file or manually enter the IdP details. + +Screenshot of Add Identity Provider form -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. - -Fully configured IdP with two Orgs associated +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. + +Fully configured IdP with two organizations associated #### (Optional) Configure a Default Team @@ -46,43 +62,48 @@ __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. - -User preferences with enable SSO button highlighted + +User preferences with Enable SSO button highlighted Next, provide the company `SSO Identifier` supplied by your balenaCloud organization administrator. - + Enable SSO modal with SSO identifier filled in. -__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`. + Login page with Enterprise SSO login highlighted. -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, for example, Okta. We have provided examples for [Microsoft Entra ID][ms-saml] (formerly Azure AD) and [Google Workspace][google-saml] 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 +112,7 @@ Currently, SAML authentication users cannot create API keys. If you require API #### 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 +136,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/ \ No newline at end of file +[ms-saml]:/learn/accounts/idp-setup/microsoft-entra-saml-setup/ +[google-saml]:/learn/accounts/idp-setup/google-workspace-saml-setup/ \ No newline at end of file diff --git a/pages/learn/accounts/idp-setup/google-workspace-saml-setup.md b/pages/learn/accounts/idp-setup/google-workspace-saml-setup.md index 2de1abde67..cbed65de15 100644 --- a/pages/learn/accounts/idp-setup/google-workspace-saml-setup.md +++ b/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: Download XML ## Conclusion diff --git a/pages/learn/accounts/idp-setup/microsoft-entra-saml-setup.md b/pages/learn/accounts/idp-setup/microsoft-entra-saml-setup.md index 58f87e95d1..2865a9de1a 100644 --- a/pages/learn/accounts/idp-setup/microsoft-entra-saml-setup.md +++ b/pages/learn/accounts/idp-setup/microsoft-entra-saml-setup.md @@ -1,42 +1,46 @@ --- -title: Configure a SAML app for Microsoft Entra ID +title: 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. +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. At the end of this guide, you can start using Single Sign-On functionality from your IdP in balenaCloud. + +## Create a New Enterprise Application -#### 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. + Create new enterprise app in Microsoft entra ID -#### Create Your Own Application +## 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`. + Create a custom app -#### Configure Single Sign-On +## Configure Single Sign-On 1. In the left menu, click Single sign-on. 2. Select SAML. + Configure SSO -#### Basic SAML Configuration +## 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. - -Configure SSO + +cConfigure SSO #### Set Unique User Identifier @@ -44,6 +48,7 @@ This section provides step-by-step instructions for setting up SAML 2.0 with Mic 2. On the Unique User Identifier row, click it. 3. Change the Source attribute field to `user.mail`. 4. Click Save. + Edit Unique User Identifier row Change source attribute @@ -52,12 +57,14 @@ This section provides step-by-step instructions for setting up SAML 2.0 with Mic 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. + Assign Users or Groups #### 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). + Download XML 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.