Authentication with PingFederate

<< Click to Display Table of Contents >>

Navigation:  Identity and access management > 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 step-by-step guide about the configuration needed, both in PingFederate and in Bizagi, in order to have an integrated authentication in Bizagi against PingFederate.

 

SAML_PingF_OV

 

Notice that for SAML 2.0, it is required that both your Identity Provider and your Bizagi project are strictly set up to support HTTPS.

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

 

Prerequisites

In order to configure PingFederate, as with any Identity Provider supporting SAML 2.0, you will need:

 

1. To have previously generated and imported your own certificates.

Such certificates are employed in this integration for the purpose of signing assertions.

This step is not bound to Bizagi nor restricted by any special requirement of Bizagi (it is usually carried out on your own).

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

 

In order to proceed with the guided steps presented below, you will need to have already imported certificates the in your Identity Provider. From such exercise, the following resulting input is needed as well:

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.

 

Recall that if you will be encrypting assertions as well, then the above is also needed for another certificate.

 

note_pin

Consider that the above implies that you will need to be in charge of managing your installed certificates (and watching after its expiration date or any other relevant maintenance aspects such as watching after any changes in your Identity Provider's endpoints).

 

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

Recall that when integrating any Identity Manager (regardless of the chosen one), customers need to synchronize those 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).

Recall that passwords are not stored when integrating an Identity Manager.

 

Once you have verified that at least there is an initial import of your users into Bizagi, you may proceed (by relying on the Work portal and its admin menu):

 

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) is worked on with version 8.4.3.

If you want to use a different version, which supports SAML 2.0, it is advisable to first 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. Configuring in Bizagi, the settings that make reference to the specification of your SAML setup.

2. Configuring Bizagi as Service Provider in ADFS.

 

Procedure

Follow these steps:

 

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

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

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

 

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

 

UsingStudio01

 

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

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

 

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, 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 the Bizagi Management Console.

 

1.3. Proceed to configure these additional parameters as described below, ensuring you click Update for each one that is modified.

Note that the parameter values are case-sensitive and therefore you will need to ensure you input these correctly.

 

Fill in or configure these settings as described:

Enable assertion encryption: You may tick this checkbox (set to On). If doing so, ensure you configure Encryption certificate and Encryption certificate password.

Enable authentication logging in database: You may tick this checkbox (set to On) to define if the web application must log every authentication event (viewed from the Work portal), according to your auditing requirements and expectations.

Encryption certificate: Use the Browse button to 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: Type the password of the digital certificate used for the encryption of assertions.

This password should match the one defined by you at the moment of exporting a certificate information in P12 format.

Force authentication: You may tick this checkbox (set to On) to avoid SSO capabilities so that every time users attempt login at Bizagi, credentials are explicitly requested. Decide on this according to your authentication requirements and expectations.

Identity Provider Metadata File Path: Type the path where the PingFederate metadata file is located. This location is typically an URL.

However, notice that the configuration for this setting with PingFederate is not done in a single step.

PingFederate will not issue its metadata file location before the Service Provider (Bizagi is configured). And similarly with Bizagi, you will generate the metadata file to use in afterward in PingFederate having these settings.

So the idea is for you to leave this setting blank in Bizagi first, and generate Bizagi's metadata file.

Once you can use Bizagi's metadata file to move on with the configuration in PingFederate, you will be able to obtain PingFederate's metadata URL and come back to this option to fill it up in this setting.

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

Organization name: Type the name of your organization. Such information is included within the request messages sent by Bizagi.

Organization URL: Type the URL of the website of your organization. Such information is included within the request messages sent by Bizagi.

SAML Protocol Binding for SLO: It is recommended to select POST so that there is support for much lengthier messages.

SAML Protocol Binding for SSO: It is recommended to select POST so that there is support for much lengthier messages.

Service provider URL: Type the full URL (including the project) of the Service Provider. This means entering the URL for Bizagi Work portal.

For Bizagi PaaS, such URL uses this format:

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

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

https://[server]/[project]

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

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

This password should match the one defined by you at the moment of exporting a certificate information in P12 format.

Signing algorithm: Select either SHA1 or SHA256.

Signing certificate: Use the Browse button to 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

 

Once you are done, review that changes have been applied.

 

1.4. Perform a reset on your Bizagi services.

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

Recall that 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. Proceed to browse for the location of a metadata file that Bizagi generates based on the previous configuration.

In order to configure PingFederate throughout the next steps in an easier way, such metadata file from Bizagi will be downloaded into a local path so that it is then employed as input in PingFederate.

 

Notice you may first view this metadata file by browsing it as:

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

 

 

Proceed to download the file by inputting in that browser:

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

 

2. Configuring Bizagi as Service Provider in PingFederate

Do this by going into the admin options as provided by PingFederate.

 

2.1. Login with admin rights in your PingFederate server.

 

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

 

2.3. Click on Create New at the Connection type, while ensuring SAML 2.0 is selected as the selected Browser Profiles:

 

PingFederate1

 

2.4. Tick the Browser SSO at the Connection Options tab:

 

PingFederate2

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

This way, you browse for Bizagi's metadata.xml file for further configuration.

 

PingFederate3

 

2.6. Define that the Logging mode is set to Standard, at the General info tab.

Click Next when done.

 

PingFederate4

 

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

To configure this, click on Configure Browser SSO first.

 

2.9. Tick the SP-Initiated SSO and the SP-Initiated SLO checkboxes at the SAML Profiles tab.

 

PingFederate5

 

Click Next when done.

 

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

Minutes before

Minutes after

You may leave defaults or change them according to your policies.

 

PingFederate5

 

Click Next when done.

 

2.11. Click on Configure Assertion Creation at the Assertion Creation tab in order to define  which information gets included within the response assertions.

 

2.12. Select the Standard mapping at the Identity Mapping tab:

 

PingFederate6

 

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

Do this by typing the following into SAML_SUBJECT either:

domain\username

username@domain

 

Consider that if the SAML_SUBJECT has a different format, then you may set it to use the e-mail while extending the contract so that the Email attribute and by using:

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

 

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

 

2.15. At the IdP Adapter Mapping, establish a new adapter for the connection by clicking on Manage Adapter Instances (located at the Adapter Instance tab):

 

PingFederate8

 

Notice you may choose to create a new one or select an existing one.

 

PingFederate9

 

2.16. Move on to the Assertion Mapping tab and select Use only Adapter Contract values in the SAML assertion:

 

PingFederate10

 

Click Next when done.

 

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

 

PingFederate11

 

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

 

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

You may simply click Next.

 

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

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

If reviewing this section overall or if wanting to perform manual changes, consider:

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

At the Signature Policy tab, it is recommended that you enforce that assertions are always signed and that such signature is required for Authn requests.

At the Encryption Policy tab, it is required that The Entire Assertion option is selected for encryption (instead of Allow Encryption in SLO Messages from the SP option, which is not supported).

 

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

 

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

 

PingFederate12

Then, select either SHA1 or SHA256 for the algorithm. Recall that this setting should match the algorithm as defined in Bizagi parameters.

 

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

For this, go to the Manage Signature Verification Settings.

 

2.23. Select UNANCHORED at the Trust Model tab (so that it supports self-signed certificates).

 

2.24. Move on to the Signature Verfication Certificate and select the public key as employed by Bizagi for signing purposes.

Notice that if this key is not selectable at the drop-down list, then you may rely on the Manage Certificates button to first import it.

 

PingFederate13

 

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

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

 

Then, select AES-128 as the Block Encryption Algorithm and RSA-OAEP as Key Transport Algorithm.

Recall that if your certificate is not listed in the drop-down list, you may import it first by using the Manage Certificates button.

 

PingFederate14

 

2.26. Move on to the Select Decryption Keys tab and browse for the certificate to be used by Bizagi to encrypt messages sent to PingFederate.

Recall that if your certificate is not listed in the drop-down list, you may import it first by using the Manage Certificates button.

 

PingFederate15

 

 

2.26. Finally, ensure that the Connection status is set as Active (at the Summary page).

 

PingFederate16

 

Ensure changes are saved and exit when done.

 

Additional step

Recall that when you configured settings in Bizagi as in the very first, the Identity Provider Metadata File Path setting was left blank.

Therefore, you will need to first obtain PingFederate metadata file by:

 

 

Once you have this file's URL, proceed to go back to Bizagi and set the above setting:

 

SAML_Bizagiparams2PingF

 

Ensure you save changes.

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