Okta Single Sign On

With Form.io, you can configure your applications to work with the Okta Applications Single Sign On portal. This allows your Form.io Applications to be managed by the Okta application management system.

Create an Okta Application

The fastest way to get started with trying out Okta is to create a trial account by going to https://okta.com and then clicking on the “Try Okta” button.

This will walk you through a new Account creation which you can setup for your Organization.

Once you create a new Okta account, your first step will be to create a new application within the Okta interface. From your main dashboard page, go to the Admin section.

Now then click on Applications menu, and then click on the Add Application button.

Now click Create New App within the Applications section.

Within the Create Application modal, make sure to select Single Page App (SPA) from the Platform dropdown, and then click Create

In the next page, you will want to provide a title for your application, upload a logo, and then provide the Login redirect URIs to the URL of your hosted application. This is typically just the URL of your hosted application. If you are developing locally, then this can be the localhost URL of your application.

Now click the Save button and it will create your application.

Application Settings

Now that you have an application created, you will want to make sure to edit the General tab of this application, and then click on Edit button.

Within the General Settings of this new application, you need to change the Login initiated by dropdown to say Either Okta or App, and then click on both Display application icon to users and Display application icon in the Okta Mobile app

When you are done, your settings should look similar to the following.

Make sure to press Save button to save these settings.

Sign On Settings

After you have done this, you will now need to setup the Sign On credentials for the tokens generated by the OpenID connect. We need to ensure that the Groups are included within the tokens generated within the application. To do this, we need to go to the Sign On tab of your application.

Once you are on the Sign On section of your application, we need to click on the Edit button by the OpenID Connect ID Token section, and then we will need to change the following settings.

Setting Value
Groups claim type Filter
Groups claim filter: Claim Name groups
Groups claim filter: Type Regex
Groups claim filter: Value .*

When you are done, it should look like this.

Assignments

Now that you have the Sign On Settings configured, you need to click on the Assignments section, and then ensure you have added your groups to the application. You can do this by clicking on the Assign button, and then say Assign to Groups, and then in the next dialog select the groups you wish to assign to the application.

Note: If you wish to add new groups to your Okta, you can click on the Directory section and then click on Groups.

Make sure you take note of the names of these Groups that have been assigned since we will use this within our Form.io configurations to provide role mappings.

We are now ready to configure our Form.io project with our Okta configurations.

Form.io Project Configurations

Now that you have created your Okta application, you can now configure your Form.io Project settings to allow for integration between Okta and Form.io. We will use the OpenID Connect settings within your Project to make this configuration.

Within your Form.io project, click on Project Settings > Authentication > OAuth > OpenID and then provide credentials as follows.

You only need to fill out the following fields to get the SSO working.

Setting Description Example
Client ID Client ID provided by Okta within your App Settings 023ds0d2dslkef3sa0b9
User Info (claims) URI The Url to fetch the user information from Okta https://{{ ORGANIZATION_NAME }}.okta.com/oauth2/v1/userinfo
Roles (Claim) This is where you will provide your role mappings based on the Okta Group ID’s created within the previous section. Please see the image below for an example.

When you are done filling out this information, this should look like the following.

Make sure you press the Save Project button to save your project settings.

Form.io Application with Okta SSO

Now that we have configured both Okta and our Form.io project, the last step is to configure our application to accept the token handshake which will provide a single-sign-on between Okta and Form.io. This happens through a series of handshake events that occur within the application that is described below.

  • The user clicks on the application within the Okta Application protal.
  • This sends the user to the Okta Login Interface for them to login.
  • Once they are logged in, they are then redirected to the application with the tokens provided within the URL of the redirect.
  • The application will then take those auth tokens and store them within the local storage of the application for future authentications and allow for “refresh” of the application.
  • The Formio JavaScript SDK will then send the Okta Authentication Token to the Form.io Server to perform a Token Swap. This is done by sending a request to the /current endpoint with the Authorization: Bearer header which provides the Okta authorization token.
  • Now, within the Form.io Server, a request is made to the Okta servers “getinfo” API endpoint to fetch the user information including their groups.
  • From the Project configurations of group to role mappings, a new Form.io token is generated which contains the Form.io Roles that have been mapped to the Form.io Project Roles.
  • This new Form.io JWT token is then sent back to the application within the response of the /current API request within the x-jwt-token Response headers.
  • This new JWT token is stored as the Form.io token and then all requests operate as they normally do.

In order to create a login event, you will need to install our Formio.js core library. This can be done either with NPM or directly within your HTML page.

Using NPM

In your console, install formiojs library using the following.

npm install --save formiojs
npm install @okta/okta-auth-js --save

You will then need to put the following within your application.

import Formio from 'formiojs/Formio';
import OktaAuth from '@okta/okta-auth-js';

or

const Formio = require('formiojs/Formio');
var OktaAuth = require('@okta/okta-auth-js');

Within your HTML page

You can also include the Formio SDK within your application by including the following.

<script src="https://ok1static.oktacdn.com/assets/js/sdk/okta-auth-js/1.16.0/okta-auth-js.min.js" type="text/javascript"></script>
<script href="https://unpkg.com/formiojs@3.0.0-rc.11/dist/formio.min.js"></script>

Creating a Single-Sign-On with Okta.

You can now place the following code as one of the first scripts that is executed within your application.

Formio.ssoInit('okta', {
  url: 'https://formio.okta.com',
  clientId: '0oa2bshrAhgqeZb42333',
  redirectUri: 'http://localhost:3002/',
  scopes: ['openid', 'groups', 'profile']
}).then(() => {
  console.log('We are logged in!');
});

If you used the NPM method above, you will also want to ensure that you provide the OktaAuth class to the library as follows.

Formio.ssoInit('okta', {
  OktaAuth: OktaAuth,
  url: 'https://formio.okta.com',
  clientId: '0oa2bshrAhgqeZb42333',
  redirectUri: 'http://localhost:3002/',
  scopes: ['openid', 'groups', 'profile']
}).then(() => {
  console.log('We are logged in!');
});

AngularJS Integration

For AngularJS applications, you can use our helper library @ https://github.com/formio/ngFormioHelper to add Okta SSO into your application.

bower install --save ng-formio-helper

You will also need to include the OktaAuth library CDN within your index.html page as follows.

<script src="https://ok1static.oktacdn.com/assets/js/sdk/okta-auth-js/1.16.0/okta-auth-js.min.js" type="text/javascript"></script>

You will then need to add the FormioAuth provider to your application as follows.

angular
    .module('myApp', [
      'ngFormioHelper'
    ])
    .run([
       'FormioAuth',
       function(
         FormioAuth
       ) {
         // Initialize the FormioAuth handler.
         FormioAuth.init({
           oauth: {
             type: 'okta',
             options: {
               url: 'https://formio.okta.com',
               clientId: '0oa2bshrAhgqeZb42333',
               redirectUri: location.origin + location.pathname,
               scopes: ['openid', 'groups', 'profile']
             }
           }
         });
       }
     ]);