# OAuth ## OAuth Application Setup Overview The most common OAuth method is leveraging the OpenID Connect framework to achieve user authentication into your application. OIDC proves to be a flexible and secure means of authenticating your user base, with a multitude of different providers available. Form.io seamlessly manages this integration, offering multiple strategies and methods to authenticate users through OIDC providers. ### Setting up an OIDC provider Choosing an OIDC provider is the first step in the integration process. An OIDC application will then be created and configured. Remote Authentication will be configured for the Application connected to the Form.io Project. This authentication method will validate the user using credentials stored with the OIDC provider, without relying on or accessing any underlying Form.io data, decoupling the OIDC user information from the Form.io project. Form.io offers integration with many providers, including the following: * [**OneLogin**](#one-login) * [**Okta**](#okta) * [**Microsoft Entra ID** ](#microsoft-entra-id) * [**Auth0**](#auth0) {% embed url="" %} The configuration process will vary for each OAuth/OIDC provider, however each provider generally requires the same setup. Each Provider will require the application domain to be saved to the [**Callback URL**](#user-content-fn-1)[^1]. This should be the domain the OIDC User is redirected to when they are authenticated from the OIDC Provider. ### Creating / Assigning Users and Groups Once the application is configured, establish a user base within the authentication provider. OIDC Users can then be assigned to OIDC Groups, which allows role mapping between the OIDC Group and Form.io Role. ### **Form.io Integration** Each will produce comparable endpoints and credentials for integrating the provider into your Form.io project. Once the OIDC application has been configured, save the following information from your OIDC provider, which will be incorporated into the Authorization settings within your Project. {% hint style="info" %} Access the application's **well-known endpoint** to retrieve the required endpoints for integration with the Form.io Project. {% endhint %}


Authorize URI	The endpoint where the OIDC user is asked to authenticate, granting access to the client application Example URL: https://yourcompany.oidcprovider.com/auth
Token URI	The endpoint utilized to retrieve the OAuth token from the provider after authorization has been granted. Example URL: https://yourcompany.oidcprovider.com/token
User Info URI	Examlpe URL The endpoint holding the scope of the authorizing user (or user attributes) such as email and ID stored within the OIDC provider Examlpe URL: https://yourcompany.oidcprovider.com/me
Client ID	Character string representing the client ID generated by the OAuth provider Example ID: abc123def456
Client Secret	Character string representing the client ID generated by the OAuth provider Example Secret: abc123def456
Scope	Communicates to the OIDC provider what information should be returned from the user to utilize for authentication. This data is compromised of various attributes and information about the User. Ensure the required scopes `openID` and `email` are set within the Form.io project authentication.

Navigate to the Form.io Project's **Settings** > **Authentication > OAuth** and apply your OIDC settings to the appropriate Form.io setting fields within the **OpenID** tab.

#### **Configure Login Form** The Form.io User Login form will then be modified along with an OAuth action, to support the OneLogin OIDC Authentication workflow. #### Role Mapping The OIDC Group associated with the OIDC user can be mapped to a Form.io role when the user authenticates. This is done by integrating the OIDC Provider group claim into the Form.io project and then mapping the OIDC Group name to a Form.io Role within the Oauth action saved to the Login Form. ### General Troubleshooting While the OAuth provider configuration and settings fall outside of Form.io, here are some common troubleshooting tips if your OIDC authentication isn't functioning correctly. * #### How Do I Find The URI Endpoints? The easiest way to identify the correct URI endpoints is to navigate to your OIDC URL and then append the '**well-known**' endpoint. `/.well-known/openid-configuration` **Example:**

https://yourcompany.oidcprovider.com/.well-known/openid-configuration

The response will provide all necessary URI endpoints specific to your OIDC provider as well as any scopes or claims you may want to include within your Form.io Authorization settings or **O*****A*****uth Action**. * **Allow Origins** - The application domain that will authenticate the OIDC User. Ensure the correct client (application) domains are set within your OIDC provider utilized for authentication of the OIDC provider that will be allowed * **Callback URL** - The URL to which Auth0 redirects users after they authenticate from the Allow Origin domain. Typically would be the same URL(s) as the Allow Orgin endpoints. In some cases, the authentication domain may be different than the domain the user is redirected to after authentication. \ Different Providers may refer to the Callback URL differently:\ Redirection URI, Redirection URL, Redirect URI, Redirect URL, or Callback URI * **Connection** - Connections determine how or where the OIDC user will authenticate. Many times, Username and Password credentials stored within the OIDC provider serve as the primary means of authenticating users. However, different providers offer integrations with other OAuth-enabled applications such as Google or Facebook for authentication. It's important to ensure that a connection method is enabled for your OIDC provider; some connections might be enabled by default, depending on the provider. * **Scope** - Check the supported Scope attributes (or claims) of your OIDC provider by searching 'scope' within the provider's 'well-known' endpoint. In every scenario, `openid` and `email` will always be included in the scope of any OIDC provider and must be configured within the OpenID settings of your project. * **Authentication Method**- In most cases, the Authentication Method should be set to POST * **Application Type** - Ensure the correct application type is configured for the OIDC application. In many cases, this will be a 'Web Page' or 'Single Page Application'. ## One Login This section covers the [**OneLogin Provider**](https://developers.onelogin.com/openid-connect) OIDC application setup process and integration with the Form.io Project. Remote Authentication will be configured for the Application connected to the Form.io Project. This authentication method will validate the user using credentials stored with the OIDC provider, without relying on or accessing any underlying Form.io data, decoupling the OIDC user information from the Form.io project. ### Create and Configure Application 1. From your OneLogin Admin dashboard, create a new application by clicking the **Applications tab** and then the **Add App** button.

2. Select the **OpenId Connect (OIDC)** application

3. Give the Application a name and click the **Save** button with the default configurations

4. Click the **Configuration** tab to set up the application details * Add the **Redirect URIs** - Live endpoint of the hosted application where the response to the SAML request should be sent, after the user signs in\ `https://app.yoursite.com` * Add the **Post Logout Redirect URIs** - Live endpoint that redirects a user to a specified URL after the logout process is complete\ `https://app.yoursite.com` The configuration should look similar to the following:

5. Click the **SSO** tab and set the **Authentication Method** to **POST**

Adding a Group Parameter will enable the ability to include the user role (group) in the OIDC claim. 6. Click the **Parameter** tab 7. Click the existing **Group** parameter 8. Set the **value** to **User Roles** and the **Transform** to **Semicolon Delimited input** 9. Set the field name to **Groups**

### Create User With the application configured, create a user base within the OneLogin Admin dashboard. Users can then be assigned to a Role linked with the OIDC Application, allowing OIDC and Form.io role mapping. 1. Within the OneLogin Admin dashboard, hover over the User tab and click **Users** 2. Click the **New User** button

3. Input the Information for the User and then click **Save User** 4. If you would like to set a password, click the **More Action** tab and **Change** **Password** 5. Generate **multiple** **users** to assign them to different roles further in the walkthrough

### Create and Assign Groups With our Users in place, the next step is to create **Roles** the OIDC Users will be assigned to. This will allow us to establish mappings between OIDC roles and Form.io roles. 1. Within the OneLogin Admin dashboard, hover over the User tab and click **Roles** 2. Click the **New Role** button

3. Give the **Role** a name and **select** the OIDC Application the Role should be associated with 4. Click the **Save** role

5. Within the **Roles** tab, click the **Role** that was just created and click the **Users** Tab 6. Using the search bar, search and select all Users that should be added to the Role and click **Check**

5. Click the **Add To Role** button for each user 6. Click **Save**

#### **Assign Role To OneLogin Application** With the Roles established, the next step is to assign the Role to the OIDC application 1. Hover over the **Application** tab and select Applications 2. Navigate to your **OIDC Application** 3. Click the **Access** tab 4. **Select** all of the **Roles** you wish to assign to the Application. Users assigned to the selected roles will be added to the Application. 5. Click **Save**

### **Form.io Integration** After the OIDC application is properly configured, information from the provider will be utilized to integrate with the Form.io project and establish remote authentication. Navigate to the Form.io Project settings and apply the OIDC settings to the appropriate Form.io field settings. #### **Client ID and Secret Key** 1. Within your OIDC Application, click the **SSO** tab 2. Copy the **Client ID** 3. Click the **Show client secret** button and **copy** the secret

4. Navigate to the OAuth settings within your Form.io project\ **Settings** > **Authentication > OAuth** ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FywaOATjkZv158Riq7BYt%2Foauth1.png?alt=media\&token=f3c262b3-7f1e-4f81-82bd-85336f96815e) 5. Paste the OIDC **Client ID** and **Client Secret** to the correlated Form.io field settings

#### Well-Known Configuration 1. Click the **SSO** tab within the **OIDC** application 2. Click the **Well-known Configuration** button to access the OIDC application metadata

The well-known configuration will look something like this:

3. Search the well-known configuration JSON file and find the following **endpoints**, then map them to the **corresponding** **fields** in your Form.io settings. | Form.io Setting | Well-known Configuration | | ---------------------- | ------------------------ | | Authorize URI | authorization\_endpoint | | Token URI | token\_endpoint | | Logout URI | end\_session\_endpoint | | User Info (claims) URI | userinfo\_endpoint | 4. Input the following values within the **Scope** setting\ **openid** | **email** {% hint style="info" %} The `openid` and `email` scopes are **required** for all OIDC providers and must be configured in your project's OpenID settings to ensure successfully user authentication {% endhint %} Your settings should look something like this

#### **Configure Login Form** Configure the Form.io User Login form to support the OneLogin OIDC Authentication within the application. 1. Navigate to the Form.io project and **edit** the application **Login** form. 2. Add a **Button** component 3. Within the Button settings, set the **Action** to **OAuth** and **OAuth** **Provider** to **OpenID** 4. **Save** the form

#### **Oauth Action** Once the Login form has been configured, an OAuth action will be added to the form to facilitate the OIDC authentication process. 1. Navigate to the **Login** form within the Form.io Project 2. Click the **Action** tab and add the **OAuth** action 3. Click the **OAuth Provider** setting and select **OpenID** 4. Click the **Action** setting and select **Remote Authentication** 5. Click the **Sign-in with OAuth Button** setting and select the **SSO** button 6. If you are mapping roles, add the following setting to the **Assign Roles** setting fields * The **Claim** setting will be the claim name that supports roles within the OIDC scope. * The **Value** setting will be the identifier for the OIDC Group. * The **Role** setting is the Form.io role that should be assigned to users with the given OIDC Role.
In the example below OIDC users with the **Member** role will authenticate into the application with the Form.io **Authenticated** role. OIDC users with the **Admin** role will authenticate into the application with the Form.io **Administrator** role. | Claim (OIDC) | Value (OIDC) | Role (Form.io) | | ------------ | ------------ | -------------- | | groups | Member | Authenticated | | groups | Admin | Administrator |

#### Role Mapping In many cases, you may want to map the OIDC Role associated with the OIDC User to a Form.io Role. This can be done by adding the OIDC group claim within the scope setting of the Form.io Project as well as the Oauth action. 1. Navigate to the **Form.io Authorization** setting\ **Settings** > **Authentication > OAuth** 2. Add the following values to the **Scope** setting field\ **groups**

3. Within the OneLogin **OIDC Application,** click the **Access** tab and take note of the **Role** **Names** assigned to the application.

4. Navigate to the **Role** settings and map the **OIDC** **group** (case sensitive) to the desired **Form.io Role**\ The example below maps OIDC users with the Member role to the Form.io Authenticated role and OIDC users with the Admin role to the Form.io Administrator role | Claim (OIDC) | Value (OIDC) | Role (Form.io) | | :----------: | :----------: | :------------: | | groups | Member | Authenticated | | groups | Admin | Administrator | 5. **Save** the **settings** ### Testing Authentication Test the authentication workflow to ensure it functions correctly. 1. Navigate to your Applications authentication page and click the **SSO with OIDC** button. 2. Enter the **OIDC** **credentials** into the OneLogin authentication page

3. Once authenticated, the OIDC user should carry the **OIDC** **Group** **Role** (Member) as well as the mapped **Form.io Role ID** within the metadata of the user object.

## Okta This section covers the [**Okta OIDC**](https://www.okta.com/openid-connect/) application setup process and integration with the Form.io Project. Remote Authentication will be configured for the Application connected to the Form.io Project. This authentication method will validate the user using credentials stored with the OIDC provider, without relying on or accessing any underlying Form.io data, decoupling the OIDC user information from the Form.io project ### Create and Configure Application 1. From your [**Okta Developer**](https://developer.okta.com/) dashboard, create a new application by clicking the **Applications tab** and then the **Applications** button. 2. Click the **Create App Integration** button

3. Select **OIDC - OpenID Connect** from the **Sign-in method** section 4. Select **Web Application** from the **Application type** section

5. Apply the following configurations to the **General Settings** of the Okta OIDC Application * Add the **Sign-in Redirect URI** - Domain of the hosted application where Okta sends the authentication response and ID token for the sign-in\ `https://app.yoursite.com/yourloginpage` * Add the **Sign-out redirect URIs** - Live endpoint that redirects a user to a specified URL after the logout process is complete\ `https://app.yoursite.com` The configuration should look similar to the following:

5. Select a **Controlled Access** setting 6. **Save** the Settings to create the application

### Create User Once the application is configured, establish a user base in the Okta dashboard. Users can be assigned to Okta Groups, which can then be mapped to roles in Form.io. 1. Within your Okta Admin dashboard, click the **Directory** tab and select **People** 2. Click the **Add person** button

3. Enter person **details** for the OIDC User 4. Click the **Password** dropdown to determine how Users password will be set 5. Click **Save** to add the User

### Create and Assign Groups With Users in place, create **Groups** the OIDC Users will be assigned to. This will allow us to establish mappings between OIDC roles and Form.io roles. 1. Within your Okta Admin dashboard, click the **Directory** tab and select **Groups** 2. Click the **Add Group** button

3. Give your Group a **Name** and click **Save**

With a Group created, the next step is to assign users to the Group. 4. From the **Group** tab, select the Group to add Users to 5. Click the **Assign people** button

5. Assign a User to a Group by clicking the **+** button next to their username.

6. Within your Okta application, click the **Sign-On** tab 7. Click **Edit** under the **OpenID Connect ID Token** section

8. Set the **Groups claim type** to **filter** 9. Input **groups** into the Groups claim filter 10. Set the filter type to **Matches regex** 11. Add a "**\***" character next to the filter type 12. **Save** the settings

#### **Assign Groups To Okta Application** After establishing the Groups, the next step is to assign them to the OIDC application 1. To assign the Group, open the **Directory** tab, select the **Group,** and click the **Applications** tab 2. Click the **Assign applications** button

3. Within the modal window, click the **Assign** button next to the **OIDC application**

### **Form.io Integration** After the OIDC application is properly configured, information from the provider will be utilized to integrate with the Form.io project and establish remote authentication. Navigate to the Form.io Project settings and apply the OIDC settings to the appropriate Form.io field settings. #### **Client ID and Secret Key** 1. Within your **Okta** Application, click the **General** tab 2. Copy the **Client ID** and **Client Secret**

#### Well-Known Configuration 1. Append the well-known endpoint to the Okta application URL `https://dev-myapplication-admin.okta.com/.well-known/openid-configuration` 2. Open the **URL** within the **browser**. The well-known configuration will look something like this:

The openid and email scopes are required for all OIDC providers and must be configured in your project's OpenID settings to ensure user authentication

\ Your settings should look something like this

3. Within the OneLogin **OIDC Application,** click the **Access** tab and take note of the **Role** **Names** assigned to the application.

4. Navigate to the **Role** settings and map the **OIDC** **group** (case sensitive) to the desired **Form.io Role**\ The example below maps OIDC users with the Member role to the Form.io Authenticated role and OIDC users with the Admin role to the Form.io Administrator role | Claim (OIDC) | Value (OIDC) | Role (Form.io) | | :----------: | :----------: | :------------: | | groups | Member | Authenticated | | groups | Admin | Administrator | 6. **Save** the **settings** ### Testing Authentication Test the authentication workflow to ensure it functions correctly. 1. Navigate to your Applications authentication page and click the **SSO with OIDC** button. 2. Enter the **OIDC** **credentials** into the Okta authentication page

3. Once authenticated, the OIDC user should carry the **OIDC** **Group** **Role** (Member) as well as the mapped **Form.io Role ID** within the metadata of the user object. ## Microsoft Entra ID This section covers the [**Microsoft** **Entra ID**](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) OIDC application setup process and integration with the Form.io Project. Remote Authentication will be configured for the Application connected to the Form.io Project. This authentication method will validate the user using credentials stored with the OIDC provider, without relying on or accessing any underlying Form.io data, decoupling the OIDC user information from the Form.io project ### Create and Configure Application 1. Navigate to the [**Azure Portal**](https://portal.azure.com/), click the left navigation panel, and select **Microsoft Entra ID**.

2. Click the **left-hand navigation bar** and select **App registrations** 3. Click the **+New registration** button

4. Give the application a **name** 5. Under the **Redirect URI** section, select **Web** from the dropdown, and input the application **URI** 6. Click the **Register** button The configuration should look similar to the following:

#### Creating Client Secret Once the application has been created, a Client secret will need to be generated that will be added to the Authentication OAuth integration settings within the Form.io Project. 1. Click the **Certificates and secrets** tab 2. Click the **+ New client secret** button 3. Give the secret a **Description** 4. Click the **Add** button

5. Copy the **Client Secret Value** {% hint style="warning" %} This is the only opportunity to save the **Client Secret Value** {% endhint %}

#### Adding group claim 1. Click on **Token Configuration** 2. Click **Add groups claim** 3. Check the **Groups assinged to the application** setting 4. Click **Add**

### Create User Once the application is configured, establish a user base within the Entra ID dashboard. Users can be assigned to Entra ID Groups, which can then be mapped to roles in Form.io. 1. Within the **Entra ID** application, click \ **Home** > **Microsoft Entra ID** > **Users** 2. Within the **All Users** tab click the **+New user** button

3. Input the User information and click the **Review + create** button {% hint style="warning" %} Ensure the User **email address** and **name** is set within the **Properties** tab of the user profile Contact your Azure administrator to add the required properties to the user profile {% endhint %}

4. Create several other users to test Group and Role mapping detailed in the next section.

### Create and Assign Groups With Users in place, the next step is to create **Groups** the Entra ID Users will be assigned to. This will allow us to establish mappings between EntraID groups and Form.io roles. 1. Within the Azure dashboard, click the left-hand navigation bar, **Groups**, and **All Groups** tab 2. Click the **New group** button

3. Give the Group a **Group Name** and keep the remaining settings at their default values

4. Click the **No Members Selected** button to assign users * **Search** for the User created in the previous section * **Select** the User * Click the **Select** button

5. Click the **Create** button 6. Follow the same steps to create additional **Groups**

#### **Assigning Groups to Application** With the Groups established, the next step is to assign the Groups to the Entra ID application. {% hint style="warning" %} Groups mappings for Entra ID are supported for formio-server version 9.6.x and above {% endhint %} {% hint style="warning" %} A proper license is required to add Groups to your Entra ID application {% endhint %} 1. Navigate back to your **Entra ID OIDC** application 2. Select the **Users and groups** tab then click the **+ Add user/group** button 3. On the next screen, click the **None Selected**

4. Select the **Groups** to add to the application 5. Click the **Select** button at the bottom of the screen and then **Assign** on the following page

After assigning the Groups, you should see the Groups displayed within the User and Groups tab of the Entra ID application. Users assigned to the selected groups will be associated with the Entra ID Application.

### **Form.io Integration** Once the OIDC application is properly configured, information from the application will be used to integrate the application with the Form.io project. Navigate to the Form.io Project settings and apply the OIDC settings to the appropriate Form.io field settings. #### **Client ID and Secret Key** 1. Navigate to the **Entra ID** dashboard, click **App registrations**, and select your application

2. Within your Entra ID Application, click the **Overview** tab 3. Copy the **Application (client) ID** value and **Secret** from the [**Client Secret Step**](#creating-client-secret)

4. Navigate to the OAuth settings within your Form.io project\ **Settings** > **Authentication > OAuth** ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FywaOATjkZv158Riq7BYt%2Foauth1.png?alt=media\&token=f3c262b3-7f1e-4f81-82bd-85336f96815e) 5. Paste the OIDC **Application** (**Client) ID** and **Client Secret** to the correlated Form.io field settings

#### Well-Known Configuration 1. Within Entra ID, click the **App registrations** tab and select the **OIDC Application** 2. Click the **Overview** tab and then **Endpoints** 3. **Copy** the ***OpenID Connect metadata document*** ULR and open it in a browser

The Endpoints will look something like this:

4. Add the following endpoints from the Well-known configuration to the correlated field settings

Form.io Setting	Well-known Config
Authorize URI	authorization_endpoint
Token URI	token_endpoint
User Info (claims) URI	userinfo_endpoint

5. Input the following values within the **Scope** setting **openid** | **email** {% hint style="info" %} The `openid` and `email` scopes are **required** for all OIDC providers and must be configured in your project's OpenID settings to ensure user authentication {% endhint %} Your Form.io Authorization settings should look something like this

**Configure Login Form** Configure the Form.io User Login form to support the Auth0 Authentication within your application. 1. Navigate to the Form.io project and **edit** the application's **Login** form. 2. Add a **Button** component 3. Within the Button settings, set the **Action** to **OAuth** 4. Set the **OAuth** **Provider** to **OpenID** 5. **Save** the form

**OAuth Action** Once the Login form has been configured, an OAuth action will be added to the form to facilitate the OIDC authentication process. 1. Navigate to the **Login** form within the Form.io Project 2. Click the **Action** tab and add the **OAuth** action 3. Click the **OAuth Provider** setting and select **OpenID** 4. Click the **Action** setting and select **Remote Authentication** 5. Click the **Sign-in with OAuth Button** setting and select the **OIDC Button** 6. If you are mapping roles, add the following setting to the **Assign Roles** setting fields * The **Claim** setting will be the claim name (**Group** **Object ID)** that supports roles within the OIDC scope. * The **Value** setting will be the **Group ID** for the Entra ID Group.

* The **Role** setting is the Form.io role that should be assigned to users with the given OIDC Role

7. **Save** the Action ### Testing Authentication Test the authentication workflow to ensure it functions correctly. 1. Navigate to your Applications authentication page and click the **SSO with OIDC** button. 2. Enter the **OIDC** **credentials** into the **Microsoft** authentication page

3. Once authenticated, the OIDC user should carry the **OIDC** **Group** **Role** (group id) as well as the mapped **Form.io Role ID** within the metadata of the user object. ## Auth0 This section explains how to set up the [**Auth0 Provider** ](https://auth0.com/)OIDC application and integrate it with the Form.io Project. Remote Authentication will be configured for the application linked to the project, allowing user validation through credentials stored with the OIDC provider. This ensures authentication occurs independently of any Form.io data, keeping OIDC user information fully decoupled from the Form.io project. ### Create and Configure Application 1. Access the [**Auth0 Admin dashboard**](https://manage.auth0.com/dashboard) 2. Click the **Applications** tab 3. Click the **+Create Application** button

4. Give the Application a **Name** and click the **Create** button

5. Within the Application, click the **Setting** tab

5. Navigate to the Application URIs section and add the application endpoint to the **Allowed Callback URLs**\ `https://myapplication.com/dashboard`

6. **Save** the settings ### Create User After configuring the application, set up your user base in the Auth0 dashboard. Assign users to Auth0 Roles, which can then be mapped to corresponding Form.io Roles. 1. In the Auth0 admin dashboard, navigate to **User Management** and select **Users** 2. Click the **+Create User** button

3. Input user **credentials** and click **Create**

4. Add **additional** **users** to assign to the roles that will be configured in the next step.

### Create and Assign Roles Once users are set up, the next step is to create roles for OIDC users. These roles establish the mappings between OIDC roles and Form.io role assignments. 1. Under the **User** **Management** tab, click **Roles** 2. Click **Create Role**

3. Enter a **Name** and **Description** for the role, then click **Create**.

4. Within the Role tab, select a **Role** created in the previous step

5. Click on the **Users** tab 6. Click **Add Users**

7. Search and select the user to add to this Role and click **Assign**

8. Assign users to additional Roles you might have created in the previous steps ### Implementing Custom Actions to Assign Form.io Roles In order to assign the Roles created in Auth0 and map them to a Form.io login, a custom Post-Login Action in Auth0 to required to map Form.io roles in the ID token. After creating and coding the action, deploy it and attach it to the Post-Login trigger to ensure it runs after user login. 1. Under the **Actions** tab click **Library** 2. Click the **Create Action** dropdown then select **Create Custom Action**

3. Give the action a **Name** 4. Set the **Trigger** to **Login / Post Login** 5. Set **Runtime** to **Node 18** and click **Create**

6. **Add** the following **code** within the **onExecutePostLogin** function ```typescript exports.onExecutePostLogin = async (event, api) => { if(event.authorization){ api.idToken.setCustomClaim('formioRoles', event.authorization.roles); } }; ```

{% hint style="warning" %} Note: you cannot .setCustomClaim('groups', ...) or .setCustomClaim('roles', ...) {% endhint %} 7. Click the **Deploy** button 8. Under the **Actions** tab, click on **Triggers** 9. Click the **post-login** trigger 10. Click the **Custom** tab 11. Drag your action in between **Start** and **Complete** 12. Click **Apply**

### **Form.io Integration** Once the OIDC application is properly configured, information from the application will be used to integrate the application with the Form.io project. Navigate to the Form.io Project settings and apply the OIDC settings to the appropriate Form.io field settings. #### **Client ID and Secret Key** 1. Navigate to your Auth0 Application and click the **Settings** tab 2. Copy the **Client ID** and **Client Secret**

3. Navigate to the **Form.io Project** Auth0 authentication should be applied to 4. Access the **OAuth** settings\ **Settings** > **Authentication > OAuth > OpenID** ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FywaOATjkZv158Riq7BYt%2Foauth1.png?alt=media\&token=f3c262b3-7f1e-4f81-82bd-85336f96815e) 5. Paste the OIDC **Client ID** and **Client Secret** to the correlated Form.io field settings

#### Well-Known Configuration 1. Within your Auth0 Application, click the **Settings** tab 2. Scroll down the Settings page and expand the **Advanced Settings** 3. Click the **Endpoints** tab

The endpoint information will look something like this:

4. Add the following endpoints Well-known configuration endpoints and map them to the **corresponding** **fields** in your Form.io settings. | Form.io Setting | Well-known Configuration | | ---------------------- | ------------------------ | | Authorize URI | OAuth Authorization URL | | Token URI | OAuth Token URL | | User Info (claims) URI | OAuth User Info URL | 5. Input the following values within the **Scope** setting\ **openid** | **email** {% hint style="warning" %} The `openid` and `email` scopes are **required** for all OIDC providers and must be configured in your Form.io project's OpenID settings to ensure successful user authentication." {% endhint %} Your settings should look something like this

#### **Configure Login Form** Configure the Form.io User Login form to support the Auth0 Authentication within your application. 1. Navigate to the Form.io project and **edit** the application's **Login** form. 2. Add a **Button** component 3. Within the Button settings, set the **Action** to **OAuth** 4. Set the **OAuth** **Provider** to **OpenID** 5. **Save** the form

#### **OAuth Action** Once the Login form has been configured, an OAuth action will be added to the form to facilitate the OIDC authentication process. 1. Navigate to the **Login** form within the Form.io Project 2. Click the **Action** tab and add the **OAuth** action 3. Click the **OAuth Provider** setting and select **OpenID** 4. Click the **Action** setting and select **Remote Authentication** 5. Click the **Sign-in with OAuth Button** setting and select the **OIDC Button** 6. If you are mapping roles, add the following setting to the **Assign Roles** setting fields * The **Claim** setting defines the claim name that carries role information within the OIDC scope. Use the same name specified in **Step 6** of the [**Custom Action**](#implementing-custom-actions-to-assign-form.io-roles) section in the Auth0 setup.

* The **Value** setting will be the identifier for the OIDC Group. Use the same **Role** name specified in **Step 3** of the [**Create and Assign Roles**](#create-and-assign-roles) section in the Auth0 setup. * The **Role** setting is the Form.io role that should be assigned to users with the given OIDC Role. 7. **Save** the Action settings {% hint style="info" %} In the example below OIDC users with the **Member** role will authenticate into the application with the Form.io **Authenticated** role. OIDC users with the **Admin** role will authenticate into the application with the Form.io **Administrator** role. {% endhint %} | Claim (OIDC) | Value (OIDC) | Role (Form.io) | | ------------ | ------------ | -------------- | | formioRoles | admin role | Administrator | | formioRoles | user role | Authenticated |

### Testing Authentication Test the authentication workflow to ensure it functions correctly. 1. Navigate to your Applications authentication page and click the **SSO with OIDC** button. 2. Enter the **OIDC** **credentials** into the OneLogin authentication page

3. Once authenticated, the OIDC user should carry the **OIDC** **Group** **Role** (Member) as well as the mapped **Form.io Role ID** within the metadata of the user object. ## Token Swap One type of application design is where form.io forms are embedded in an existing application that already has OAuth authentication built into it. In this type of application, the OAuth token can be exchanged for a form.io token to enable all future interactions with form.io to be authenticated using the new form.io token. To do this, you should have an existing Bearer (or other) authorization token from the OAuth provider. You also need to set up the OpenID and OpenID Connect settings in your project. Then, instantiate the Formio library with your project URL and call the currentUser endpoint with your authorization header. ```json var header = new Formio.Headers(); header.set('Authorization', 'Bearer 2e762950-9498-4079-a699-xxxxxxxxxxxx'); Formio.setBaseUrl('https://yourdomain.com'); Formio.setProjectUrl('https://yourdomain.com/yourproject'); var formio = new Formio('https://yourdomain.com/yourproject'); formio.currentUser({ external: true, header: header, }); ``` {% hint style="info" %} To perform a Token Swap, it is required to expose the /UserInfo endpoint {% endhint %} Form.io will use the authorization token to request the OAuth endpoint, receive the user information, and create a new form.io token that is passed back to the form.io library and used on subsequent requests. ## OIDC - Developer Portal To enable SSO in the Developer Portal, simply apply all the configurations detailed above, but apply the configurations to the **Portal Base** project. Utilizing the Remote Authentication method will set up authentication for the Developer Portal application, eliminating the necessity for resource-based authentication. Follow the link below for a detailed walkthrough: [**SSO Authentication Into Developer Portal Using OIDC**](#user-content-fn-5)[^5] ## OIDC - Form Manager Application The same concepts above can be applied to the Form Manager application. Since the Form Manager utilizes the Admin Login form for authentication, the only difference between this workflow and the previous SSO example is the form being modified is the Admin Login form instead of User Login. #### OIDC Provider Application 1\. Create an application within your OIDC provider (in this example auth0) and choose Single Page application type. ![](https://gblobscdn.gitbook.com/assets%2F-MPHoF2HwOA0s5HV_AIB%2F-MbHdEabkqwq1Igu9AC5%2F-MbHgIgCB2XOuZmHLA6H%2Fimage.png?alt=media\&token=168eec8a-3001-470f-b339-f21daad47ad7) ![](https://gblobscdn.gitbook.com/assets%2F-MPHoF2HwOA0s5HV_AIB%2F-MbHdEabkqwq1Igu9AC5%2F-MbHfJD7-KiXfb3TBEz6%2Fimage.png?alt=media\&token=b02dc97f-99fa-48d9-94d4-c98ef8f4719a) #### Open ID Application Configuration Gather the Client ID and secret as well as the necessary endpoints found within the [**well-known** ](#how-do-i-find-my-uri-endpoints)endpoint for your application. ![](https://gblobscdn.gitbook.com/assets%2F-MPHoF2HwOA0s5HV_AIB%2F-MbHdEabkqwq1Igu9AC5%2F-MbHhY_XfB7mZkBl9O9Z%2Fimage.png?alt=media\&token=ded09e8f-6fe1-4497-a6df-8a252f353979) ``` https://dev-abcdefghij.us.auth0.com/.well-known/openid-configuration ``` ``` { "issuer": "https://dev-abcdefghij.us.auth0.com/", "authorization_endpoint": "https://dev-abcdefghij.us.auth0.com/authorize", "token_endpoint": "https://dev-abcdefghij.us.auth0.com/oauth/token", "device_authorization_endpoint": "https://dev-abcdefghij.us.auth0.com/oauth/device/code", "userinfo_endpoint": "https://dev-abcdefghij.us.auth0.com/userinfo", "mfa_challenge_endpoint": "https://dev-abcdefghij.us.auth0.com/mfa/challenge", "jwks_uri": "https://dev-abcdefghij.us.auth0.com/.well-known/jwks.json", "registration_endpoint": "https://dev-abcdefghij.us.auth0.com/oidc/register", "revocation_endpoint": "https://dev-abcdefghij.us.auth0.com/oauth/revoke", "scopes_supported": ["openid", "profile", "offline_access", "name", "given_name", "family_name", "nickname", "email", "email_verified", "picture", "created_at", "identities", "phone", "address"], "response_types_supported": ["code", "token", "id_token", "code token", "code id_token", "token id_token", "code token id_token"], "code_challenge_methods_supported": ["S256", "plain"], "response_modes_supported": ["query", "fragment", "form_post"], "subject_types_supported": ["public"], "id_token_signing_alg_values_supported": ["HS256", "RS256"], "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"], "claims_supported": ["aud", "auth_time", "created_at", "email", "email_verified", "exp", "family_name", "given_name", "iat", "identities", "iss", "name", "nickname", "phone_number", "picture", "sub"], "request_uri_parameter_supported": false } ``` #### Form.io Project Configuration Navigate to the Form.io Project the Form Manager application is connected to. Navigate to the **Authorization** > **OAuth** > **OpenID** settings. ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FTpezWP8zwdGrYh5jV2A3%2Foauth16.png?alt=media\&token=ec4ed57b-3e03-402e-838d-b6a01d5d4743) Apply the information from the OIDC application and **well-known** endpoint. ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F83Nf2UpCYv71JuJ9g4Om%2Foauth17.png?alt=media\&token=be4d6c19-dad5-4c22-96b3-357118945dc0) #### Setting Up OpenID Login Button 1. Within your Project, navigate to the **Admin** Login form. 2. Add a **Button Component** * Select the **OAuth** action * Select the **OpenID** provider * Save settings. ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FqMVZdNyXpwg6tGOnmGit%2Foauth18.png?alt=media\&token=54cee414-2fb0-47d3-8e73-4dfb23255f7c) 3. Navigate to the **Action** tab and add the **Oauth** Action. ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F4WpSf1fao1HKne6bilHG%2Fadminlogin.jpg?alt=media\&token=c5430375-fe87-4130-8dfb-8368c44e0db6) 4. Configure the **OAuth** action * Select your **OAuth** provider * Select the **Remote** **Authentication** Action * Select the **SSO** button within the Admin login form * Since the Form Manager requires Administrative users, select the **Administrator** Role ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FANDtivSC7KLxrvogyPh7%2Foauth20.png?alt=media\&token=94d4bbca-6d24-43e6-b9df-87bf18df6acd) #### **Workflow Testing** 1. Launch the **Form Manager** application 2. Click the **Login with OIDC** button 3. Enter your **OIDC** User **credentials** ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FQ57LxKvhUwBWkZo0IJj6%2FFormManagerlogin.jpg?alt=media\&token=220fba26-0a5c-4380-b3ae-4ec4a16ed261) You should authenticate into the Form Manager application

[^1]: The URL to which Auth0 redirects users after they authenticate from the Allow Origin domain Other terms for the Callback: Redirection URI Redirection URL Redirect URI Redirect URL Callback URI [^2]: authorization\_endpoint [^3]: token\_endpoint [^4]: userinfo\_endpoint [^5]: