Refer Strings

Overview

A refer string is a method of authentication in Unqork. With a refer string, you can grant end-users access to your application—even if they don't have an account.

You've probably come across refer strings without knowing it. Think of an email that contains a registration link. That link takes you to a site you otherwise have to log in to view. If that's the case, the link contains a refer string to grant you access.

To use a refer string, you add it to a URL that directs your end-user to your application. When your end-user visits that URL, they gain access without any further action needed. You also have the option of limiting each refer string to a single use for added security. Let's take a closer look at generating refer strings in Unqork.

What You'll Learn

In this article, you'll learn:

• What a refer string is.

• How to generate a refer string.

What is a Refer String?

Refer strings are an easy way to authenticate users and grant access to your application. A refer string grants your end-user access with a single button-click. To do that, you first set a few parameters in a Plug-In component. Those parameters include:

Parameter	Description
userId	This is a unique ID of your choosing. If you're redirecting to an external platform, you can use a user ID recognized by that platform.
expireOffset	A numerical value that works with expireMeasure (below) to set an expiration window. For example, if you want the refer string to be valid for 7 days, your expireOffset is 7. The maximum offset is 30 days.
expireMeasure	A unit of measure that works with expireOffset (above) to set an expiration window. For example, if you want the refer string to be valid for 7 days, your expireMeasure is days. The maximum offset is 8 days.
oneTimeUse	Limits the refer string to one use when set to true. TIP  Best practice is to limit refer strings to one time use whenever possible. Doing so drastically increases the security of your application.
additionalParams	Anything else that you want to include in your refer string. For example, you can assign a specific role to the user when they reach their target platform.

NOTE  As with any API (application programming interface) call, it's important to check the documentation during configuration. A refer string API call is an internal API call, so you can find the documentation here: https://developers.unqork.io/#operation/generateReferString.

Your Plug-In component uses these parameters to make an API call. The result is an encrypted string that contains your parameters. But that string on its own isn't useful unless it's combined with a larger URL. To refer your end-user to your application, use the following URL format:

<hostname>?refer=<referstring>/#/display/<moduleID>

When your end-user visits this URL, Unqork authenticates them using the refer string. Your end-user doesn't have to do anything else.

Refer String Models

You have two models when configuring a refer string endpoint call. No matter which model you use, it's important that you (or another designer) always set the parameters yourself. They should never be set by your end-users. For example, you don't want an end-user to generate a refer string with any role they pass through as a parameter. Here's a breakdown of each model:

• Direct: You set the parameters and generate the refer string using a single module. This method uses Hidden components placed directly in the Module Builder.

• Proxy: You set the parameters in one module and pass them to a second module to generate the refer string. This method uses a server-side executed module for added security.

NOTE  While similar, the Direct Model uses one module where the Proxy Model splits the process across two or more modules. You can see a sample configuration of the Proxy Model here: https://training.unqork.io/#/form/5ea0832e853d3d020eb5347e/edit. This article walks you through a use case for the Direct Model.

Say you want to grant your end-user access to the following module: https://trainingx.unqork.io/#/display/5e9f83275349fc020f8db299. If they visit that URL while logged out of the Unqork Training environment, they see the login screen. But if you add a refer string to that URL, the end-user gains access right away. To do this, you configure an API call to generate the refer string and add it to the module's URL.

NOTE  For demonstration purposes, the result of this use case displays the refer string both on its own and as part of the larger URL using Text Fields.

This is what your module looks like in the Module Builder:

NOTE  This example uses sample module ID 5e9f83275349fc020f8db299 in the Unqork Training environment as a destination. If you're building out this use case in the Training environment itself, you need to log out to test the refer string functionality.

What You'll Need

To set up this use case, you need:

• 4 Hidden components
• 1 Calculator component
• 1 Initializer component
• 2 Text Field components
• 1 Plug-In component
• 1 Button component
• 1 Decisions component

Configuration

Configure the Hidden Components

To set your parameters, use 4 Hidden components and an Initializer component. These Hidden components store your User ID, Role, Expire Measure, and Expire Offset parameter values. Later, an Initializer component sets these values with each New Submission.

1.

Drag and drop 4 Hidden components onto your canvas.

2.

Enter the following Property IDs and Label Text fields:

3.

Save each component as you add it.

Configure the Calculator Component

To set the expireOffset parameter, add a Calculator component. This lets you easily update how long the refer string should stay valid. If you need to change the expiration window, update this Calculator component.

1.

Drag and drop a Calculator component onto your canvas. Place your Calculator below your Hidden components.

2.

Enter calcOffset as the Property ID and Label Text fields.

3.

In the Outputs table, enter the following:

4.

Click Save.

Configure the Initializer Component

Next, add an Initializer component. On each new submission, this Initializer:

• Sets the User ID, Role, and Expire Measure. It also triggers the calculator for your Expire Offset. These are the same parameters that you referenced in your Hidden components earlier.

• Triggers the pluginCreateReferString Plug-In component. This Plug-In calls your refer string API endpoint.

1.

Drag and drop an Initializer component onto your canvas. Place the Initializer above your Hidden components.

2.

Enter initParameters as the Property ID and Label Text fields.

3.

Select New Submission from the Trigger Type.

4.

In the Outputs table, enter the following:

5.

Click Save.

Configure the Text Field Component

Because a refer string is the result of an API call, you need to set up a place to hold the result of that call. Add a Text Field component to do that.

1.

Drag and drop a Text Field component onto your canvas. Place your Text Field below your Calculator component.

2.

Enter referString as the Property ID field.

3.

Enter Refer String as the Label Text field.

4.

Click Save.

Configure the Plug-In Component

Now that you have parameters and an output set, add a Plug-In component. This component calls the refer string API endpoint.

1.

Drag and drop a Plug-In component onto your canvas. Place your Plug-In above your Text Field component.

2.

Enter pluginCreateReferString as the Property ID and Label Text fields.

3.

In the Inputs table, enter the following:

4.

In the Outputs table, enter the following:

5.

Select Generates an encrypted referstring for authentication from the Internal Services drop-down. The Request Type and Data Source URL auto-populate.

6.

Click Save.

Configure the Decisions Component

Remember, a refer string on its own is not all that useful. So, you need to put the refer string into a URL your end-user can actually navigate to in the browser. So, you can use a Decisions component configured with a Concatenate formula to put the pieces together.

1.

Drag and drop a Decisions component onto your canvas. Place your Decisions component below your Text Field component.

2.

Enter ruleURL as the Property ID and Label Text fields.

3.

In the Inputs table, enter the following:

4.

In the Outputs table, enter the following:

5.

In the Micro Decisions table, enter the following into the first row:

6.

Click Save.

Configure the Text Field Component

Finally, to hold your full URL, add a second Text Field component.

1.

Drag and drop a Text Field component onto your canvas. Place your Text Field component below your Decisions component.

2.

Enter referURL as the Property ID field.

3.

Enter URL with Refer String as the Label Text field.

4.

Click Save.

5.

Save your module.

With the above steps complete, your module generates a unique refer string for each new end-user. That string displays in the referString Text Field component. You also see the full concatenated URL in the second Text Field component like this:

You can test your work by copying the URL and logging out of the Training environment. Then, paste the full URL into your browser. You gain access to the module immediately. For comparison, the URL without the refer string is https://trainingx.unqork.io/#/display/5e9f83275349fc020f8db299. If you visit this URL while logged out, you see the login screen. If you need to test the API call portion of the lab again, log back into the Training environment.

Lab

You can find the completed Refer String use case here: https://training.unqork.io/#/form/5f43f4158cf0890219abfd35/edit.