This guide will teach you how to enable OpenID Connect (OIDC) SSO for your organization via the Formant Admin API.
Prerequisites
Set up an OIDC identity provider
Before using OIDC SSO in Formant, you'll need to set up an OIDC provider for your organization. You'll need to enter the provider's URL, and generate a Client ID to allow Formant to authenticate via OIDC.
(Optional) Create OIDC groups, Formant teams, and Formant roles
You can manage various groups of users and their permissions within your OIDC authentication structure. When users sign into your Formant organization using OIDC SSO, their email address will be checked for membership in a group. If the address is found, the user is assigned the set of permissions and access levels associated with that group.
Formant has an equivalent concept, which is accomplished using roles and teams. A role is a set of permissions and access levels granted to a single user. A team is a named set of users who all have the same role.
When users sign into Formant via OIDC SSO for the first time, if they are part of an OIDC group, Formant will check for an equivalent team. If the group does not have a corresponding team, the user will be assigned a default role.
To learn more about creating roles and teams in Formant, see Users, service accounts, and teams and Configure access levels.
Making the API call
You'll want to call the following endpoint: POST SSO Configuration. Configure the parameters as follows:
| Parameter | Usage |
|---|---|
| organizationId | ID of the organization for which OIDC SSO should be enabled |
| domain | Users with an email address on this domain will be able to sign in via SSO. This must match your email address in Formant. For example, if your email is [email protected], you can only add xyz.com. |
| defaultRoleId | Enter the ID of the default role which should be assigned to new users. Either a default role or a default team must be defined. If both are defined, the default team will take precedence. |
| defaultTeamId | Enter the ID of the default role which should be assigned to new users. Either a default role or a default team must be defined. If both are defined, the default team will take precedence. |
| defaultAccountId | Enter the ID of the default account to which new users should be assigned. |
| authenticationFlow | Set this to oidc. |
| clientId | Enter the Client ID provided to you by your identity provider during registration. |
| issuer | Enter the URL of your OIDC identity provider. |
| ssoGroupNameToTeamMappings | Enter the names of your OIDC groups, and then map those groups to Teams in Formant. |
| enabled | Set this to true to enable SSO for your organization. |
If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].