This article is also available in:
Third party authentication in Public Forms

In some cases you organization may require that Public Forms could only be launched by certain users, for example by your clients. In this case, the start of the process should be allowed only for those users who have authenticated on your website.
For these cases, Flokzu has the possibility of delegating access in your own authentication system.

Settings

Once you have enabled Public Forms, you must check the box Delegate draft authentication and draft access to see the integration options between Flokzu and your own system.



Authentication service URL: REST service's URL that will handle user authentication.
Draft notification service URL : If you have enabled Drafts, you should complete this field with a REST service's URL to send the notifications when a draft is saved, updated or deleted. In this way, the authenticated users will be able to see the saved drafts on your website and continue working on them.
Content that will be added to the draft email: HTML content that will be added in the notification email to sent to the user, with the validation code. Here, you should add the URL on your site that allows users to retrieve their drafts.

How does it work?

If third party authentication has been enabled, the behavior of the public form will be as follows:

Acces a Public Form

When accessing a Public Form, it will be verified that the Email and Authorization properties exist in the request headers, and the authentication service will be invoked to allow or deny access.
If the authentication is successful, the form will be shown to the user, else, Access Denied screen will be displayed.

If the request doesn't have headers or authentication service is out of service, Access Denied screen will be displayed as well.

Saving or updating draft

When saving a draft, an email will be sent to the user, at the same address that request header, with the content of the field Content that will be added to the draft email and the validation code. In that email we will not include any URL to acces the draft bypassing your system.

The service on Draft notification service URL will be invoked and we will send a webhook with status created or updated

You will find the webhook format at Service specs section.

Submit

When the user submits a form retrieved from his drafts, the process instance is created in Flokzu and the draft is removed from the database.
This action is notified to Draft notification service URL sending a webhook with status deleted

Solution overview

1 - End-user sign in to your website
2 - Selects the option to create a new process instance.
3 - The website sends a request to the backend to access the public form.
4 - The backend generates the user's credentials and request the Flokzu authentication service to validate those credentials.
5 - The public form authentication service:
a - Validate the credentials with your website authentication service.
b - Returns the temporary URL which allows to access to the public form.
6 - The backend returns the temporary URL to the end-user's browser
7 - The browser request the public form to Flokzu, through the temporary URL

The following sequence diagram shows the solution with the authentication service



This diagram assumes that your website needs authentication, that end-user is already signed-in, and backend knows the end-user's email.

External services specs

Authentication

The external authentication service is expected to work as follows:

URL
POST - <url in Authentication service URL field>

Header:
Email: <email>
Authorization: <token>

Headers are the same that you must include in the request to open the Public Form.

HTTP status codes:

401: The authorization has been refused for those credentials.

Response JSON
{
  "status": 401,
  "message": "Unauthorized"
}

200: Response if the credentials are valid and a session for this user is active.

Response JSON
{
  "status": 200,
  "message": "OK"
}


Draft notifications

URL:
POST - <url in Draft notification service URL>

Body:

{
  "Timestamp": <current-timestamp>,
  "Type": <draft-type>,
  "Payload": {
      "draft_id": <draft-id-encrypted>,
      "draft_url": "https://host/draft-url"
      "draft_status": <status>,
      "updated_at": <last-update>,
      "email": <email>,
      "authorization": <token>
  }
}

Where:

<current-timestamp>: Date and time when the request is made. It send in extendend ISO-8601 format - UTC (ex: 2021-03-03T16:18:05Z).
<draft-id-encrypted>: Drafts encrypted id. It's also sent as a parameter in the URL.
<status>: It could takes the following values, “created”, “updated” o "deleted" depending on whether the draft is created for the first time, updated and saved as a draft, or deleted.
<lastupdate>_: Date of last update of draft. It's used to automatically delete drafts older than 30 days. It send in extendend ISO-8601 format - UTC.

Keep in mind that all drafts older than 60 days since their last update should be removed from your system.

HTTP status codes:

200: Response if the system update was successful

Response JSON
{
  "status": 200,
  "message": "OK"
}


- : Any other response will be taken as invalid.

Public Forms authentication service

This services allows the access to the public forms and drafts that have been protected with third party authentication.
The service is protected wit the same APIKey uses in OpenAPI calls.

URL
POST - https://app.flokzu.com/flokzuopenapi/api/<api-key>/publicform/authenticate

Headers
X-Username: <email>
X-Api-Key: <api-key>
Content-Type: application/json

Body

{
  "public-form-id": <public-form-id>,
  "draft-id": <draft-id>,
  "email": <email-usuario-final>,
  "authorization": <token>,
  "embedded": true/false
}


Where:

<email>: is a valid Flokzu User email, in the same way that are used in OpenAPI calls
<api-key>: Tenant APIKey, as used in OpenAPI calls.
<public-form-id>: Public form identifier, as it appears in the public form URL.
<draft-id>: Draft identifier, which was sent in the webhooks notification. This is an optional value, it must not be present when requesting access to a new process instance instead of the draft.

Status codes:

401: Unauthorized / Invalid credentials

Response JSON
{
  "status": 401,
  "message": "Unauthorized"
}


422: If the authentication service of your website responds that the credentials are not valid

Response JSON
{
  "status": 422,
  "message": "Invalid credentials"
}


200: Response if credentials are valid and there is an active session for this user

Response JSON
{
  "status": 200,
  "public-form-url": ""
}


When the service receives a request:

1 - Check for a valid credentials in headers.
2 - Get the public form and checks if third-party authentication is enabled.
If so
a - Verifies that the email and token are valid
b - Validates the credentials of the body (email and authorization) against the authentication service
If not, return an error as explained in the status codes.
3 - When the credentials are valid, it generates a temporary token and returns the URL in the public-form-url attribute.

The URL to return depends on whether a draft identifier was specified or not, according to the following:

Without draft-id

URL of the public form with the following parameters added:
auth with the temporary token
embedded Only if the embedded parameter was true when calling this service

Example embedded
https://app.flokzu.com/public/01e1aLENCSEG?auth=eyJhb.eyJzIi._adss&embedded=true

Example not embedded
https://app.flokzu.com/public/01e1aLENCSEG?auth=eyJhb.eyJzIi._adss

With draft-id

URL of the public form with the following parameters added:
p1 Encrypted draft ID
auth temporary token
embedded Only if the embedded parameter was true when calling this service

Example embedded
https://app.flokzu.com/public/01e1aLENCSEG?p1=34lkj3oiu343h3l3&auth=eyJhb.eyJzIi._adss&embedded=true

Example not embedded
https://app.flokzu.com/public/01e1aLENCSEG?p1=34lkj3oiu343h3l3&auth=eyJhb.eyJzIi._adss

Token generation
Since the token is going to be used in a query param when accessing the public form, it will be a one-time use token to prevent someone without access from using it.
The token to be generated will be 32 characters long, and has a collision check implemented.

Webhooks
The following is the format of the webhooks notifications:

Body

{
  "Timestamp": <current-timestamp>,
  "Type": <draft-type>
  "Payload": {
    "draft_id": <draft-id-encriptado>,
    "public-form-id": <form-id-encriptado>,
    "draft_status": <status>,
    "updated_at": <last-update>,
    "email": <email>,
    "authorization": <authorization>
  }
}


Where:
<form-id-encriptado>: is the ID of the public form, created by Flokzu for login
<email> and <authorization>: are the ones saved by the authentication service associated to the temporary token. They are sent to you so that you can validate them if you wish.
Was this article helpful?
Cancel
Thank you!