Authentication with PingFederate

<< Click to Display Table of Contents >>

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

Authentication with PingFederate

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

This section is a guide to the configuration needed, both in PingFederate and in Bizagi, to have an integrated authentication in Bizagi against PingFederate.

 

SAML_PingF_OV

 

For SAML 2.0, both your Identity Provider and your Bizagi project must support HTTPS.

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

 

Prerequisites

To configure PingFederate, 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

You need to be in charge of managing your installed certificates (monitoring expiration dates and any other relevant maintenance work such as responding to 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 user 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 integrating 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 PingFederate.

Bizagi supports PingFederate version 8.

The following example (and official certification) works with version 8.4.3.

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

 

 

What you need to do

The following outline of steps describes what needs to be done, both at Bizagi and at PingFederate:

 

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

2. Configure Bizagi as Service Provider in ADFS.

 

Procedure

 

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

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

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

 

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

 

UsingStudio01

 

1.2. Locate the Security module and select 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 bottom right:

 

SAML_Bizagiparams1

 

Click Update.

You will get a confirmation message, 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 as well.

To do this, follow the same procedure using the Bizagi Management Console.

 

1.3. Configure these additional parameters. Click Update for each parameter you modify.

Parameter values are case-sensitive, make sure you provide the correct values.

 

Fill in or configure these settings as described:

Enable assertion encryption: If you check this checkbox (set to On), make sure to configure Encryption certificate and Encryption certificate password.

Enable authentication logging in database: Check this checkbox (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 format, containing the public and private keys) Bizagi uses to encrypt the assertions it generates.

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 the certificate information in P12 format.

Force authentication: Check this checkbox (set to On) to disable SSO capabilities so that every time users attempt login at 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 where the PingFederate metadata file is located. This location is typically a URL.

However, note that configuration of this setting with PingFederate is not done in a single step.

PingFederate will not issue its metadata file location before you configure Bizagi as Service Provider. As with Bizagi, you generate a metadata file of settings to use afterward in PingFederate.

Leave this setting blank in Bizagi for now, and generate Bizagi's metadata file.

Once you can use Bizagi's metadata file with the configuration in PingFederate, you can obtain PingFederate's metadata URL and come back to this option to fill provide the URL for this setting.

Idle sessions time-out: Define the number of 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. 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 selecting POST to support longer messages.

SAML Protocol Binding for SSO: We recommend selecting POST to support longer messages.

Service provider URL: Provide the full URL (including the project) of your Bizagi Work portal.

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]

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

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

This password should match the one you defined when you exported the 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 keys) that Bizagi uses to sign the assertions it generates.

Technical email contact address: Provide an e-mail address for contact with your corporation, regarding technical issues.

 

 

SAML_Bizagiparams2

 

Once you are done, make sure that your changes have been applied.

 

1.4. Perform a reset on your Bizagi services.

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

Changes in the authentication type, or any of its settings, are not reflected until the cache of the application server is explicitly refreshed.

 

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

To configure PingFederate more easily, download a metadata file to a local path to use as input in PingFederate.

 

You can review the metadata file by browsing to this URL:

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

 

 

Download the file by inputting in the browser:

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

 

2. Configure Bizagi as Service Provider in PingFederate

 

2.1. Login with admin rights to your PingFederate server.

 

2.2. Access the Idp Configuration menu and locate the SP Connections section.

 

2.3. Click Create New for the Connection type, making sure that SAML 2.0 is selected as the Protocol:

 

PingFederate1

 

2.4. Check the Browser SSO checkbox on the Connection Options tab:

 

PingFederate2

2.5. Use the Load metadata option on the Import metadata tab.

Browse for Bizagi's metadata.xml file for further configuration.

 

PingFederate3

 

2.6. Confirm that Logging mode is set to Standard, on the General info tab.

Click Next when done.

 

PingFederate4

 

2.8. Configure the Web browser and HTTP profile for message exchange.

First click on Configure Browser SSO.

 

2.9. Click the SP-Initiated SSO and the SP-Initiated SLO checkboxes on the SAML Profiles tab.

 

PingFederate5

 

Click Next when done.

 

2.10. On Assertion Lifetime tab, set the value for the minutes corresponding to the validity of issued assertions:

Minutes before

Minutes after

You may accept or modify defaults according to your policies.

 

PingFederate5

 

Click Next when done.

 

2.11. Click Configure Assertion Creation on the Assertion Creation tab define which information the response assertions include.

 

2.12. Select Standard mapping on the Identity Mapping tab:

 

PingFederate6

 

2.13. Define the attribute taken as the base for the contract, at the Attribute Contract tab.

Enter in the SAML_SUBJECT either:

domain\username

username@domain

 

If the SAML_SUBJECT has a different format, you can set it to use the e-mail while extending the contract to include the Email attribute:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

 

2.14. Click Map New Adapter Instance on the Authentication Source Mapping tab.

 

2.15. On the Adapter Instance tab, establish a new adapter for IdP Adapter Mapping by clicking on Manage Adapter Instances:

 

PingFederate8

 

You can create a new one or select an existing one.

 

PingFederate9

 

2.16. On the Assertion Mapping tab, select Use only the Adapter Contract values in the SAML assertion:

 

PingFederate10

 

Click Next when done.

 

2.17. Select Adapter in the first drop-down list (Source) and Mail for the second one (Value), the SAML_SUBJECT fields on the Attribute Contract Fulfillment tab.

 

PingFederate11

 

If the contract was extended in step #2.13 with the Email attribute, you need to select the same options from the drop-down lists (first Adapter, then mail) for the Email field that appears.

 

2.18. Skip the configuration presented on the Issuance Criteria tab.

Simply click Next.

 

2.19. Click Configure Protocol Settings in the Browser SSO section and review Protocol Settings.

The following configuration should be automatically filled out based on Bizagi's metadata file.

When reviewing this section overall or if you want to make manual changes, consider:

On the Allowable SAML Bindings tab, only POST and REDIRECT values should be selected.

On the Signature Policy tab, we recommend that you enforce that assertions are always signed and that signatures are required for Authn requests.

On the Encryption Policy tab, make sure The Entire Assertion option is selected for encryption (instead of the Allow Encryption in SLO Messages from the SP option, which is not supported).

 

2.20. Click Configure Credentials on the Credentials tab and locate the Credentials section, to define security measures for messages between PingFederate and Bizagi.

 

2.21. Browse in the Digital Signature Settings tab for the certificate to sign assertions that are sent to Bizagi.

 

PingFederate12

Select either SHA1 or SHA256 for the algorithm. This setting should match the algorithm defined in Bizagi parameters.

 

2.22. Define how the certificate will be validated by PingFederate whenever Bizagi signs messages.

For this, go to Manage Signature Verification Settings.

 

2.23. Select UNANCHORED in the Trust Model tab (to support self-signed certificates).

 

2.24. In the Signature Verfication Certificate tab, select the public key employed by Bizagi for signing purposes.

If this key is not selectable in the drop-down list, use the Manage Certificates button to first import it.

 

PingFederate13

 

2.25. If you have enabled in Bizagi, that assertions will be encrypted, you need to select the certificate and algorithm used for this purpose (and follow this step and # 2.26).

For this, move to the Select XML Encryption Certificate tab and browse for the certificate.

 

Select AES-128 as the Block Encryption Algorithm and RSA-OAEP as the Key Transport Algorithm.

If your certificate is not listed in the drop-down list, you can import it using the Manage Certificates button.

 

PingFederate14

 

2.26. Move tto the Select Decryption Keys tab and browse for the certificate Bizagi uses to encrypt messages sent to PingFederate.

If your certificate is not listed in the drop-down list, you can import it using the Manage Certificates button.

 

PingFederate15

 

 

2.26. Finally, ensure that the Connection status is set as Active on the Summary page.

 

PingFederate16

 

Make sure your changes are saved and exit when done.

 

Additional step

When you configured settings in Bizagi, you left the Identity Provider Metadata File Path blank.

To complete that setting, you need to obtain PingFederate metadata file.

 

Once you have this file's URL, go back to Bizagi and set it in this key:

 

SAML_Bizagiparams2PingF

 

Save your changes

You have configured your PingFederate to rely on SAML 2.0 for an integrated authentication with Bizagi!