OAuth authentication

<< Click to Display Table of Contents >>

Navigation:  Integration and authentication > Identity managers > Azure Active Directory authentication >

OAuth authentication

Overview

Bizagi Cloud supports integration with Identity Management services such as Azure Active Directory (Azure AD) throughout the support for the OAuth protocol with the OpenID extension.

Through this OAuth setting in Bizagi, you may choose to delegate authentication to an identity provider server supporting such standard.

Among other identity provider servers supporting the standard, different from Azure AD, you may choose to authenticate against a different Bizagi project you may have.

 

note_pin

Note that Bizagi Cloud integrates with Azure AD in order to provide secure sign-in and authorization services, while also offering a Single Sign-On experience.

It is recommended to use Azure AD, and set it as described at Azure Active Directory authentication.

 

This section describes how to configure OAuth in your Bizagi Cloud project, so that this one delegates authentication to another Bizagi Cloud project.

For the sake of a better explanation on steps, the Bizagi Cloud 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.

 

What you need to do

In order to configure your Client project to sign in by relying on a Server project, please follow these steps:

 

1. Ensure 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.

 

note_pin

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. Ensure that the Server project supports OAuth.

At the Bizagi Server project, you may use any type of authentication.

You will fist need to ensure 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 in order to grant access to an external application.

 

OData_Workportal1

 

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:

 

 

OData_Workportal2

 

note_pin

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 (in order to enhance the security employed by these tokens, especially regarding replay attacks).

 

OData_Workportal15b

 

 

When defining the new application, ensure 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.

 

Cloud_OAuth3

 

 

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.

 

Cloud_OAuth4

 

 

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).

 

Cloud_OpenProj

 

2.2 Go to the security settings.

Click on the Expert view, and select the Security module.

 

Cloud_SecurityModule

 

Click on Authentication in the middle panel, and ensure that the drop-down list at the rightmost panel shows OAuth.

Next for the dropdown appearing right below, ensure you select Bizagi.

 

Cloud_OAuth1

 

Click Update if you had a different choice before.

Upon setting this authentication type, notice that further parameters will be listed as sub-items:

 

Cloud_OAuth2

 

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 Bizagi Cloud, 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.

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).

Redirect URI

Defines the callback URI after a successful authentication.

For Bizagi Cloud, this is set as

https://[project_environment]-[your_project]-[your_company].bizagi.com/oauth2/client/callback

Use OpenID Connect

Enables the use of the OpenID protocol (if set as On).

 
4. Synchronize the users from your Server project into your Client project.

Regardless of the chosen Identity manager, you will always need to synchronize the authorized accounts for Bizagi Work portal (even though for integrated authentication, passwords are not stored in Bizagi when doing so).

When synchronizing users with Bizagi Cloud, users are uniquely defined by their domain and username combination.

 

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.