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 `admin@xyz.com`, 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.