CONFIGURING OIDC

UnForm can use an Open ID Connect (OIDC) provider to authenticate users and provide UnForm with a user email address.  UnForm can also auto-create new users using the email as their user ID by setting up valid email patterns, such as by domain name, relieving administrators of some maintenance burden.  Auto-created users do not have any specific permissions, so to enable group membership or specific permissions, their record can be edited after creation.

In order for UnForm to interface with the OIDC provider, an application must be registered at that provider and UnForm must be provided the following information in its Configuration option, Security tab:

•Provider configuration URL, which will end with "/.well-known/openid-configuration".  This URL contains information UnForm needs to redirect the user to the provider when logging into the UnForm browser interface.

•Application Client ID, which identifies this registered application to the provider.

•The root path to this UnForm instance, such as "https://exampleunform.com:27502. This is the root of two redirect paths configured in the application.  Note for OIDC, UnForm must be accessed using https rather than http (unless it is always accessed has http://localhost).  Therefore, a prerequisite for using OIDC with UnForm is SSL certificate configuration so that it can be accessed using https://domain.

•Auto-generated user patterns, typically @domain, that enables new users authenticated by the provider to have user records automatically generated.

Application Registration in Microsoft Identity (Entra)

A common provider for many UnForm users is Microsoft.  Here are registration settings you can use on that platform.

•Create a new application registration

•On the Overview page, open Endpoints to and copy the OpenID Connect metadata document URL.  This is the Provider configuration URL.

•Also on the Overview page, copy the Application (Client) ID.  This value is the Application Client ID value.

•Create one required and one optional redirect URI:

ohttps://your-unform-domain:port/api/login (required)

ohttps://your-unform-domain:port/api/logout (optional, will log out users from Microsoft when logging out of UnForm)

•Add an email claim under Token configuration

•Add email, oidc, profile, and User.Read to the API permissions list

The above settings will enable a user to login using 'Login with Provider' at the UnForm login screen.  Once authenticated by the provider, UnForm will receive a JWT token (via the redirect URI) with authenticated user information, including an email address.  Once that JWT token is verified, UnForm accepts that user as valid, and uses the provided email as the user ID.