Allow third party authentication in Public Forms
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.
Updated on: 08/07/2022
Thank you!