Portal SSO

Introduction

After deploying the environment and enabling the Deployed Portal, 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.

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.

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 SSO

• OIDC 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 properly configured within the Portal Base Project.

SAML SSO

Ensure a SAML Provider has been properly configured within the Portal Base Project.

Form.io Integration Settings

1. Navigate to the Portal Base Project

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

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

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

3. Modify the Label to reflect SAML authentication

4. Click the Action dropdown and select Custom

5. Copy the following code and paste it into the Button Custom Logic code block

Formio.ssoInit('saml');

1. Add a Hidden component

2. Click the Data tab and open the Custom Default Value tab

3. Add the following JavaScript within the code block

4. Save the Settings and Form

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

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

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

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.

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: [e-mail] |ADMIN_PASS: CHANGEME

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');
}

1. 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.

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.

To temporarily bypass the authentication method, pass the disableAutoLogin=true URL query parameter within your browser.

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 properly configured within the Portal Base Project.

OIDC SSO

Ensure your OIDC Provider is properly configured within the Portal Base Project.

1. As an environment Admin, navigate to the Portal Base Project

1. Edit the User Login form

2. Add a Button component called SSO with OIDC and configure the following settings

   • Set the Action to OAuth

   • Set the OAuth Provider to OpenID

1. Click the Actions tab and add the OAuth action

2. 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.

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.

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.

Your Login form should look something like this

1. Navigate to your Applications authentication page and click the SSO with OIDC button. You should be prompted to enter your OIDC credentials

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.

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.

See SAML Group or OIDC Group examples for more information

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.

SSO_TEAMS=true

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.

4. The Team Name should match the Group associated with the SAML User

SSO Team Project Assignment

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.

Read More about Teams and different permission settings that can be granted

1. Navigate to the project you wish to provide access to

2. Click the Teams within the Projects navigation bar

3. Select the role you wish that team to have within the given Project.

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.

Form Manager SSO

To enable the Form 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.

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.

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

For a description of all Configurations available go to the Form Manager Settings 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 - Creates a new user record within a Form.io Resource by utilizing the user credentials from the OAuth provider.

• User Login - Utilizes the remote OIDC User authentication to locate a Form.io user record within a resource to establish authentication.

• User Link - 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.

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.

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.

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 within your deployed environment or for a connected application.

Registration Form Modifications

1. To get started, navigate to your Project and edit the User Registration Form.

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

OAuth Action

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

1. Add an OAuth Action 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

• 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.

• Set the Claim to email and select the Email field

• Set the Claim to name and select the Name field

• Save the Action

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.

1. 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

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

Registration Workflow Testing

With the Registration form modified, we are now ready to test the workflow.

1. Navigate to your application's registration page

2. Click the Register with OIDC button and enter the OIDC User credentials

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

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

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' or 'Linked' using the OIDC methods detailed within this documentation to establish a proper connection.

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.

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

1. Add an OAuth Action 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!

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

Workflow Testing

With the Registration form modified, we are now ready to test the workflow.

1. Navigate to your application's login page

2. Click the Login with OIDC button and enter the OIDC User credentials

The same user created using the OIDC User Registration method is now authenticated into the application.

This example can be followed for your client application or for SSO into the Form.io Developer Portal.

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.

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.

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 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
    }
});