SAML Configuration with Azure AD

<< Click to Display Table of Contents >>

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

SAML Configuration with Azure AD

Overview

Bizagi provides an Azure Enterprise Application that helps you to configure your Azure AD with SSO easily.  This section explains  you can configure the Enterprise Application.

 

1. Prerequisites

To configure Azure AD, as with any Identity Provider supporting SAML 2.0, you need:

 

1.1 To have previously generated and imported your own certificates.

The integration uses the certificates to sign assertions.

This step is not bound to Bizagi nor restricted by any special requirement of Bizagi (you normally do it yourself).

If you need some guidance or an example on this step, refer to Generating and installing certificates.

 

To proceed with these guided steps, you need to have imported certificates into your Identity Provider. For this exercise, you need:

The certificate information in .P12 or .PFX  file format.

The password for the certificate file, as defined by you when you exported the public and private keys.

 

Azure AD particularly does not demand that the P12 certificates match configuration on Azure's side.

 

If you will be encrypting assertions as well, you also need this information for another certificate.

 

note_pin

You will need to be in charge of managing your installed certificates (keep track of its expiration date and other relevant maintenance aspects such as changes in your Identity Provider's endpoints).

 

1. 2. To have already imported and synchronized your users into Bizagi

When integrating any Identity Manager, you need to synchronize authorized accounts so they can access Bizagi 's Work portal.

Synchronizing means importing or updating the account's primary identifiers only (domain plus username typically, and the email address).

Bizagi does not store passwords when integrating an Identity Manager.

 

note_pin

You cannot have two or more users with the same email, because it is considered as part of the primary identifier.

 

Once you have verified in the Work Portal that there has been at least an initial import of your users into Bizagi, you may proceed:

 

125Users13

 

note_pin

In Bizagi, unique identifiers for users are either email or the combination of domain and username. We recommend using the email as the Unique Identifier in Azure.

 

2. Configure your Bizagi project

Open the Bizagi Studio project or the Management Console of your environment, and set the Authentication properties:

 

EnterpriseApp_02

 

Configure these settings:

Cookie type: Define the type of cookie Bizagi uses Persistent o Session cookies. The idle session time-out defines the expiration time for cookies.

Enable assertion encryption: When Bizagi sends messages to the identity provider, it sends two types of assertions.

 -Authentication request: which does not have any sensitive information, therefore is not encrypted by standard definitions.

 -Session log out request: This assertion contains sensitive information, and can be encrypted. If you set this property on, session log out request are encrypted by Bizagi. Make sure that your identity provider supports receiving log out request encrypted.

On the other hand, Bizagi can handle any encrypted message sent by the IdP, even if this property is set off.

Enable authentication logging in database: Check this check box (set to On) to direct the web application to log every authentication event, according to your auditing requirements and expectations. You can view the log in the Work portal.

Encryption certificate: Use the Browse button to locate and upload the digital certificate (in P12 or PFX format, containing the public and private key) that will be used to encrypt the assertions generated by Bizagi.

Encryption certificate password: Provide the password of the digital certificate used for the encryption of assertions.

This password should match the one you defined when you exported certificate information in P12 or PFX format.

Force authentication: Check this check box (set to On) to disable SSO capabilities so that every time users attempt to log in to Bizagi, they have to provide their credentials. Using this option depends on your authentication requirements and expectations.

Identity Provider Metadata File Path: Provide the path where the Azure AD metadata file is located. This location is typically an URL. Such URL in Azure AD is usually found at:

 

https://login.microsoftonline.com/[tenant]/federationmetadata/2007-06/federationmetadata.xml

 

You need to provide the id of your tenant/subscription (as copied into your clipboard in the first steps of configuring Azure AD). Initially, you can use a fictional metadata. For example you can use the contoso Microsoft fictional's company for testing purposes:

 

https://login.microsoftonline.com/contoso.com/FederationMetadata/2007-06/FederationMetadata.xml

 

Later you can reconfigure this parameter at the end of the configuration procedure. See Get the Azure metadata file.

Idle sessions time-out: Define the minutes of inactivity after which a session expires, according to your authentication requirements and expectations (e.g. 5 minutes).

Organization name: Provide the name of your organization. This is included within the request messages sent by Bizagi.

Organization URL: Provide the URL of the website of your organization. This is included within the request messages sent by Bizagi.

Redirect to a log-off page after log-off process: Check this check box if you wish to redirect users to a static log-out page when they log-out.

SAML Protocol Binding for SLO: We recommend selecting REDIRECT as supported specifically by Azure.

SAML Protocol Binding for SSO: We recommend selecting POST so that there is support for longer messages.

Service provider URL: Provide the full URL for the Bizagi Work portal.

For Automation Service, such URL uses this format:

https://[environment]-[project]-[company].bizagi.com/

For on-premises projects, the URL uses this format:

https://[server]/[project]

The above URL is case-sensitive. Do not enter anything for [environment]- to reference the Production environment.

Show detailed authentication error messages: Check this box if you want authentication errors to be shown in a detailed way when they occur.

Signature certificate password: Provide the password of the digital certificate used for the signing of assertions.

This password should match the one you defined when exporting certificate information in P12 format.

Signing algorithm: Select either SHA1 or SHA256.

Signing certificate: Use the Browse button to locate and upload the digital certificate (in P12 format), containing the public and private key that will be used to sign the assertions generated by Bizagi.

Technical email contact address: Provide an email address for contact with your corporation regarding technical issues.

Notice that the values you provide for the settings are encrypted in Bizagi when you save them.

 

After this step is completed, Bizagi generates a metadata.xml file. You can use it as input in the next step.

 

2.1 Download the metadata file

Before configuring Bizagi as a service provider in your identity provider, you need to download a file that contains the metadata of the SAML configuration. This file is usually required by Identity Providers to define predefined configurations.

 

Make sure that you upload the Signing Certificate, and set the Signature certificate Password.

To download the metadata file, Bizagi has the following endpoints

 

You can review this metadata file by browsing it at:

https://[environment]-[project]-[company].bizagi.com/saml2/metadata.xml?mode=preview

 

Download the file by inputting in your browser:

https://[environment]-[project]-[company].bizagi.com/saml2/metadata.xml?mode=attachment

 

EnterpriseApp_03

 

 

3. Configure the Enterprise Application in Azure AD

Do this in the admin options provided by Azure AD.

 

3.1 Log in to your Azure services with a user account with admin rights.

Access your Azure subscription with the Azure AD service.

You will need to sign into Azure's portal at https://portal.azure.com.

 

AzureAD_portal01

 

3.2 Register the Enterprise Application

Open the Azure AD, and select the Enterprise Applications menu. Click New Application:

 

EnterpriseApp_01

 

Search the Bizagi application and select it:

 

EnterpriseApp_04

 

3.3 Define users that are going to be authenticated in Bizagi using Azure SSO

Define users that are going to be authenticated in Bizagi, using Azure SSO. Add them manually or with any predefined group on your Azure AD. Remember that users must be registered in Bizagi.

 

EnterpriseApp_05

 

3.4 Configure the Single sign-on properties

Select the Single sign-on menu, and click the SAML option:

 

EnterpriseApp_06

 

3.4 Set up the metadata file

Now you can upload the metadata file downloaded in the step 2.1.

 

EnterpriseApp_07

 

Review and fill the rest of mandatory fields:

 

EnterpriseApp_08

 

Sign on URL: is the Bizagi 's Work Portal URL, for example, https://<projectname>-<companyname>.bizagi.com

Reply URL: This is the destination in the SAML response: for example, https://<projectname>-<companyname>.bizagi.com/saml2/assertionConsumer

Identifier (Entity ID):  It is the Bizagi 's Work Portal URL, for example, https://<projectname>-<companyname>.bizagi.com

Logout URL: It is the Bizagi's Work Portal logut URL, for example https://<projectname>-<companyname>.bizagi.com/saml2/logout

 

3.5 Verify or upload the certificate

You must include the SAML signing certificate. If the configuration does not have a certificate, click Add a certificate and upload the same certificate used in the Bizagi's configuration.

 

EnterpriseApp_16

 

If the certificate is configured correctly, you can see its properties. Make sure its status is active.

 

EnterpriseApp_17

 

3.6 Define the Unique User Identifier

To identify users when they are being authenticated by Bizagi, you need to define the a Unique Identifier. In Bizagi, unique identifiers for users are either email or the combination of domain and username. We recommend setting the email as the Unique Identifier. Click the edit icon in the User Attributes & Claims options:

 

EnterpriseApp_09

Click the Unique Identifier:

 

EnterpriseApp_12

 

Select the Email Address format, and user.mail as the Source Attribute:

 

EnterpriseApp_13

 

3.7 Get the metadata URL

Finally, copy the App Federation metadata URL:

 

EnterpriseApp_11

 

 

note_pin

The metadata URL must have the following format:

 

https://login.microsoftonline.com/<TenantID>/federationmetadata/2007-06/federationmetadata.xml?appid=<applicationID>

 

It is very important to make sure that the appid parameter is contained at the end of the URL.

 

Open your Bizagi Studio Authentication configuration, or using your Management Console, and paste the URL:

 

EnterpriseApp_14

 

Now when you run the Work Portal, Bizagi displays the Azure's log-in page and users can be authenticated with your Azure AD.

 

note_pin

Remember to do this configuration in all your environments, or to deploy security configurations in your target environments, for example, test or production environments.