Azure AD Authentication

<< Click to Display Table of Contents >>

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

Azure AD Authentication

Overview

Bizagi supports integration with Identity Management services such as Azure Active Directory (Azure AD).

Bizagi integrates with Azure AD in order to provide secure sign-in and authorization services, while also offering a Single Sign-On experience, which uses the <%TERMS_OAUTH%> protocol with the <%TERMS_OPENID%> extension.

 

This section describes how this integration works and how to configure it.

 

AzureAD_Authentication

 

How Azure AD integration works

<%TERMS_OPENID%> is an authentication protocol, built on top of <%TERMS_OAUTH%> to extend the authorization specification. It can be used to securely sign users into web applications (in this case, the Work portal).

By using this feature, you can outsource sign-up, sign-in, and other identity management experiences in your web applications to Azure AD.

This allows you to provide Single Sign-On capabilities at the browser level.

 

This authentication mechanism introduces the concept of an id_token, which is a security token that allows for due verification of the identity of the user while obtaining some of his/her basic profile information.

Because <%TERMS_OPENID%> extends <%TERMS_OAUTH%>, it also enables applications to securely acquire access_tokens.

Access_tokens allow you to access resources that are secured by an authorization server.

 

The following diagram illustrates the communication flow between Bizagi and Azure AD.

 

AzureAD_01

note_pin

Currently supported standards in this mechanism are:

<%TERMS_OPENID%> v1.0, relying on the <%TERMS_OAUTH%> authorization flow.

 

Though <%TERMS_OAUTH%> considers authorization aspects, these definitions apply to resources.

This means, that for access rights definitions in the Bizagi Work portal (i.e. which profiles can see, work or use certain Bizagi options), you will still need to input authorization definitions in Bizagi.

 

What you need to do

In order to configure Bizagi to sign in with Azure AD, please follow these steps:

 

1. Register your Bizagi Work portal as an authorized app in your Azure AD.

2. Configure the authentication type in Bizagi with the Management Console.

3. Synchronize the users from your Azure AD into Bizagi.

 

note_pin

The steps oriented toward configuring integration with Azure AD, 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. Register your Bizagi Work portal as an authorized app in your Azure AD.

The first step is to set up the configuration needed to Register Bizagi Work portal (its URL) in Azure AD.

This includes inputting Bizagi endpoints while using the proper access keys for an entitled connection.

 

1.1 Log in to your Azure services

Access your Azure subscription with the Azure AD service.

To do so, you will need to sign in to Azure's portal at https://portal.azure.com.

 

AzureAD_portal01

 

1.2. Go into your Active Directory.

Click on Active Directory option at the left panel and click your on App registrations to then add a new application to it (by clicking New application registration).

 

Azure_auth1

 

1.3. Input the app's basic details

Give this app a name, and select Web App / API for its type.

For its Sign-on URL note that you need to input the base URL where your end users access Bizagi Work portal.

 

Consider:

For Bizagi PaaS (cloud projects), this URL is specified as:

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

While replacing [your_company] and [your_project] for your subscription's values accordingly.

Similarly, replace [project_environment] with test for a testing environment, or with nothing at all for a production environment.

 

For <%ONPREMISES%> Bizagi projects, this URL is specified as:

https://[your_server]/[your_project]

While replacing [your_server] and [your_project] depending on how you set up your environment.

 

Azure_auth2

 

Click Create when done.

 

1.4 Go into the details of your app.

Once the app is created, click on it to go into its details.

Notice that a created app will list its Application ID.

 

Azure_auth3

 

1.5 Create a valid access key for the app

In order to do this, first go into the Settings and then click on Keys.

 

Azure_auth4

 

At the next screen, ensure you add a long descriptive number for your key.

Input such number within Description.

Ensure you set the expiration for such key, and then click Save so that the key is generated and shown to you.

 

Azure_auth5

 

note_pin

Note that the above access keys may must have an expiration date, and you are therefore, in charge of managing and looking after its validity.

 

At this point, you should copy the key's value.

Ensure you paste it into someplace you control having adequate measures for safekeeping and acknowledge that this value will be your Key.

 

Azure_auth6

 

1.6 Fill out additional URL details

Go back into Settings but this time browse your app's Properties.

In there, you may look up the current App ID URI and change it to a more descriptive one (such as one involving the URL of your Bizagi Work portal) if it helps you.

Still, it is needed that this URI is unique.

 

Fill out other URLs such Home page URL or LogoutURL.

 

Azure_auth7

 

1.7 Configure Bizagi endpoints in Azure AD

Go back into Settings but this time go into your app's Reply URL.

In there, edit the current value so that you use the same URL as specified for Sign-on URL, but this time append to its end the following suffix:

/oauth2/client/callback

 

Azure_auth9

 

 

Click Save when done.

 

1.8 Look up your AD endpoints

Go back to App registrations and look up the Endpoints in order to gather these URLs that you will need to configure later on in Bizagi.

 

Azure_auth8

 

 

Make sure you copy down the endpoints for the following:

OAuth 2.0 Token Endpoint

OAuth 2.0 Authorization Endpoint

 

note_pin

Adequate authorization settings are usually set Ok by default, which means you should not need to configure this setting.

By default the new applications and their keys are granted with Sign in and read user profile, which is what Bizagi requires.

Notice it is Ok that this setting does NOT require Admin:

 

Azure_auth10

 

At this point, configuration directly in Azure AD is set and you may now go to Bizagi to complete the procedure.

 

2. Configure the authentication type in Bizagi with the Management Console.

At this point, after having verified access in Azure AD is adequate, you will now need to input the Azure AD details into Bizagi.

Do this by using Bizagi Management Console targeting the environment you want this configuration to apply to (e.g, development environment, testing environment, production environment).

 

2.1 Open your project with the Management Console.

Open the Bizagi Management Console and load your project.

 

Cloud_OpenProj_MC

 

2.2 Go to the security settings.

Click on the Security module.

 

AzureAD_MC

 

2.3 Select Azure authentication.

To do this, click on Authentication in the middle panel, and use the following settings for the parameters in the rightmost panel:

Type: OAuth2.

Client: Azure AD.

Click Update.

 

AzureAD_Bizagi

 

Once OAuth2 and AzureAD are chosen, you will notice that new parameters for such Authentication are displayed.

 

2.4. Configure the authentication parameters and endpoints.

To do so, consider the detail as described below:

 

PROPERTY

VALUE

Client ID

Should match the Application Id as registered in Azure AD.

Client Secret

Should match the generated Key for that App set in Azure AD.

Redirect Uri

Should match the Response URI as registered in Azure AD, which should correspond to the Reply URL (that one ending in /oauth2/client/callback).

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

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

Logout Endpoint

Should refer to a Logout endpoint as handled by Azure AD, usually having the following URL:

https://login.microsoftonline.com/[tenant]/oauth2/logout?post_logout_redirect_uri=[homeRedirect]

 

Consider:

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

[homeRedirect]: Should specify the URL used to direct after a log-out.

Usually, you use the same login URL, which is the one directing to Bizagi Work portal.

 

note_pin

If you applied this change into an environment other than development, then you should also make sure such same changes are applied in your development environment as well.

To do this, follow the same procedure mentioned above while using Bizagi Studio.

 

3. Synchronize the users from your Azure AD into Bizagi.

At this point, the configuration is complete.

However, before using or testing the integrated authentication in runtime, you will need to explicitly import users from Azure AD into Bizagi (as you are in charge of managing users).

 

Disregarding the selected Authentication type, for your Work Portal login at runtime, you will need to have imported/synchronized users from your user repository and into Bizagi (this task may be scheduled in Bizagi if integrating to your AD).

Recall that if you are using Bizagi PaaS, integrating your AD needs a VPN.

Alternate options to an AD/LDAP sync through a VPN, consider invoking Bizagi web services from your end (a "push"), or having Bizagi invoke a web service on your side to fetch users (a "pull").

 

 

 

Alternate options to an AD/LDAP sync, are either:

Invoking Bizagi web services from your end (a "push").

For this you need to build a SOAP web services client.

Having Bizagi invoke a web service on your side to fetch users (a "pull").

For this you need to make sure that you produce and publish a web services that can return the list of users.

 

note_pin

If you will not synchronize users about yet, then you may test that the authentication works as expected by simply creating one user manually in Bizagi Work portal for validation purposes. To create such user, consider:

1. You may need to temporarily switch back to using Bizagi authentication so that you can log in.

2. Ensure your created user is set with the exact domain\username combination matching your users in Azure AD.

 

Authentication in runtime

Once these steps are carried out, authentication will be set for your end users in runtime.

End users will be able to sign-in, and you can verify them by using a browser to access Bizagi Work portal.

 

The following image exemplifies access to the testing environment's Work portal for Bizagi PaaS (using https://[project_environment]-[your_project]-[your_company].bizagi.com):

 

AzureAD_AgilityURL

 

When the Bizagi Work portal loads, it redirects you to your Azure AD login page:

 

AzureAD_portal01

 

After you sign in successfully to Azure AD, you are redirected back to Bizagi Work portal with a valid session:

 

Cloud_WorkportalSession

 

note_pin

If you are already logged in with a valid session, you will not need to input credentials.

SSO capabilities are kept at the browser's level while having an authenticated valid session (for instance, idle session settings are also taken from your configuration in Azure AD).