SAML general configuration

<< Click to Display Table of Contents >>

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

SAML general configuration

Overview

Bizagi supports integration with any Identity and Access Management systems that complies with the SAML 2.0 protocol.

SAML 2.0 is the most widely-adopted industry protocol for authentication, and most major Identity Managers on the market support it.

 

This article take you through the SAML general configuration in Bizagi, including the following relevant topics:

SAML setup in Bizagi Studio

Bizagi Configuration as a Service Provider in the Identity Provider

Endpoints for the Identity Provider

 

How to configure SAML-based authentication

Before you integrate your SAML-compliant Identity Provider with Bizagi, you need to have generated and installed your own certificates.

The integration uses a certificate for signing assertions. you can use an additional certificate to encrypt assertions if supported by your Identity Provider.

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

 

note_pin

If you plan on using an authentication method different than Bizagi and you are performing a deployment to an environment with no users on it (normally this would only be the case for a project's first deployment), follow these steps so that you can correctly configure your users and authentication without getting locked out of the Work Portal:

1.Perform the deployment with the authentication method set to Bizagi. This lets you access the Work Portal as the Admon user without providing any credentials.

2.Once in the Work Portal you can manually enter your users, or alternatively you can rely on the method of your choice to synchronize your users' information into the WFUser table (SOAP, Excel file, LDAP Synchronization, or performing a Data Synchronization procedure).

3.Perform an IISRESET so that the Admon user can no longer access the Work Portal.

4.After having your users registered in the Work Portal, use the Management Console to set the authentication method to your preferred one.

 

If you plan on using LDAP authentication with periodic users synchronization, you may ignore the previous steps since you will only need to wait until the next synchronization happens for your users to be able to log into the Work Portal.

 

Apart from this, here is an outline of what needs to be done, both by the Identity Provider and at Bizagi:

 

1. Configure in Bizagi the settings that make reference to the specification of your SAML setup.

 

1.1. If you are going to configure it from the development environment, open Bizagi Studio.

 

1.2. Locate the Security module and click the Authentication option found under the Security item.

Select Federated authentication from the drop-down list in the panel to the right, and select SAML v2.0 from the drop-down at the lower right:

 

SAML_Bizagiparams1

 

Within these settings, you configure:

Enable assertion encryption: When Bizagi sends messages to the Idp, 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 reques tare  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: Set this option to On to have the web application log every authentication event. You can view the log from 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 keys) that will be used to encrypt the assertions generated by Bizagi.

Applicable when enabling the Enable assertion encryption property.

Even though it is possible to reuse the same certificate as employed for the Signing certificate setting, we recommend different certificates, especially on Production environments.

Using self-signed certificates is supported.

A P12 format is equivalent to PFX format (if you have a PFX simply rename that file changing its extension).

Encryption certificate password: Type the password for the digital certificate for encryption.

Applicable when enabling the Enable assertion encryption property.

Force authentication: Set this option to On to avoid SSO capabilities and request credentials every time users attempt to log in at Bizagi.

Identity Provider Metadata File Path: Provide the path, usually a URL, to where the metadata file of the Identity Provider is located. For on-premises Bizagi projects, you can also use a full disk path while ensuring adequate access rights.

Idle session time-out: Define the number of minutes of inactivity after which a session expires.

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

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

SAML Protocol Binding for SLO: Select either POST or REDIRECT to define which Binding implementation to use in single logout.

Selecting REDIRECT may not be optimal when encrypting assertions, as such messages become part of the URL. The URL may get long enough to trigger errors in some browsers.  

SAML Protocol Binding for SSO: Select either POST or REDIRECT to define which Binding implementation to use in single sign-on.

Selecting REDIRECT may not be as optimal when encrypting assertions, as such messages become part of the URL. The URL may get long enough to trigger errors in some browsers.  

Service provider URL: Type the full URL (including the project) of the Service Provider. This means entering the URL for 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 URL is case-sensitive. For Automation Service, leave [environment]- blank for the Production environment.

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

Signing algorithm: Select either SHA1 or SHA256 to define which algorithm to use when signing assertions.

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

Using self-signed certificates is supported.

A P12 format is equivalent to PFX format (if you have a PFX simply rename that file changing its extension).

Technical email contact address: Provide an email address for contacting your corporation, regarding technical issues. The email is included within the request messages sent by Bizagi.

 

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.

 

SAML_Bizagiparams2

 

You can also set or change this parameters from the Management Console Web.

 

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

 

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

 

 

note_pin

Using X509 certificates, a temporary public / private key object is stored in the machine key directory. If you get an access denied error:

 

FederatedAuthentication_Error

 

Make sure that the user of the application pool in the IIS server has permissions as network_services to write in this folder C:\ProgramData\Microsoft\Crypto\RSA\MachineKeys. We suggest instead using the Application pool identity.

 

2. Configuring Bizagi as a Service Provider in your Identity Provider

In your Identity Provider's admin options, you should be able to register Bizagi as a trusted Service Provider.

For most Identity Providers, you specify/confirm Bizagi's URL, and load information from a metadata file.

Along with this configuration, you define the certificate to use to sign assertions, and exactly which information is sent within assertions (i.e, the user's unique identifier such as their email address). Configuration regarding a certificate to use to encrypt assertions is optional and it depends on whether your Identity Provider supports it.

The exact steps to accomplish this may vary for different Identity Providers, however, some general concepts apply in all cases.

 

Endpoints

You need to provide in the Identity Provider the following endpoints:

 

Single Sign on URL: Provide the URL of your Bizagi Work portal followed by the /saml2/assertionConsumer suffix.

For Automation Service, the URL has this format:

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

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

https://[server]/[project]/saml2/assertionConsumer

 

Service Provider ID URI (also known as audience ID URI or Application ID URI): Provide the URL of the Bizagi Work portal just configured in Bizagi Studio (or the Bizagi Management Console).

For Automation Service, the URL has this format:

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

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

https://[server]/[project]/

 

Single Logout URL: Provide the URL of the Bizagi Work portal followed by the /saml2/logout suffix.

For Automation Service, the URL has this format:

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

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

https://[server]/[project]/saml2/logout