Add an identity provider (IdP)
Add SSO identity providers in Reunite, so users can use them for logging into Reunite as well as individual projects. After you have added an IdP in Reunite, the identity provider can then be configured in the redocly.yaml
configuration file for individual projects.
Before you begin
Make sure you have the following before you begin:
- A SAML 2 or OpenID Connect-based identity provider
- The following information about your identity provider:
- SAML 2
- Single sign on URL
- Issuer ID
- x509 public certificate
- OpenID Connect
- Either a configuration JSON or URL
- Client ID
- Client Secret
- SAML 2
- If you plan to use RBAC, add teams before completing this step.
owner
role in your organization
Add a Corporate identity provider (IdP)
A Corporate identity provider is used to authenticate internal users into Reunite and projects. You can only add one Corporate identity provider for your organization.
- Log in to your Redocly instance.
- Select SSO and login in the navigation menu on the left side of the page.
- In the Corporate row under Identity Provider, click + Add and select the type of identity provider you want to add - either SAML 2 or OpenID Connect.
- Complete the form based on the information you have gathered about your SSO identity provider.
- Click Save.
Add a Guest identity provider (IdP)
A Guest identity provider is used to authenticate external users into projects. You can only add one Guest identity provider for your organization.
- Log in to your Redocly instance.
- Select SSO and login in the navigation menu on the left side of the page.
- In the Guest row under Identity Provider, click + Add and select the type of identity provider you want to add - either SAML 2 or OpenID Connect.
- Complete the form based on the information you have gathered about your SSO identity provider.
- Click Save.
Team mapping
Team mapping is an option when you add a Corporate or Guest IdP. The option name differs depending on the protocol you are using to connect:
- For OpenID Connect, the option is referred to as team claim mapping.
- For SAML 2, the option is referred to as team attribute mapping.
In both instances, team mapping is a way to specify what you want your IdP groups to be labeled as in Reunite.
You can also use team mapping to assign users in your IdP groups different project RBAC teams or organization roles than the default team and role.
When users log in with an IdP, the groups assigned in the IdP override the RBAC teams assigned in Reunite.
To map IdP groups to Redocly default teams or project RBAC teams:
- Select the Configure team attribute mapping or Configure team claim mapping checkbox.
- Enter the IdP group name in the Value text box on the left side.
- Enter the Redocly default team tied to an organization role or project RBAC team name into the Team text box on the right side.
- Click the Add mapping button to add additional mappings as needed.
- Click Save.
When users assigned to those groups in your IdP log in to Reunite, they have the project or organization role access assigned to those teams.
Verified domains
Verified domains are a way for you to connect users with a given organization. They only apply to corporate identity providers when logging into Reunite, not logging in to projects. You can add a Verified domain on the SSO and login page in Reunite.
When you add a Verified domain to your organization, users logging in to Reunite with the verified domain email are automatically directed to the corporate identity provider, with the option to use Redocly credentials or social logins. If you also select to require SSO authentication, users logging in to Reunite with the verified domain email domain can only log in using the corporate identity provider.
Require SSO authentication
You can require SSO authentication for all members of your organization by selecting the Require SSO authentication for all members of the Redocly organization checkbox on the SSO and Login page. Selecting this checkbox means that if you have rbac
configured, users must log in with SSO credentials and if they do not have SSO credentials, they will lose access to the organization.
Requiring SSO authentication does not require users to log in to your project. To require login to your project, you must configure rbac
. See Configure RBAC for more information.
Related how-tos
- If you want to specify which identity providers users can use to log in to your project with or if you want to disable SSO, follow the instructions in the Configure SSO how-to documentation.
- If you want to limit access to certain pages in your project or in Reunite, follow the instructions in the Configure RBAC how-to documentation.
Resources
- Discover all the options available for configuring SSO in the
sso
reference documentation - Learn more about the different identity provider types you can add in Reunite or configure in your
redocly.yaml
file in the Single sign-on (SSO) concept doc. - To understand more about the different components involved in Redocly's RBAC, read the Role-based access control (RBAC) concept documentation.
- View examples and options for configuring RBAC in your
redocly.yaml
file in the RBAC reference documentation.