docs: azure sso guide #3431
Merged
docs: azure sso guide #3431
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
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
thomasheartman
requested changes
Mar 31, 2023
There was a problem hiding this comment.
Great work on this! 🙌🏼 The content's all there, but I've got some structural suggestions that I think we should look at. I've added suggestions for most everything so that you can see what I mean. Feel free to push back on any of the suggestions and we'll have a dialog about it!
And before we merge: You'll need to also add the guide to the sidebar by editing website/sidebars.js. Find the section that has the other SSO how-tos and add this one in too. Remember to organize them such that the order is alphabetical based on their title.
Comment on lines
24
to
30
| ### Step 2: Navigate to SSO configuration {#step-2} | ||
|
|
||
| In order to configure SSO with SAML with your Unleash enterprise you should navigate to the Single-Sign-On configuration section and choose the "SAML 2.0" tab. | ||
|
|
||
|  | ||
|
|
||
| ### Step 3: Create an Enterprise Application within Azure AD {#step-3} |
There was a problem hiding this comment.
This first section isn't used at all until the next next section, so we can remove it.
Suggested change
| ### Step 2: Navigate to SSO configuration {#step-2} | |
| In order to configure SSO with SAML with your Unleash enterprise you should navigate to the Single-Sign-On configuration section and choose the "SAML 2.0" tab. | |
|  | |
| ### Step 3: Create an Enterprise Application within Azure AD {#step-3} | |
| ### Step 1: Create an Enterprise Application within Azure AD {#step-1} |
Comment on lines
54
to
70
| **d) Section 2: Attributes & Claims** | ||
|
|
||
| Unleash requires an email to be sent from the SSO provider so make sure to set the "Unique User Identifier" to the "user.mail" source attribute. | ||
|
|
||
| In addition you may provide the following attributes: | ||
|
|
||
| - firstName | ||
| - lastName | ||
|
|
||
| _(These will be used to enrich the user data in Unleash, but are not required)._ | ||
|
|
||
|  | ||
|  | ||
|
|
||
| > Please make sure to replace URLs with the public URL for your Unleash instance. This will require correct region prefix and the instance name. | ||
| > | ||
| > The correct format is: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/callback |
There was a problem hiding this comment.
Why does Unleash require an email? The wording here is a little confusing, I think. I don't quite understand what's going on.
Where does the firstname and lastname go? I don't see them in the screenshot? Or is that the givenname and surname claims that are shown in the second screenshot?
Suggested change
| **d) Section 2: Attributes & Claims** | |
| Unleash requires an email to be sent from the SSO provider so make sure to set the "Unique User Identifier" to the "user.mail" source attribute. | |
| In addition you may provide the following attributes: | |
| - firstName | |
| - lastName | |
| _(These will be used to enrich the user data in Unleash, but are not required)._ | |
|  | |
|  | |
| > Please make sure to replace URLs with the public URL for your Unleash instance. This will require correct region prefix and the instance name. | |
| > | |
| > The correct format is: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/callback | |
| ##### Section 2: **Attributes & Claims** | |
| 1. Set the "name identifier format" to "Email address". | |
| 2. Select "attribute" as the source. | |
| 3. Enter "user.mail" in the source attribute field. | |
| Optionally, you can also provide a first name and a last name. If provided, these will be used to enrich the data in Unleash. | |
|  | |
|  |
Comment on lines
72
to
82
| **e) Get the Azure AD Setup Details** | ||
|
|
||
| Make note of the following details necessary for the Unleash SAML configuration. | ||
|
|
||
| Unleash will need: | ||
| - Azure AD Identifier | ||
| - Login URL | ||
| - X.509 Certificate (in the Federation Metadata XML) | ||
|
|
||
|  | ||
|  |
There was a problem hiding this comment.
Suggested change
| **e) Get the Azure AD Setup Details** | |
| Make note of the following details necessary for the Unleash SAML configuration. | |
| Unleash will need: | |
| - Azure AD Identifier | |
| - Login URL | |
| - X.509 Certificate (in the Federation Metadata XML) | |
|  | |
|  | |
| ##### Sections 3 and 4: Azure AD setup details {#azure-details} | |
| You will need some details from section 3 and 4 of the SAML setup form to configure the integration within Unleash. These details are: | |
| - Azure AD Identifier (from section 4) | |
| - Login URL (from section 4) | |
| - X.509 Certificate (in the Federation Metadata XML from section 3) | |
| <Figure caption="Section 3 contains a download link for the Federation Metadata XML file. Section 4 lists the Azure AD identifier and the login URL" img="/img/sso-azure-saml-azure-details.png"/> | |
| <Figure caption="Within the Federation Metadata XML file, find the `X509Certificate` tag. You'll need the content within that tag." img="/img/sso-azure-saml-x509cert.png"/> |
Comment on lines
84
to
94
| ### Step 4: Configure SAML 2.0 provider in Unleash {#step-4} | ||
|
|
||
| Go back to Unleash Admin Dashboard and navigate to `Admin Menu -> Single-Sign-On -> SAML`. Fill in the values captured in the _"Get the Azure AD Setup Details"_ step. | ||
| This is how the Azure details map to Unleash | ||
| - Azure AD Identifier > Entity ID (should be formatted as https://sts.windows.net/**{GUID}**) | ||
| - Login URL > Single Sign-On URL (should be formatted as https://login.microsoftonline.com/**{GUID}**/saml2) | ||
| - Azure Federation Metadata XML (copy the X509Certificate) > X.509 Certificate | ||
|
|
||
| You may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains separated by commas. You must also decide which global Unleash role they will be assigned (Editor role will be the default). | ||
|
|
||
|  |
There was a problem hiding this comment.
Wait, is this step 2 or 3 now?
Also, the section on auto-creating users is great, but it does not belong here. Instead, we should check to see if this is already covered in the user group SSO configuration doc (website/docs/reference/rbac.md) and link there. Or wait, that's for user groups. Single users might be different?
Suggested change
| ### Step 4: Configure SAML 2.0 provider in Unleash {#step-4} | |
| Go back to Unleash Admin Dashboard and navigate to `Admin Menu -> Single-Sign-On -> SAML`. Fill in the values captured in the _"Get the Azure AD Setup Details"_ step. | |
| This is how the Azure details map to Unleash | |
| - Azure AD Identifier > Entity ID (should be formatted as https://sts.windows.net/**{GUID}**) | |
| - Login URL > Single Sign-On URL (should be formatted as https://login.microsoftonline.com/**{GUID}**/saml2) | |
| - Azure Federation Metadata XML (copy the X509Certificate) > X.509 Certificate | |
| You may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains separated by commas. You must also decide which global Unleash role they will be assigned (Editor role will be the default). | |
|  | |
| ### Step 3: Configure a SAML 2.0 provider in Unleash {#step-3} | |
| In Unleash, navigate to the SAML 2.0 tab on the single sign-on page. | |
| <Figure caption="The single sign-on page is accessible from the single sign-on link in the admin menu (in the navigation bar)." img="/img/sso-configure-saml.png"/> | |
| Use the values from the [previous section](#azure-details) to fill out the form: | |
| 1. In the entity ID field, add the **Azure AD identifier**. It should look a little like this `https://sts.windows.net/<identifier>. | |
| 2. In the single sign-on URL field, add the **login URL**. It should look something like `https://login.microsoftonline.com/<identifier>/saml2` | |
| 3. In the X.509 certificate field, add the content of the `X509Certificate` tag from the **federation metadata XML**. | |
|  |
Comment on lines
96
to
104
| ### Step 5: Validate {#step-5} | ||
|
|
||
| You have now successfully configured Unleash to use SAML 2.0 together with Azure AD as an IdP. Please note that you also must assign users to the application defined in Azure AD to actually be able to log-in to Unleash. | ||
|
|
||
| Try signing out of Unleash. If everything is configured correctly you should be presented with the option to sign in with SAML 2.0. | ||
|
|
||
| Additionally, Azure gives the option to test logging in with a user at the bottom of the Azure AD SAML setup page. | ||
|
|
||
|  |
There was a problem hiding this comment.
This isn't really a step, so let's remove that bit of the heading.
Also, the thing about assigning users in Azure seems like a pretty major point. Maybe that should be it's own step?
Suggested change
| ### Step 5: Validate {#step-5} | |
| You have now successfully configured Unleash to use SAML 2.0 together with Azure AD as an IdP. Please note that you also must assign users to the application defined in Azure AD to actually be able to log-in to Unleash. | |
| Try signing out of Unleash. If everything is configured correctly you should be presented with the option to sign in with SAML 2.0. | |
| Additionally, Azure gives the option to test logging in with a user at the bottom of the Azure AD SAML setup page. | |
|  | |
| ### Step 4: Add users {#step-4} | |
| You must **assign users to the application you defined in Azure AD** for them to be able to log in. | |
| [... maybe add some steps here?] | |
| ### Validation | |
| If everything is set up correctly, you should now be able to sign in with the SAML 2.0 option. You can verify that this works by logging out of Unleash: the login screen should give you the option to sign in with SAML 2.0. | |
| You can also test the integration in Azure by using the "test single sign on" step in the SAML setup wizard. | |
| <Figure caption="The SAML setup wizard contains a step that lets you test your SAML 2.0 integration. You can use this to verify that everything is configured correctly within Azure." img="/img/sso-azure-saml-test-user.png"/> |
There was a problem hiding this comment.
@thomasheartman I've made lots of updates to this, let me know what you think!
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
Comment on lines
64
to
66
| > Please make sure to replace URLs with the public URL for your Unleash instance. This will require correct region prefix and the instance name. | ||
| > | ||
| > The correct format is: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/callback |
There was a problem hiding this comment.
This should probably be an admonition instead, I think. And what URLs are we asking them to replace?
Suggested change
| > Please make sure to replace URLs with the public URL for your Unleash instance. This will require correct region prefix and the instance name. | |
| > | |
| > The correct format is: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/callback | |
| :::info URLs and formats | |
| Make sure to replace URLs with the public URL for your Unleash instance. This will require correct region prefix and the instance name. | |
| The correct format is: https://**[region]**.app.unleash-hosted.com/**[instanceName]**/auth/saml/callback | |
| ::: |
Comment on lines
75
to
76
|  | ||
|  |
There was a problem hiding this comment.
These both feel like they should be figures instead of images. I think the alt text would be a useful caption for anyone. what do you think?
|
|
||
| You can also test the integration in Azure by using the "test single sign on" step in the SAML setup wizard. | ||
|
|
||
|  |
There was a problem hiding this comment.
Turn this into a figure too?
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
thomasheartman
approved these changes
May 25, 2023
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.
About the changes
Added Azure SSO SAML 2.0 instructions based off of testing/user feedback.
Not on GH, internally yes
Important files
website>docs>how-to>how-to-add-sso-azure-saml.md
website>docs>static>img (added images for docs)