SSO Email Token

The SSO Token can be integrated inside an email action to authenticate a user into an application with a single click of a button. Email SSO Tokens are commonly used for things like Reset Password or User Registration workflows. This example however will detail how to use SSO tokens to authenticate a Manager user to review and approve employee expense reports.

Create Manage Role

Before establishing the SSO Token, there is some setup needed to facilitate the workflow. Since a new Manager user group will be established, a Manager role is required to be assigned to the user group.

1. Click the Access tab within your Project

2. Click the +New Role button

3. Title the Role Manager

4. Click Create Role

Create Manage Resource

The SSO token performs a lookup against a Resource in order to authenticate a user into the application. Next, create a Manager Resource inside the Form.io Project to facilitate the Manager users.

1. Within the Project, click the Resource tab

2. Click the +New Resource button

3. Title the Resource Manager

4. Add an Email and Password field

5. Click the Create Resource button

Add Role Assignment Action

Next, add the Role Assignment action to the Manager Resource. This will ensure the Manager Users will receive the Manager role when a Manager user is created.

1. Within the Manager Resource, click the Action tab

2. Select Role Assignment from the action dropdown and click +Add Action

3. Click the Resource Association dropdown and select New Resource

4. Click the Action Type and select Add Role

5. Click the Role dropdown and select the Manager Role.

6. Save the Action

Establish Manager User Group

Make a submission against the Manager Resource to establish the User group.

1. Open the Manager Resource

2. Click the Use tab

3. Make a submission to create a Manager account E.G. [e-mail] / abc123

Establish Employee User Group

The User Resource, which is automatically created within the Project, will be used to create the Employee users. This Resource already has an action in place to assign the Authenticated role to users submitted against this Resource.

1. Open the default User Resource

2. Click the Use tab

3. Make a submission to create an Employee user account E.G. [e-mail] / abc123

Create Expense Report Form

This Form will be submitted by the Employee Users and in turn, reviewed by the Manager via the SSO token.

1. Click the Form tab within the Project

2. Click the +New Form button

3. Title the Form Expense Report. Ensure the API Path for the form is expensereport

4. Add your own fields like a Text Field for the Expense and Currency field for the Amount

5. Alternatively, import the following Expense Report form into your project using the Import button from the form tab. https://examples-khvenypsypifjpi.form.io/expensereport

6. Click the Create Form button

Set Form Permissions

Set up the Permissions on the form to allow Employee Users to submit the form and Manager Users to read and update all submissions.

1. Open the Expense Report form

2. Click the Access tab for the form

3. Add the following Submission Data Permissions Create Own: Authenticated (Role assigned to the Employee Users) - Allows Employee Users to submit the form Read All: Manager - Allows Manager Users to view (read) all form submissions Update All: Manager - Allows Manager Users to update all form submissions

4. Remove the following Form Definition Access permissions Read Form Definition: Anonymous - Removing this permission will prompt the User to log in before viewing the form.

5. Save the settings

Create Email Action

The Email Action will fire off an email to the Manager whenever the form is submitted. This email will contain the SSO Token required to authenticate the Manager into the application, allowing the Manager to review the Expense Request.

Click Here to learn more about how SSO Tokens work

In order for the Email action to function, an Email Transport must be configured within your project.

Click Here for information on integrating an Email provider.

1. Within the Expense Report Form, click the Action tab

2. Select Email from the action dropdown and click +Add an action

3. Select the Email Transport

4. Add the email address to the To: Email Address field E.G. [e-mail]

5. Modify the Message field to include an SSO Token that will authenticate the Manager

https://pro.formview.io/?token=[[token(data.email=manager)]]#/project-domain/expensereport/submission/{{ id }}/edit

---

Here's a summary of how the SSO Token works:

https://pro.formview.io/

The Application domain the SSO token will authenticate the user into. In this example, we will be using the FormView Pro Application to test out the workflow.

token=[[token(data.email=manager)]]

The token will then search within the Manager resource and try to find a record that matches the Email data within the given Resource. If a match is found, a special JWT token will be generated.

/project-domain/expensereport/submission/

This is the , and the of the form the token will be authenticating the user into.

In order for the SSO token to function, you will need to modify the example URL to include your own Form.io project domain and ensure the expense report form endpoint is correct.

{{ id }}/edit

The Submission ID the SSO token authenticates the user into. The user will be viewing the submission in Edit mode when the SSO token is clicked.

---

You can also use HTML classes and the integrated Bootstrap library to customize the SSO link. Here’s an example of the SSO Token link within a button block:

<center><a class="btn btn-primary btn-block" href="https://pro.formview.io/?token=[[token(data.email=manager)]]#/project-domain/expensereport/submission/{{ id }}/edit">Review Expense Report</a></center>

Workflow Testing

With the SSO token in place, the next step is to test out the SSO workflow. The FormView Pro application will be used to help facilitate the workflow inside an application environment.

FormView Pro is an application integrated with the Form.io Project. It serves as a way for end users to consume and submit forms built and published within the Form.io platform.

Click Here to learn more

User Submission

Submit the Expense Form as an Employee user to trigger the Email Action containing the Manager SSO Token.

1. Navigate to the Expense Report form

2. Click the Launch tab

3. Click the Go To Form button to launch the form inside the application

4. Login using the User credentials submitted E.G. [e-mail] / abc123

5. Submit the form

Manager Review

At this point, the email action should be triggered containing the SSO Token for the Manager.

1. Check the email inbox for the Manager

1. Click the SSO Link to authenticate as the Manager and review the submission

SubmissionThe SSO Token will authenticate the Manager user to view and edit the Expense Report submission