95f4f641b5
https://linear.app/unleash/issue/2-1136/custom-root-roles-documentation - [Adds documentation referencing custom root roles](https://unleash-docs-git-docs-custom-root-roles-unleash-team.vercel.app/reference/rbac); - [Adds a "How to create and assign custom root roles" how-to guide](https://unleash-docs-git-docs-custom-root-roles-unleash-team.vercel.app/how-to/how-to-create-and-assign-custom-root-roles); - Standardizes "global" roles to "root" roles; - Standardizes "standard" roles to "predefined" roles to better reflect their behavior and what is shown in our UI; - Updates predefined role descriptions and makes them consistent; - Updates the side panel description of the user form; - Includes some boy scouting with some tiny fixes of things identified along the way (e.g. the role form was persisting old data when closed and re-opened); Questions: - Is it worth expanding the "Assigning custom root roles" section in the "How to create and assign custom root roles" guide to include the steps for assigning a root role for each entity (user, service account, group)? - Should this PR include an update to the existing "How to create and assign custom project roles" guide? We've since updated the UI; --------- Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
3.5 KiB
| title |
|---|
| How to add SSO with OpenID Connect |
:::note Availability
The Single-Sign-On capability is only available for customers on the Enterprise subscription. Check out the Unleash plans for details.
:::
Introduction
In this guide we will do a deep dive on the Single-Sign-On (SSO) using the OpenID Connect protocol and connect it with Okta as IdP. Unleash supports other identity providers and protocols, have a look at all available Single-Sign-On options
Basic configuration
Step 1: Sign-in to Unleash
In order to configure SSO you will need to log in to the Unleash instance with a user that have "Admin" role. If you are self-hosting Unleash then a default user will be automatically created the first time you start Unleash:
- username:
admin - password:
unleash4all
Step 2: Navigate to SSO configuration
Unleash enterprise supports multiple authentication providers, and we provide in depth guides for each of them. To find them navigate to "Admin" => "Single-Sign-On" section.
Step 3: Okta with OpenID Connect
Open a new tab/window in your browser and sign in to your Okta account. We will need to create a new Application which will hold the settings we need for Unleash.
a) Create new Okta application
Navigate to “Admin/Applications” and click the “Add Apps” button.
Then click “Create Application” and choose a new “OIDC - OpenID Connect” application, and choose application type "Web Application" and click create.
b) Configure Application Integration
Give you application a name. And set the Sign-in redirect URI to:
https://[region].app.unleash-hosted.com/[instanceName]/auth/oidc/callback
(In a self-hosted scenario the URL must match your UNLEASH_URL configuration)
You can also configure the optional Sign-out redirect URIs: https://[region].app.unleash-hosted.com/[instanceName]/
Save your new application and your will ge the required details you need to configure the Unleash side of things:
c) Configure OpenID Connect provider in Unleash
Navigate to Unleash and insert the details (Discover URL, Client Id and Client Secret) in to Unleash.
Pleas note that the
Discover URLmust be a valid URL and must include thehttps://prefix. For example: https://dev-example-okta.com is a valid discovery URL.
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. You must also decide which root Unleash role they will be assigned (Editor role will be the default).
Step 4: Verify
Log out of Unleash and sign back in again. You should now be presented with the "Sign in with OpenID Connect" option. Click the button and follow the sign-in flow. If all goes well you should be successfully signed in to Unleash.
(If something is not working you can still sign-in with username and password).
Success!