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 SSO Authentication methods available for accessing the Developer Portal. You can opt for automatic login via Remote Authentication (SSO) or utilize the login form to authenticate a SAML or OIDC SSO User.

1. Automic Login Using SAML SSO This method will log in the SAML user automatically when the user navigates to the Portal environment based on their SAML authentication.

2. Login Form Authentication using OIDC or SAML This method modifies the User Login form to support a special SSO button that will prompt the user to enter their SAML or OIDC user credentials for authentication.

Please Note: The Automatic Login is supported with SAML only. For other Authentication Methods, utilize the SSO Login Form Authentication

SSO Provider Integration

Regardless of which Authentication method you are utilizing, the first step is to configure your SSO Provider and integrate it into the Form.io Portal Base Project. The Provider settings are added to the Portal Base Project by navigating to Settings > Authorization and choosing the OAuth > OpenID (OIDC) or SAML tabs.

Visit one of the Provider documentation links below for details on configuration:

SAML Single Sign-On

OIDC Single Sign-On

Developer Portal SSO using Automatic Login with SAML

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 content:

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.

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

Developer Portal SSO using Login Form Authentication

The second SSO Authentication method is modifying the Portal Base User Login form to support SSO authentication for OIDC or SAML users into the Developer Portal. Before this workflow can be established, ensure you have your SSO Provider Integrated properly within the Portal Base Project.

This approach offers the flexibility to employ both a Resource-based authentication method and SSO authentication by implementing a "Login with SSO" button on the User Login form. Follow the steps below to integrate SSO Authentication on the Login form using SAML or OIDC providers.

SAML SSO

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

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

2. Ensure the SAML Integration has been properly configured within your Authorization > SAML settings.

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

3. Edit the User Login form

4. Add a Button component and configure the following settings

   • Set the Action to Custom

   • Add the following code to the Custom Logic Formio.ssoInit('saml');

3. Add a Hidden component to the form

   • Click the Data tab

   • Add the following code to the Custom Default Value if (Formio.pageQuery().saml) { Formio.ssoInit('saml'); window.location.replace('/'); }

4. Navigate to the deployed environment Authentication page

   • Click the SSO with SAML button

   • The SAML Provider authentication page should display

   • Enter the OIDC User credentials

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

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

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

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.

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

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

Team Management

SSO Teams relieve the need to manually add individual SSO Users to a Team. Instead, during the SSO authentication process, roles associated with OIDC users are automatically linked to a Team if the Team's name matches the user role.

Dynamic SSO Team Mapping is coming soon for OIDC and is currently available for SAML

Depending on the SAML 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 Role 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.

Once you have done this, anyone with a SAML or OIDC Role (coming soon) name that matches the name of the Team will be automatically assigned to that team and be granted access to a 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.