Enterprise SSO (SAML) documentation #3019
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
otaviojacobi
reviewed
Jul 3, 2024
otaviojacobi
reviewed
Jul 3, 2024
shaunmulligan
force-pushed
the
enterprise-sso
branch
from
454a15d
to
844dbfd
Compare
|
|
||
| ### 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 "Merge Account". |
There was a problem hiding this comment.
Suggested change
| 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 "Merge Account". | |
| To log in using your enterprise SAML authentication, you must first have an existing balenaCloud account using your company email address. If you don't have an account, you can [create a new balenaCloud account](https://dashboard.balena-cloud.com/signup). Once logged in, navigate to [user preferences](https://dashboard.balena-cloud.com/preferences/details) from the top right profile icon in the dashboard header and click "Merge Account". |
| * 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 "Merge account" button, you agree to the above terms. If you have any questions or concerns, please contact our support team before completing the transfer. |
There was a problem hiding this comment.
Suggested change
| By clicking the "Merge account" 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 "Merge account" button, you agree to the above terms. For any queries or questions, contact our [support team](https://balena.io/support) before completing the transfer. |
|
|
||
| <!-- NOTE: we link to this FAQ in the dashboard --> | ||
| #### How do I delete a SAML account? | ||
| To delete a SAML account, you must use the `sdk`. This is only necessary if you are looking to [delete your Idp](#how-do-i-delete-an-identity-provider-in-balenacloud). Removing the user from your IdP will block their balenaCloud access. If you really want to delete your SAML users, execute the following command: |
There was a problem hiding this comment.
Only admins would be able to run this and actually delete. Better to mention that.
Suggested change
| To delete a SAML account, you must use the `sdk`. This is only necessary if you are looking to [delete your Idp](#how-do-i-delete-an-identity-provider-in-balenacloud). Removing the user from your IdP will block their balenaCloud access. If you really want to delete your SAML users, execute the following command: | |
| To delete a SAML account, you must use the [balenaSDK](https://docs.balena.io/reference/sdk/node-sdk/). This is only necessary if you are looking to [delete your Idp](#how-do-i-delete-an-identity-provider-in-balenacloud). Removing the user from your IdP will block their balenaCloud access. If you really want to delete your SAML users, execute the following command: |
|
We also probably want to update the guides screenshots on google/microsoft to show a balena-cloud.com url rather balena-staging.com |
shaunmulligan
changed the title
| <!-- 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. The following changes will occur: |
There was a problem hiding this comment.
We should probably add a comment mentioning that this is non (at least trivially) roll back, e.g. once a user becomes saml managed it can't be easily undone (it will require intervention from us)
|
|
||
| <!-- NOTE: we link to this FAQ in the dashboard --> | ||
| #### How do I delete a SAML account? | ||
| To delete a SAML account, you must use the `sdk`. This is only necessary if you are looking to [delete your Idp](#how-do-i-delete-an-identity-provider-in-balenacloud). Removing the user from your IdP will block their balenaCloud access. |
There was a problem hiding this comment.
I think we can maybe put the Removing the user from your IdP will block their balenaCloud access. in bold. and also mention that this blocks users from login in but their current session (that can be up to 12h long) will still remain valid for this 12hours.
|
|
||
| ## 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). This process assumes that you have already configured a [SAML 2.0 IdP and possess an XML certificate][ms-saml] ready for upload. |
There was a problem hiding this comment.
I think we need to make a little bit more clear that we support all SAML 2.0 Identity providers, we just showed the examples of how to do with MS/and google workspace as they are more common but any SAML 2.0 IdP is supported (okta, etc)
Change-type: minor
Co-authored-by: Vipul Gupta <[email protected]>
vipulgupta2048
force-pushed
the
enterprise-sso
branch
from
f40726d
to
c605e0e
Compare
| @@ -0,0 +1,45 @@ | |||
| --- | |||
| title: Configure a SAML app for Google Workspace | |||
There was a problem hiding this comment.
Suggested change
| title: Configure a SAML app for Google Workspace | |
| title: SAML app for Google Workspace |
NIT
| @@ -0,0 +1,45 @@ | |||
| --- | |||
| title: Configure a SAML app for Google Workspace | |||
| excerpt: prepare your Google Workspace organization to integrate with balenaCloud | |||
There was a problem hiding this comment.
Suggested change
| excerpt: prepare your Google Workspace organization to integrate with balenaCloud | |
| excerpt: Configure your Google Workspace organization with balenaCloud to enable SAML |
| excerpt: prepare your Google Workspace organization to integrate with balenaCloud | ||
| --- | ||
|
|
||
| # Google Workspace SAML |
There was a problem hiding this comment.
Suggested change
| # Google Workspace SAML | |
| # Configure a SAML app for Google Workspace |
And since this page is a guide this title suits it better than being in the sidebar
|
|
||
| # Google Workspace SAML | ||
|
|
||
| This guide will walk you through the steps to create a SAML Identity Provider (IdP) using Google Workspace to integrate with balenaCloud. |
There was a problem hiding this comment.
Suggested change
| This guide will walk you through the steps to create a SAML Identity Provider (IdP) using Google Workspace to integrate with balenaCloud. | |
| 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. |
Giving the guide a purpose for folks to know what's the final stage is going to be fulfilling.
|
|
||
| This guide will walk you through the steps to create a SAML Identity Provider (IdP) using Google Workspace to integrate with balenaCloud. | ||
|
|
||
| ##### Prerequisites |
There was a problem hiding this comment.
Suggested change
| ##### Prerequisites | |
| ## Prerequisites |
|
|
||
| ##### Prerequisites | ||
|
|
||
| Access to a Google Workspace admin account capable of creating apps and users for the organization. |
There was a problem hiding this comment.
Suggested change
| Access to a Google Workspace admin account capable of creating apps and users for the organization. | |
| 1. Access to a Google Workspace admin account capable of creating apps and users for the organization. |
Still a list of prereqs
|
|
||
| Access to a Google Workspace admin account capable of creating apps and users for the organization. | ||
|
|
||
| ##### Steps to Create a SAML Identity Provider in Google Workspace |
There was a problem hiding this comment.
Suggested change
| ##### Steps to Create a SAML Identity Provider in Google Workspace | |
| ## Steps |
We already know what we are here for
Comment on lines
40
to
43
|
|
||
| ##### Final Steps | ||
| 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%"> |
There was a problem hiding this comment.
I say make this step 7, better flow so people don't miss out tbh
And add a heading below called Conclusion
NIT
Change-type: patch
Change-type: patch
otaviojacobi
approved these changes
Jul 10, 2024
drskullster
approved these changes
Jul 10, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Draft of SSO/SAML docs, still needs: