Authentication with ADFS

<< Click to Display Table of Contents >>

Navigation:  Identity and access management > SAML authentication >

Authentication with ADFS

Overview

Bizagi supports integration with Identity and Access Management systems (i.e, Identity Managers or Identity Providers) which are SAML 2.0 compliant, such as Microsoft ADFS.

This section is a step-by-step guide to configuring in ADFS and in Bizagi to have an integrated authentication in Bizagi against ADFS.

 

SAML_ADFS_OV

 

For SAML 2.0, both your Identity Provider and your Bizagi project must be set up to support HTTPS.

For introductory information about SAML 2.0, refer to Authentication via SAML.

 

 

Prerequisites

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

 

1. To have previously generated and imported your own certificates

The integration uses the for signing assertions.

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

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

 

To proceed with the guided steps below, you need to have already imported certificates in your Identity Provider. You need the following information:

The certificate information (.p12 file).

The password for that .p12 file, as defined by you at the moment of exporting the public and private key.

 

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

 

note_pin

To continue, you need to be in charge of managing your installed certificates (keeping track of expiration dates and any other relevant maintenance aspects such as handling changes in your Identity Provider's endpoints).

 

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

When integrating any Identity Manager, you need to synchronize the accounts that are authorized to access Bizagi's Work portal.

Synchronizing means importing or updating the account's primary identifier only (domain plus username typically, and the e-mail address).

Bizagi does not store passwords when it is integrated with an Identity Manager.

 

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: e-mail, or the combination of domain and username.

The examples of SAML-based authentication provided below use e-mail as the unique identifier for users.

 

3. An installed and fully configured and supported version of ADFS.

Bizagi supports ADFS version 3.0.

If you want to use a different version which supports SAML 2.0, check with our support team before proceeding.

 

 

What you need to do

 

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

2. Configure Bizagi as Service Provider in ADFS.

 

Procedure

 

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

Use the Bizagi Management Console targeting the environment you want this configuration to apply to (e.g, development, testing, staging, or production environment).

Alternatively and only for the development environment, you may use Bizagi Studio.

 

1.1. Open Bizagi Management Console and select your Bizagi project.

 

UsingStudio01

 

1.2. Locate the Security module. Click on the Authentication option found under the Security item.

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

 

SAML_Bizagiparams1

 

Click Update.

You will get a confirmation message and notice that additional parameters appear under the Authentication item.

 

note_pin

If you applied this change into an environment other than development, make sure to apply the same changes in your development environment.

Follow the above procedure in the Bizagi Management Console.

 

1.3. Configure the additional parameters, making sure you click Update for each that you modify.

The parameter values are case-sensitive so you must be sure to input them correctly.

 

Fill in or configure these settings as described:

Enable assertion encryption: Check this checkbox (set to On) to turn this feature on. If you do so, be sure to configure Encryption certificate and Encryption certificate password.

Enable authentication logging in database: Check this checkbox (set to On) to define wheter the web application must log every authentication event (you can view the log in Work portal), according to your auditing requirements and expectations.

Encryption 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 encrypt the assertions generated by Bizagi.

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

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

Force authentication: Check this checkbox (set to On) to disable SSO capabilities so that every time users log in to Bizagi, they have to provide their credentials. Decide on this according to your authentication requirements and expectations.

Identity Provider Metadata File Path: Provide the path to the ADFS metadata file. This location is typically a URL, such as the default https://[my_federateserver]/FederationMetadata/2007-06/FederationMetadata.xml

Provide the appropriate value for [my_federateserver].

Idle sessions time-out: Set the number of minutes for which a session will expire, according to your authentication requirements and expectations (e.g, 5 minutes).

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

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

SAML Protocol Binding for SLO: We recommend you to select POST so that there is support for longer messages.

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

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

For Automation Service, the URL uses this format:

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

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

https://[server]/[project]

The URL is case-sensitive and [environment]- should be disregarded (left as blank) while in a production environment.

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

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

Signing algorithm: Select either SHA1 or SHA256. With ADFS the default is set to SHA256. To use SHA1, you need to configure the algorithm when defining the relying party trust at the ADFS directly.

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 e-mail address for contact with your corporation, regarding technical issues.

 

 

SAML_Bizagiparams2

 

When you are done, confirm that your changes have been applied.

 

note_pin

Authentication changes may not be reflected immediately; you may need to reset the Bizagi services.

 

1.4. Perform a reset on your Bizagi services.

For on-premises projects, this means executing an IISReset.

Any change in the authentication type, or any of its settings, is not reflected immediately unless the cache of the application server is explicitly refreshed.

 

1.5. Browse for the location of a metadata file that Bizagi generates based on the previous configuration.

To configure ADFS throughout the next steps more easy, download the metadata file from Bizagi to a local path so you can input it into ADFS.

 

You may first review the metadata file by browsing it as:

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

 

2. Configure Bizagi as Service Provider in ADFS

Do this in the admin options in ADFS.

 

2.1. In your ADFS server, open the administration console.

 

2.2. Launch the creation of a relying party trust.

Right-click Relying party trust to display the options menu, and select the configuration wizard:

 

SSO_idp0

 

Click Start.

 

ADFS_2

 

2.3. Select the data source.

To configure the relying party, select the Import data about the relying party from a file option and browse for the metadata file generated by Bizagi.

 

ADFS_3

 

2.4. Select the metadata file.

Make sure you locate Bizagi's metadata.xml file.

 

ADFS_4

 

Click Next when done.

 

2.5. Enter a unique name.

Give a display name to this configuration, for your convenience.

 

ADFS_5

 

Click Next when done.

 

2.6. Skip multi-factor authentication.

Select the I do not want to configure multi-factor authentication settings for this relying party trust at this time option and click Next.

 

ADFS_6

 

2.7. Choose issuance authorization.

Select the Permit all users to access this relying party option and click Next.

 

ADFS_7

 

You see a summary of the information to set for this relying party trust, including the information that came from Bizagi's metadata file.

You may click Next when done.

You may also check (in the Advanced view) that the algorithm set for this use (either SHA1 or SHA256), matches the one configured in Bizagi.

 

2.8. Open the Claim rules editor.

Before you close the actual configuration window, check the Open the Edit Claim Rules dialog for this relying party trust when the wizard closes checkbox.

 

ADFS_8

 

Then click Close.

 

2.9. Define a new claim rule by clicking Add Rule.

 

ADFS_9

 

 

2.10. Select the Send Claim Using a Custom Rule template.

 

ADFS_10

 

Click Next when done.

 

2.11 Create the following rules:

 

Rule 1

 

Rule name: email

Custom rule: c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"), query = ";mail;{0}", param = c.Value);

 

ADFS_12

 

Rule 2

 

Rule name: nameid

Custom rule: c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");

 

ADFS_14

 

When you are done, your newly created rules are displayed as shown in the image below.

 

ADFS_13

 

The rule may not be recognized right away. If so, delete the rule, create it once again and restart the ADFS server.

 

At this point you have configured your ADFS to rely on SAML 2.0 for an integrated authentication with Bizagi!

You will need to carry out the next part only if you have employed self-signed certificates.

 

Additional step for self-signed certificates

If you have issued and installed a self-signed certificate for your ADFS for signing and encrypting purposes, you will need to perform the following:

1.Access your ADFS server and open a PowerShell console.

2.Enter the following command:

Get-AdfsRelyingPartyTrust -Identifier [relying_party_trust] | Set-AdfsRelyingPartyTrust 

-SigningCertificateRevocationCheck None -EncryptionCertificateRevocationCheck None 

Replace [relying_party_trust] accordingly to the unique name given at the configuration above (when you register Bizagi's relying party trust).