OAuth authentication

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Security definition > Work Portal Security > Work Portal Authentication >

OAuth authentication

Overview

Bizagi supports integration with Identity Management services such as Azure Active Directory (Azure AD) throughout the support for the OAuth 2.0 protocol with the OpenID extension. For introductory information about authentication options in Bizagi, refer to Identity and Access Management.

 

OAuth 2.0 is an authorization framework used to delegate the user authentication to third party applications. This framework is used also form web applications and mobiles.

 

How does OAuth 2.0 works

The framework defines four roles:

 

Resource owner:  This is the user that knows the credentials to access a particular resource. This is usually a person trying to access a system, In Bizagi this would be a user trying to access the Work Portal.

Client: For security reasons, the resource server does not talk directly with the authorization server, so a breach in the communication between the user and the resource server does not expose credentials or secured information. The client then is an additional "application" that wants to access the user account in the authorization server. To do that, the user must give permission, so the client can talk to the authorization server on its behalf.

Resource server: This server hosts the application that the user wants to access. Usually the resource server and the authorization server are embedded in one application or API.

Authorization server: This server holds the user's accounts and credentials.

 

The following diagrams describes the general authorization flow when a user tries to access a resources.

 

Security_8

 

To generate trust between the authorization/resource server and the client, you must register your application first. When you register the application it is important to define a redirect URI, also known as the callback URL. This URL is used to redirect the user when the user is authenticated and the access token or authorization code is given, so the user can access the application.

 

Once you register your application in the authorization server, this gives a pair of OAuth keys:

 

Client ID: Identifier of the client registered in the authorization server.

Client Secret: password to authenticate the client. Be careful not confuse the client with the user. The client is an application talking on behalf of the user.

 

Grant type

Some steps shown in the general authorization flow  above can be different depending on the grant type configured. Bizagi supports the following grant types:

 

Authorization code: The application will get an authorization code using the redirect URL. This grant type is used when you need to integrate web or mobile applications. Before obtaining the token, the authorization code must be sent to the authorization server. This extra step diminishes the possibility for attackers to get the token directly. The following diagram highlights the extra steps in the regular flow:

 

Security_9

Client credentials: This grant type is used to get an access token in the context of a user. For example, get an access token as an administrator. This is used when you need to use a feature of Bizagi without considering all the users of the Application. For example, when you want to use the OData layer, as the admon user. With this grant type, there is no need to send an authorization code, and the OAuth keys are validated directly to get the access token.

Bearer token: This grant type is used as an HTTP authentication scheme, so an external application using the OAuth keys pair, can get an access token directly sending these keys in the authorization header of the HTTP request. For example when you synchronize users using SCIM. This grant type is recommended under an HTTPS secure connection.

 

Authorization (OAuth) vs Authentication (OpenID)

Authentication is the procedure to identify a user or a person. The authentication procedure validates that a user is what he  or she claims to be. There are different ways to validate that, for example, biometrics, or passwords, as usually is done y IT. On the other hand, authorization is a procedure to give access to a defined set of resources once a user is authenticated. OAuth 2.0 is an authorization protocol but is not capable to identify users. Therefore, Bizagi uses the OpenID standard, so it gives authentication capabilities to Bizagi.

 

OpendID is a layer on top of the OAuth 2.0 protocol so systems can authenticate a user using the same protocol. In Bizagi, the OpenID standard is used for user authentication.

 

OAuth 2.0 Authentication Identity Providers

Through this OAuth setting in Bizagi, you may choose to delegate authentication to an identity provider server supporting such standards. Among other identity provider servers supporting the standard you can choose:

 

Azure AD

ADFS4

Other Bizagi project

 

OAuth 2.0 configuration parameters

Bizagi has the following configuration parameters when you set the OAuth authentication type. Some of the parameters change depending on the identity provider selected:

 

PARAMETER

DESCRIPTION

Identity Provider URL Server

Defines the server URL, for IdP  in charge of authenticating users.

Bizagi server URL

URL of the Bizagi project that you are authenticating using OAuth 2.0.

Client ID

Holds the client ID as generated in your IdP OAuth application.

Client Secret

Holds the client secret as generated in your Idp OAuth application.

 

*Not available for Implicit grant type.

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.

 

*Only available for Bizagi as an Identity provider

Enable Single Sign On Cookie

Enables a Single Sign-On experience by relying on cookies (if set as On).

 

*Only available for Bizagi as an Identity provider

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

OAuth2 Authorization Endpoint

Should match the OAuth 2.0 Authorization endpoint as per your Azure AD.

Use the following URL:

https://login.microsoftonline.com/[tenant]/oauth2/authorize

 

Consider:

[tenant]: Should specify your Tenant id (based on your Azure's subscription).

 

*Only available for Azure AD as an Identity provider

Token Endpoint

Should match the OAuth 2.0 Token endpoint as per your Azure AD.

Use the following URL:

https://login.microsoftonline.com/[tenant]/oauth2/token

 

Consider:

[tenant]: Should specify your Tenant id (based on your Azure's subscription).

 

*Only available for Azure AD as an Identity provider

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.

 

 

Bizagi OAuth Endpoints

The endpoints provided by Bizagi regarding OAuth authentication to handle communication with third parties are (preceded by https://[project_environment]-[your_project]-[your_company].bizagi.com/[your_project]-[project_environment]):

 

/oauth2/server/authorize

oHandles third party authorization requests.

/oauth2/server/token

oHandles third party token requests.

/oauth2/client/callback

oHandles response codes from an Authorization Server.

/oauth2/server/logout

oInvalidates a token.