# Portal SSO

## Introduction

After deploying the environment and enabling the [**Deployed Portal**](https://help.form.io/deployments/deployment-guide), also referred to as the Form.io *Developer Portal*, your next objective might be to utilize Single Sign-On (SSO) to authenticate the environment users into the deployed Developer Portal interface.

This is done by setting up a SAML or OIDC authentication application and integrating the provider into your [**Portal Base Project.**](https://help.form.io/deployments/portal-base-project)

{% hint style="info" %}
The **Portal Base Project** is used to manage Administrative / Portal Users, Teams, and Authentication for the **deployed** **environment**. \
**DO NOT build** an application from this project or add additional forms to it. Instead, go to the home page and create a new project.
{% endhint %}

There are two primary SSO authentication methods for accessing the Developer Portal. Visit one of the Provider documentation links below for details on application setup and integration with the Form.io Project. 

* [**SAML**](https://help.form.io/developers/auth/saml#introduction) **SSO**  
* [**OIDC**](https://help.form.io/developers/auth/oauth#remote-authentication-sso) **SSO**

## SAML Authentication

Modify the Portal Base User Login form to enable SSO authentication for SAML users accessing the Developer Portal. Before this workflow can be established, ensure you have your [**SAML Applicaiton**](https://help.form.io/developers/auth/saml#introduction) properly configured within the Portal Base Project. 

### SAML SSO

Ensure a [**SAML Provider** ](https://help.form.io/developers/auth/saml#introduction)has been properly configured within the Portal Base Project.

{% embed url="<https://www.loom.com/share/bb9b8b27c8aa47978f1747de9abbc18e>" %}

#### **Form.io Integration Settings**

1. Navigate to the [**Portal Base Project** ](https://help.form.io/deployments/portal-base-project)

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F6ogLked0rJb3l9Xx8Jgq%2Fportalbase.jpg?alt=media&#x26;token=0a5ccfc5-4e56-4b2a-9a91-1db966427a55" alt=""><figcaption></figcaption></figure>

2. Navigate to the **OAuth** **settings** of your Portal Base Project and ensure the provider credentials have been properly configured\
   **Settings > Authorization > Oauth**

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FsXGf9sopj2lW7IrfqpTi%2Fspaces_-MPHoF2HwOA0s5HV_AIB_uploads_ywaOATjkZv158Riq7BYt_oauth1.webp?alt=media&#x26;token=6d096c30-98db-4f84-9504-284e455a5774" alt=""><figcaption></figcaption></figure>

3. Ensure the correct SAML Roles are properly mapped to the correct Form.io Role

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FUiemnMrECH6HqVAv9lDP%2FSamlRole.jpg?alt=media&#x26;token=4affa875-ac57-4aae-80f9-607ff95f32b8" alt="" width="528"><figcaption></figcaption></figure>

#### **Login Form Configuration**

Follow the steps below to achieve SAML SSO authentication using a Form.io Login form.

1. Edit the authentication Form embedded within your application
2. Drag and drop a **Button** component&#x20;
3. Modify the **Label** to reflect SAML authentication
4. Click the **Action** dropdown and select **Custom**&#x20;
5. Copy the following code and paste it into the **Button Custom Logic** code block

```javascript
Formio.ssoInit('saml');
```

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FlAWhhaQCpLF1PVWNzpbI%2Fbuttonsettings.jpg?alt=media&#x26;token=7d946b39-8793-4715-b3eb-40962724a88d" alt="" width="563"><figcaption></figcaption></figure>

6. Add a **Hidden** component&#x20;
7. Click the **Data** tab and open the **Custom Default Value** tab
8. Add the following **JavaScript** within the code block
9. **Save** the Settings and Form

```javascript
if (Formio.pageQuery().saml) {
  Formio.ssoInit('saml');
  window.location.replace('/');
}
```

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FVYGeQg9FRW0DZUMpTcoM%2Fsamllogic.jpg?alt=media&#x26;token=4ed8e492-ec31-410c-a9d1-099a41cdc3b6" alt=""><figcaption></figcaption></figure>

#### Authentication Test

1. Navigate to the Form.io deployed environment **Authentication** page
2. Click the **SSO** **with** **SAML** button
3. The **SAML** **Provider** authentication page should display
4. Enter the OIDC User **credentials**&#x20;

The SAML User should authenticate into the deployed portal environment with their assigned Form.io Role.&#x20;

### **SAML Automic Login**

The Automatic Login authentication method will perform a login via SAML SSO as soon as the SAML User navigates to the authentication page of the Deployed Portal. This relieves the user from having to interface with the Login form and click additional buttons to authenticate into the Portal.

{% embed url="<https://www.loom.com/share/615d3fb9540e450d94e63d854d1b2055>" %}

{% hint style="info" %}
Because this method bypasses the login page, you will no longer have the ability to log into the portal application as the Super Admin created during the deployment process. The Super Admin utilizes the following credentials set within the deployment environment variables:\
`ADMIN_EMAIL: admin@example.com` |`ADMIN_PASS: CHANGEME`
{% endhint %}

To enable Automatic SSO login to your developer portal, you will need to first ensure your **SAML** **SSO** **Provider** **Integration** settings have been configured within the **Portal Base Project.** The **User Login Form** within the Portal Base Project will then be modified to support the automatic SAML login integration.

#### **Login Form Configuration**

1. Navigate to the **User Login Form** within the **Portal Base** project
2. Drag a **Hidden** component to the form
3. Configure the **Label** (for ex. *samlAutoLogin*)
4. Go to the **Data** tab and under **Persistent** configuration choose '**None**'
5. Scroll down to the **Custom Default Value** section and insert this code:

```
if (!instance.builderMode && !Formio.disableAutoLogin && !Formio.pageQuery().disableAutoLogin) {
  Formio.ssoInit('saml');
}
```

6. **Save** the component and the form

#### **Workflow Testing**

Navigate to your environment endpoint. If you have already authenticated into your SAML provider, you should automatically log in to the environment. If you have not yet authenticated, you should be prompted to enter your SAML credentials and then authenticate. When logging out, the SAML user should be redirected to the SAML provider authentication page.&#x20;

#### **Disabling Automatic SSO Authentication**

Since Automatic SSO Authentication bypasses the Login form, you will be unable to log in as the Super Admin for the environment. This is necessary when needing to make modifications to the Portal Base Project.&#x20;

To temporarily bypass the authentication method, pass the *disableAutoLogin=true* URL query parameter within your browser.&#x20;

```
http://localhost:3000/?disableAutoLogin=true
```

Alternatively, if you're already authenticated into the environment, set *Formio.disableAutoLogin=true* from within the DevTools console

## OIDC Authentication

Modify the Portal Base User Login form to enable SSO authentication for SAML users accessing the Developer Portal. Before this workflow can be established, ensure you have your [**OIDC Application**](https://help.form.io/developers/auth/oauth#oauth-application-setup-overview) properly configured within the Portal Base Project.&#x20;

### OIDC SSO

Ensure your [**OIDC Provider**](https://help.form.io/developers/auth/oauth#oauth-application-setup-overview) is properly configured within the Portal Base Project.

{% embed url="<https://www.loom.com/share/ce8fa9a679194e5eba8d461b4e3cf909>" %}

1. As an environment Admin, navigate to the [**Portal Base Project** ](https://help.form.io/deployments/portal-base-project)

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FICVhjhVAYP9bTFtn1bw8%2Fportalbase.jpg?alt=media&#x26;token=f5ff5ba9-8ecd-48b0-b540-7f533ddfb08c" alt=""><figcaption></figcaption></figure>

2. Edit the **User Login** form
3. Add a **Button** component called **SSO with OIDC** and configure the following settings
   * Set the **Action** to **OAuth**
   * Set the **OAuth** **Provider** to **OpenID**

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FXlrcZVAMm0vYKOPWnFr8%2FOIDCSSOButton.jpg?alt=media&#x26;token=9cc19580-38bc-4492-924e-5513160e1326" alt="" width="563"><figcaption></figcaption></figure>

4. Click the **Actions** tab and add the **OAuth** action
5. Within the OAuth action, configure the following settings
   * Set **OAuth Provider** to **OpenID**
   * Set **Action** to **Remote Authentication**
   * Set **Sign-In With OAuth Button** to the SSO Button - **SSO with OIDC**
   * If you are not delegating OIDC Roles, leave the **Claim** and **Value** setting blank and select a Form.io role you want to assign the user. The following configuration will delegate every OIDC user logging in to carry the Form.io Authenticated role.

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FIht7oiy5JKAG5RmkOpIe%2Fssoaction.jpg?alt=media&#x26;token=5ae347d0-098d-4951-82d9-e8ec433f30ea" alt=""><figcaption></figcaption></figure>

*Optional* - If you are delegating Claims, ensure you set the Claim and related Value within your Project settings and OAuth action. \
In the example below, the OIDC provider utilizes the 'groups' claim (found within the support scopes). The Value is the OIDC Role name the OIDC User is associated with. You can then map these OIDC roles to a Form.io role enabling granular permissions.&#x20;

{% hint style="info" %}
OIDC provider claims and values may differ between providers. Ensure you check your OIDC provider's 'well-known' to see a list of supported claims.&#x20;
{% endhint %}

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FUyog5143gwnb3BejiDEi%2Foauthclaims2.jpg?alt=media&#x26;token=626ee0ca-530a-4200-af1f-b7510761ff20" alt=""><figcaption></figcaption></figure>

Your Login form should look something like this

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F1llxqxOgd0TtDKorAVp6%2Fuserlogin.jpg?alt=media&#x26;token=496ae18e-a314-4a8f-a91b-dc2d203ea5e5" alt=""><figcaption></figcaption></figure>

6. Navigate to your Applications authentication page and click the **SSO with OIDC** button. \
   You should be prompted to enter your OIDC credentials&#x20;

The authenticated OIDC user should carry the OIDC Group Role (Member) as well as the correct Form.io Role ID (Authenticated 65de..) within the metadata of the user object. This was accomplished in the previous step by mapping the OIDC group role to the Form.io Role configured within the OAuth action.

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FjygSzctqIuSEPxTFMi31%2Foidcremoteuserobject.jpg?alt=media&#x26;token=a759ee35-f017-4cc2-b6c5-daaee33eb277" alt="" width="563"><figcaption></figcaption></figure>

## **SSO Teams For The Deployed Portal**

SSO Teams relieve the need to manually add individual SSO Users to a Team.  Instead, during the SSO authentication process, OIDC groups associated with OIDC users are automatically linked to a Team if the Form.io Team name matches the OIDC Group name.&#x20;

{% hint style="info" %}
See [**SAML** **Group**](https://help.form.io/developers/auth/saml#create-and-assign-groups) or [**OIDC Group**](https://help.form.io/developers/auth/oauth#create-and-assign-groups) examples for more information
{% endhint %}

Depending on the SSO Provider, it may be necessary to configure the Group 'Claim' parameter within the provider's configuration. This will ensure the SAML Role associated with the authenticating SAML user is returned to Form.io so it can be mapped to a Form.io role.

#### Enabling SSO Teams Within Your Environment

Before an SSO Team can be created, the feature will need to be enabled for your environment. To do so, add the following within your deployment API server [**Environment Variables**](https://help.form.io/deployment-guide/enterprise-server#environment-variables).

```
SSO_TEAMS=true
```

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FUy4pWD7LbeT063WCLntl%2Fssoteamvariable.jpg?alt=media&#x26;token=04792a70-4df4-4af5-9edc-e89fe4007e11" alt=""><figcaption></figcaption></figure>

#### SSO Team Creation

1. After enabling the variable
2. Create a new **Form.io Team** from the Developer Portal
3. Check the new **SSO Team setting** checkbox:\
   This setting will communicate to the API server this should be an SSO Team.&#x20;
4. The **Team Name** should match the **Group** associated with the SAML User

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F3MRVZKw1UYglStcUV5OI%2Fsso2.png?alt=media\&token=a02f5819-01b7-417c-a5f0-74615adc0794)

#### SSO Team Project Assignment&#x20;

Next, you will need to assign that Team to the projects you wish to allow SSO users to have access to within the Form.io developer portal interface.&#x20;

{% hint style="info" %}
[**Read More**](https://help.form.io/userguide/teams) about Teams and different permission settings that can be granted
{% endhint %}

1. Navigate to the project you wish to provide access to
2. Click the **Teams** within the Projects navigation bar
3. &#x20;Select the role you wish that team to have within the given Project.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FPkcCeMxfvnHrrxNBGx5h%2Fsso4.png?alt=media\&token=2cba33ca-d8ea-496c-9984-128197fe4dba)

After this is set up, anyone with a **SAML** or **OIDC** Role/Group name matching the Team's name will be automatically assigned to that team and granted access to the project

These Users will have access and permissions to Project(s) the SSO Team has been assigned to.&#x20;

## Form Manager SSO

To enable the [**Form Manager**](https://help.form.io/userguide/manager) with SAML SSO authentication, you will need to first navigate to your project, and just like you did for the Portal Base project above, configure this project with the same SAML configuration.&#x20;

**Important:** Make sure that you configure a separate SSO application within your SAML provider to use the correct project URLs instead of using the same SAML configuration provided in the previous step.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FOVW4rbKyLkww7GirWAFF%2Fsso1.png?alt=media\&token=6c10fe91-e3dc-4ef4-a11f-ff2872abe506)

After you do that, you will now need to provide the SSO configuration within your project's **Public Configuration** section.

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2Fw0sK7nXJIXDmEopqW01T%2Fsso3.png?alt=media\&token=a40a84fc-c93d-471b-80bc-6a4857631c20)

For a description of all Configurations available go to the [**Form Manager Settings**](https://help.form.io/userguide/form-manager#form-manager-configurations) documentation.

## Other OIDC Authentication Methods

Aside from SSO, OIDC can also link or create user within a Form.io Resource. Below are additional OIDC authentication methods for deployed portal users:

* [**User Registration** ](#user-registration-with-oidc)- Creates a new user record within a Form.io Resource by utilizing the user credentials from the OAuth provider.&#x20;
* [**User Login**](#user-login-with-oidc) - Utilizes the remote OIDC User authentication to locate a Form.io user record within a resource to establish authentication.&#x20;
* [**User Link**](#user-link-with-oidc) - This will "link" an external OIDC user entity with an existing Form.io user record.

Each of these methods can be used to establish a variety of authentication strategies within the Form.io platform. To achieve this within Form.io, an OIDC provider must be established first. Once OIDC has been set up, credentials generated from the provider will be integrated into the Form.io project. Modifications of your Form.io authentication forms will be necessary to establish the final connection between your forms and the OIDC provider.&#x20;

**Preconditions** for the authentication method examples:

* Ensure the Project is configured to support your OIDC Provider
* The following default forms that are created with a Form.io project are being utilized:\
  User Login Form\
  User Registration Form
* The Registration and Login Forms are being mapped to the default User Resource

### User Registration with OIDC

The OIDC User Registration method allows OIDC Users to register their accounts using Form.io, saving their OIDC User record within a Form.io Resource. Most Form.io Projects come with a User Register form by default which will be modified in this example to support OIDC registration.&#x20;

In this example, the User Registration form is embedded within my application to enable SSO registration that will save to the **User Resource** within my project.&#x20;

{% hint style="info" %}
It's important to note that this workflow does not register a user with an OIDC provider, but rather registers an OIDC user within the Form.io Project. This registration can be applied to the[ **Portal Base Project**](https://help.form.io/deployments/portal-base-project) within your deployed environment or for a connected application.&#x20;
{% endhint %}

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F6aroJZo48XjXBLNIUJJK%2Foauth3.png?alt=media\&token=114dff0f-9b41-4d6b-b928-4fde2ec25a49)

#### Registration Form Modifications&#x20;

1. To get started, navigate to your Project and edit the **User Registration** For&#x6D;**.**
2. Add a **Hidden** field called **Email** and a **Hidden** field called **Name**
3. Add a **Button** called Register with OIDC and modify the following **settings**
   * Set a **Label** for the button like **Register** **with** **OIDC**
   * Set the **Action** to **OAuth**
   * Set the **OAuth Provider** to **OpenID**

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FllQ11xNM8lw6PMPYq78Z%2Foidcregistration.jpg?alt=media&#x26;token=544ccbf5-129d-4de4-a32b-2e559b5feba3" alt=""><figcaption></figcaption></figure>

#### OAuth  Action

This action will integrate the OIDC Provider and map the provider claims to the User Resource within the Form.io Project.&#x20;

4. Add an [**OAuth** **Action**](https://help.form.io/userguide/forms/form-building/actions#oauth) to the Registration form and modify the following **settings**
   * Set **OAuth** Provider to **OpenID**
   * Set **Action** to **Register New Resource**
   * Set **Resource** to **User**
   * Set **Sign-in with OAuth Button** to **Register With OIDC**

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FL9WXXLTRJ4YbCy3Y4DyB%2FOIDCOAuthRegistration.jpg?alt=media&#x26;token=c8615a9a-7238-46ac-8469-8ddf8bceeaf5" alt=""><figcaption></figcaption></figure>

* Set the **OAuth Callback URL** to your application Domain

#### **Map Claims**

These settings will dictate what information from the OIDC User scope should be saved with the Registration record. Since the data input will be done on the OIDC authentication page, no physical fields on the form are needed. The **hidden** **email** and **name** field will be used to map the email and name from the OIDC User scope to the submission object.&#x20;

* Set the **Claim** to **email** and select the **Email** field
* Set the **Claim** to **name** and select the **Name** field
* **Save** the Action

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FZ09fzgm1KZQgrNagNuaL%2FOauthclaims.jpg?alt=media&#x26;token=a5ae45c6-97de-4809-a909-c67fdbae295c" alt=""><figcaption></figcaption></figure>

#### Save Submission Action

Now that the OAuth settings have been mapped to the User Resource, a Save Submission action will be added to ensure the data submitted against the Registration form is stored within the User Resource.&#x20;

5. Add a **Save Submission** Action and configure the following settings
   * Set the **Save Submission To** field to the **User** Resource
   * Map the **Name** and **Email** field on the form to the corresponding fields on the **User** Resource

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FAk002gjxxsvN5w1diQBU%2FOAuthResigstrationSaveSubmission.jpg?alt=media&#x26;token=d13b0d44-2821-43ec-832a-a883b266290b" alt=""><figcaption></figcaption></figure>

After saving the Action, our Registration form should look like this

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FoInPMg5cgQiwN6cJ4gBy%2Foauth5.png?alt=media\&token=551732be-754d-47e7-a698-373c6269d536)

#### Registration Workflow Testing

With the Registration form modified, we are now ready to test the workflow.&#x20;

1. Navigate to your application's registration page
2. Click the **Register with OIDC** button and enter the **OIDC** **User** **credentials**&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FYxwfFVDaIMlEK9DQkHQa%2Foidcregistrationworkflow.jpg?alt=media&#x26;token=940e97a2-747f-4639-8d13-af418016231a" alt="" width="358"><figcaption></figcaption></figure>

3. Navigate to the **User** Resource **Data** tab within the Project and ensure a User record was generated based on OIDC User registration.

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FVhaUYGrDItYNVPq3ft8K%2FOIDCregistartionuserrecord.jpg?alt=media&#x26;token=8e711252-fc68-4187-b0a0-43aa92b40272" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
When embedding the form into the renderer, append "?live=1" parameter at the end of the form embed url to allow for the OAuth action to trigger properly
{% endhint %}

### User Login with OIDC

This Authentication method will utilize OIDC User credentials to log in a User that has been saved within the User Resource of the Form.io Project. The OIDC User and Form.io User record must be  '[**Registered**](#user-registration-with-oidc)' or '[**Linked**](#user-link-with-oidc)' using the OIDC methods detailed within this documentation to establish a proper connection.&#x20;

Once these conditions have been met, the User Login form can be configured to authenticate the OIDC User against the User Resource within the project.&#x20;

#### **User Login Modification**

1. Edit the **User Login** form within your Project
2. Add a **Button** component called **Login with OIDC** and configure the following **settings**
   * Set a **Label** for the button like **Login** **with** **OIDC**
   * Set the **Action** to **OAuth**
   * Set the **OAuth Provider** to **OpenID**

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2Fq4lR2nIR8JPY6QJlBLMl%2Fuserloginoidcbutton.jpg?alt=media\&token=5ded0a74-26c6-47ca-b008-6818bec87c42)

3. Add an [**OAuth** **Action**](https://help.form.io/userguide/forms/form-building/actions#oauth) to the Registration form and modify the following **settings**
   * Set **OAuth** Provider to **OpenID**
   * Set **Action** to **Register New Resource**
   * Set **Resource** to **User**
   * Set **Sign-in with OAuth Button** to **Register With OIDC**

Now click **Save** and our form is now configured for Login using OIDC!

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FPHo25V6JfGsKLZCBDixb%2Floginwithoidcaction.jpg?alt=media&#x26;token=8ed3804a-b2e5-42cd-9fd8-0e45d0b26d45" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
When embedding the form into the renderer, append "?live=1" parameter at the end of the form embed url to allow for the OAuth action to trigger properly
{% endhint %}

#### Workflow Testing

With the Registration form modified, we are now ready to test the workflow.&#x20;

1. Navigate to your application's login page
2. Click the **Login with OIDC** button and enter the **OIDC** **User** **credentials**&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FViNI0RjF3kGVilKcM0Q4%2Foneloginuilogin.jpg?alt=media&#x26;token=d42605f9-335f-4eac-90db-8d631c547ae8" alt="" width="343"><figcaption></figcaption></figure>

The same user created using the [**OIDC User Registration**](#workflow-testing) method is now authenticated into the application.

{% hint style="info" %}
This example can be followed for your client application or for SSO into the Form.io Developer Portal.&#x20;
{% endhint %}

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FFBWhxfYtCUr0LeH2hsoY%2Floginoidcportal.jpg?alt=media&#x26;token=c2a99e6b-0efc-4719-b8e0-5f889fc12b67" alt=""><figcaption></figcaption></figure>

### User Link with OIDC

This authentication method will "link" an external OIDC user entity with an existing Form.io user record.  This method requires custom code within your application to properly link the user records with the OIDC user.&#x20;

1. Create a Form called **Link User**
2. Edit the **Submit** Button and modify the following settings:
   1. Set the **Action** to **OAuth** and the **Provider** to **OIDC**
3. **Embed** the form somewhere in your application where only authenticated users can access it, like a user settings page.&#x20;
4. Add custom logic within the Application to hide the form for users who have already logged in. Specifically, check if the user has an `externalIds` entry for your provider. Here is some sample code that will check if the user has been linked with GitHub using the [formio.js](https://github.com/formio/formio.js) library:

```
var isLinkedToGithub = false;

Formio.currentUser().then(function(user) {

    if(!user) {
        return;
    }

    user.externalIds.forEach(function(id) {
        if(id.type === 'github') {
            isLinkedToGithub = true;
        }
    });

    if(isLinkedToGithub) {
        // Hide form here
    }
});
```