Authentication with Okta

<< Click to Display Table of Contents >>

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

Authentication with Okta

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

This section is a step-by-step guide about the configuration needed, both in Okta and in Bizagi, in order to have an integrated authentication in Bizagi against Okta.

 

SAML_Okta_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 Okta, 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.

 

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.

 

What you need to do

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

 

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

2. Configuring Bizagi as Service Provider in Okta.

 

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: Leave this checkbox unmarked (set to Off). Okta is not currently supporting the reception of encrypted assertions.

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: Disregard this setting (given that is Enable assertion encryption disabled).

Encryption certificate password: Disregard this setting (given that is Enable assertion encryption disabled).

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 Okta metadata file is located. This location is typically an URL.

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

Okta 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 Okta 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 Okta, you will be able to obtain Okta'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.

 

note_pin

Authentication changes may not be reflected immediately; in which case, 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.

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

 

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 Okta

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

 

2.1. Login with admin rights into your Okta portal.

 

2.2. Locate the Applications menu and click on it to select Applications.

Then click on Add Application:

 

Okta_1

 

2.3. Click on Create New App given that it is a non-existing one.

 

Okta_2

 

 

2.4. Fill out the following details:

Platform: Select Web.

Sign on method: Click SAML 2.0.

Platform: Select Web.

 

Okta_3

 

Click Create when done.

 

2.5. Go to the Create SAML integration section.

 

2.6. Fill out General settings:

App name: Define the unique name for your app.

App logo: Select a representative logo of your choice.

 

Okta_4

 

 

Click Next when done.

 

2.7. Fill out Configure SAML:

Single Sign on URL: Enter the URL of the Bizagi Work portal followed by the /saml2/assertionConsumer prefix.

For Bizagi PaaS, such URL uses this format:

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

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

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

Use this for Recipient URL and Destination URL: Tick this option.

Audience URI (SP Entity ID): Enter the URL of the Bizagi Work portal just as it was configured in Bizagi Studio (or the Bizagi Management Console).

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]/

Use this for Recipient URL and Destination URL: Tick this option.

Default RelayState: Leave it empty.

Name ID format: Select E-mailAddress.

Application Surname: Select E-mail.

 

Okta_5

 

2.8. Fill out Show Advanced Settings:

Response: Select Signed.

Assertion Signature: Select Signed.

Signature Algorithm: Select RSA-SHA1 or RSA-SHA256, according to the one configured in Bizagi.

Digest Algorithm: Select SHA1.

Assertion Encryption: Select Encrypted.

Encryption Algorithm: Select AES256-CBC.

Key Transport Algorithm: Select RSA-1.5.

Encryption Certificate: Browse for the public certificate for encryption purposes and upload it.

Enable Single Logout: Select Allow application to initiate Single Logout.

Single Logout URL: Enter the URL of the Bizagi Work portal followed by the /saml2/logout prefix.

For Bizagi PaaS, such URL uses this format:

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

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

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

SP Issuer: Enter the URL of the Bizagi Work portal just as it was configured in Bizagi Studio (or the Bizagi Management Console).

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]/

Signature Certificate: Browse for the security certificate for signing purposes and upload it.

Authentication context class: Select PasswordProtectedTransport.

Honor force authentication: Select Yes.

SAML Issuer ID: Leave the default value as generated by Okta.

 

Okta_6

 

Click Next when done.

 

Okta_7

 

2.9. Leave the defaults and blanks for other options and click Next.

 

Okta_8

 

Notice you may preview how the assertion would be set in runtime:

 

Okta_9

 

2.10. Notice that at the Feedback tab, you may also choose to set:

Are you a customer or partner: Select I'm an Okta customer adding an internal app.

App type: Tick the This is an internal app that we have created checkbox.

 

Okta_10

 

Click Finish when done.

 

2.11. Finally and once the app is created, browse to its details and into the Sign On tab.

 

2.12. Click and select the hyperlink labeled as Identity Provider metadata.

 

Okta_11

 

 

Recall that you need to copy this URL so that you can configure it back in Bizagi, by having the Identity Provider Metadata File Path setting point to it.

 

SAML_Bizagiparams2PingF