Overview
This section describes how to configure OAuth in your Bizagi project, so that this one delegates authentication to another Bizagi project. The Bizagi project set to use OAuth for authentication purposes will be referred to as the Client project, while the target one granting access will be referred to as the Server project.
The following diagram shows the steps to authenticate a user when you use other Bizagi project.
1. Redirect to the identity provider and validate OAuth server keys. When a user tries to access the Bizagi client project, this redirects the request to the Bizagi server. First, the Bizagi server validates the OAuth keys (Client ID and Client Secret), and the Redirect URI. IF any of these does not match, the Bizagi client displays an error message.
2. The Bizagi server requests the user credential using the log-in page for the Bizagi server project.
3. After the user inputs the credentials, the Bizagi server validates the user's credentials.
4. If the credentials given by the user are correct, the Bizagi server returns the authentication token, so it gives access to the Work Portal of the Bizagi client. For this purpose, Bizagi has a callback service, that is configured as the redirect URI, that waits for the answer of the Bizagi server in the authentication procedure using the OAuth protocol.
What you need to do
To configure your Client project to sign in by relying on a Server project, please follow these steps:
1. Make sure that the Server project supports OAuth.
2. Generate access keys for OAuth access.
3. Set the authentication type in Client project, through Bizagi Studio.
4. Synchronize the users from your Server project into your Client project.
|
The steps oriented toward configuring such integration, will require specific technical details (e.g, endpoints, authorized credentials) which are usually managed by an IT admin. Therefore, these steps will require a profile having expertise on this matter, and having access to the information mentioned above. |
1. Make sure that the Server project supports OAuth.
At the Bizagi Server project, you may use any type of authentication.
You will first need to make sure that such project was created in version 11.1 or higher, and that such project was NOT migrated from a previous Bizagi 10.x version.
2. Generate access keys for OAuth access.
Once you have ensured that your Server project supports OAuth according to its version, go to the Work Portal and proceed to obtain OAuth credentials (client ID and client secret) as described below:
2.1 Register the OAuth application.
Click on the OAuth2 Applications option available under the Admin menu to grant access to an external application.
Notice this option lists services being accessed by Bizagi devices, but it allows you to include additional applications that represent granted access to the services by getting appropriate access keys.
2.2 Add a new application.
Click on the option to add a new record in this table:
|
Note that for the default and system settings, you may only choose to edit the token's lifetime, which determines a number of minutes after which a token expires (to enhance the security employed by these tokens, especially regarding replay attacks).
|
When defining the new application, make sure you consider the following details:
•Name: Give a unique and representative name.
•Grant type: For this particular scenario (connecting a Client project to a Server project), use Authorization code.
•Web Site: Specify the URL of your Client project for descriptive purposes.
•Allowed Scope: For this particular scenario (connecting a Client project to a Server project), use Login.
•Redirect strategy: For this initial test and for a general use, consider setting Web application.
•Redirect URI: Define the URL to which there will be directed in the callback once an user inputs his/her credentials.
•Token lifetime: Define the number of minutes for which a same token is valid and can be reused for another invocation (usually to enhanced security while avoiding replay attacks).
An usual or recommended setting should consider not exceeding 15 minutes.
Once you are done, click Save.
You will notice that your new registered application is listed along with its access keys.
2.3 Copy the access keys once the application is registered.
Access keys which will be needed in the next step, are: Client Id and Client Secret.
3. Set the authentication type in Client project, through Bizagi Studio.
To explicitly choose Bizagi authentication, follow these steps:
3.1 Open your Bizagi Studio project.
Open Bizagi Studio and load your project (Development environment).
2.2 Go to the security settings.
Click on the Expert view, and select the Security module.
Click on Authentication in the middle panel, and make sure that the drop-down list at the rightmost panel shows OAuth.
Next for the drop-down appearing right below, make sure you select Bizagi.
Click Update if you had a different choice before.
Upon setting this authentication type, notice that further parameters will be listed as sub-items:
2.3 Configure OAuth parameters.
Refer to the detail provided in the table below:
PARAMETER |
DESCRIPTION |
|---|---|
Bizagi Identity Provider URL Server |
Defines the Bizagi server URL, for that Server project in charge of authenticating users. For Automation Service, this is set as https://[project_environment]-[your_project]-[your_company].bizagi.com |
Client ID |
Holds the client ID as generated in your Server project's OAuth application. |
Client Secret |
Holds the client secret as generated in your Server project's OAuth application. |
Cookie type |
Defines whether Bizagi uses Persistent o Session cookies. The idle session time-out defines the expiration time for cookies. |
Enable authentication logging |
Establishes if an audit log is recorded with all authentication events. If enabled look for the table AUTHOLOG in the database. |
Enable Refresh Token |
Enables an automatic token refresh treatment (if set as On), so that users are not prompted to re-enter credentials if the token has expired. Note that through this setting, token expiration is still enforced only that Bizagi will automatically retrieve a new token. |
Enable Single Sign On Cookie |
Enables a Single Sign-On experience by relying on cookies (if set as On). |
Idle session time-out |
Defines the time in minutes in which an idle session expires; in which case it would be required to authenticate again. This setting defines the expiration time for cookies. In case you wish to increment this time-out to more than 60 minutes (not recommended), bear in mind that you will need to edit the default settings at your web server (e.g, doing so directly at the IIS). |
Redirect to a logoff page after logoff process |
Defines if users are redirected to a static logout page when they logout. |
Redirect URI |
Defines the callback URI after a successful authentication. For Automation Service, this is set as https://[project_environment]-[your_project]-[your_company].bizagi.com/oauth2/client/callback |
Show detailed authentication error messages |
Defines if authentication errors are shown in a detailed way when they occur.
|
Important notes
Consider the following restrictions on this particular use, when having a Client project connect to a Server project and currently regarding error handling:
•Error messages are not currently localized to different languages (shown only in English)
•Error messages are not different across environments (Development, Testing or Production)
•No error page is shown whenever connectivity fails between the Client project and Server project -especially if nesting more than 1 project under this treatment.
•Logs are not recorded with further detail (i.e event viewer).
•The following settings in the Server project (applies when using Bizagi authentication) are not configurable for the Client project:
Enable password change after the first login, Idle account duration before lockout, or Password restoring options.