Issuing self-signed certficates

<< Click to Display Table of Contents >>

Navigation:  Identity and access management > SAML authentication >

Issuing self-signed certficates

Overview

Bizagi supports integration with Identity and Access Management systems (i.e, Identity Managers or Identity Providers) by means of secure industry protocols and standards.

Among such secure protocols, SAML 2.0 is supported and its use requires demands having issued and installed certificates.

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

 

This is so given the exchange of messages between Bizagi (as a Service Provider) and your SAML-compliant Identity Provider, need to be duly signed.

For some Identity Providers (according to how these support extended options), using another certificate can be employed to also encrypt the messages exchanged.

 

Self-signed certificates

For certificates which are employed to sign or encrypt messages, you may use self-signed certificates without implying any security concerns.

Self-signed certificates are those which are not issued by a public Certificate Authority, and which you may locally generate on your own, by means of SDK tools such as Java's keytool, OpenSSL or others.

This article describes how you may issue and install a self-signed certificate; that is, if you are planning on using them.

 

The following illustration represents (in a high level) working with certificates; while considering that the Certificate Authority may not necessarily be an external one but one setup locally by relying on the use of a self-signed certificate.

 

x509_overview

 

The above shows considers generating a certificate having a private and a public key pair.

Then, signing the certificate with the root certificate of a Certificate Authority (by providing the public key through a certificate signing request .csr). Finally, the certificate is signed, issued and exported in a P12 format, to be used along its password when setting up a trusted communication such as SAML 2.0.

 

Prerequisites

The main prerequisite is to install the SDK of your choice which you will employ to generate self-signed certificates.

This article will instruct steps applicable to using OpenSSL as the SDK for this purpose.

 

For this, download the appropriate installer of OpenSSL from https://slproweb.com/products/Win32OpenSSL.html, where you may locate 64-bit or 32-bit installers according to your system architecture.

 

OpenSSL_1

 

For Windows OS, running the installation is assisted, and it is recommended to follow the default steps save the setting indicating to copy OpenSSL DLLs to The OpenSSL binaries (bin) directory:

 

OpenSSL_2

 

After a successful installation, you should be able to see the openssl.exe executable file (i.e, for Windows), along with its openssl.cfg configuration file, at the bin folder of the location as defined during installation:

 

OpenSSL_3

 

It is recommended that you add OpenSSL into your system environment variables so that you may run its executable without needing to worry about paths.

To do this, edit the Path variable:

 

SAML_OpenSSL2

 

And ensure you add the above location (OpenSSL's bin folder) into its registered locations:

 

SAML_OpenSSL1

 

Ensure you click Ok and save changes while closing these windows (any opened command prompts, environment variable windows, etc).

Throughout the guided steps in this article, OpenSSL will be employed from a command prompt.

In case you are interested in learning about further options and for complete information about OpenSSL command options, refer to its official documentation at https://www.openssl.org/docs/man1.0.2/apps/openssl-req.html.

 

Before you start

For clarity purposes, it is recommended that you create a folder to exclusively store the certificates to be issued within the following steps.

Recall that throughout the following steps, two different certificates will be issued: one for message signing, and another for encryption.

This path will be referred to as <CERT_DIR>.

 

The sample image below shows a created folder set to C:\Root\MyCerts:

 

SAML_OpenSSL3

 

What you need to do

When issuing a self-signed certificate, the following outline of steps is carried out:

1.Create a Certificate Signing Request (CSR).

2.Sign the request.

3.Export the private and public key under a P12 format.

 

Procedure

Follow these steps:

 

1. Create a Certificate Signing Request (CSR).

You will need to issue a Certificate Signing Request before issuing a final certificate, while creating both a private key and a public key file.

Consider that the instructed commands may be displayed in more than one line due to presentation purposes.

For these commands shown below which are lengthy, ensure that you remove any line breaks in between parameters.

 

1.1. Open a command prompt and browse into the <CERT_DIR> folder created previously.

 

SAML_OpenSSL4

 

1.2. Run the following command to create a Certificate Signing Request for the certificate to be used to sign assertions:

openssl req -newkey rsa:2048 -subj "[certificate_details]" -nodes -sha256 -keyout [key_name].key -out [csr_name].csr

 

Consider replacing:

[certificate_details]: The identifier and displayed details of the certificate.

Such information should use the following format: /C=[CO]/ST=[ST]/L=[city]/O=[org]/OU=[unit]/CN=[display_name]/

In such format, you would replace [CO] for the 2-digit country code, [ST] for the 2-digit state code, [city] for the locality or city, [org] for your organization's name, [unit] for the organizational unit, and [display_name] for the identifier of the certificate.

For clarity purposes and for your own convenience, it is suggested that the [display_name] includes the Sign word somewhere.

[key_name]: The name for the file which will be generated holding the private key.

For clarity purposes and for your own convenience, it is suggested that it includes the Sign word somewhere.

[csr_name]: The name for the file which will be generated holding the certificate signing request with the public key.

For clarity purposes and for your own convenience, it is suggested that it includes the Sign word somewhere.

 

 

SAML_OpenSSL5

 

Once the command is run successfully, the two output files (.key and .csr) should be shown at your <CERT_DIR> folder:

 

SAML_OpenSSL6

 

1.3. Repeat the same previous step if you will be encrypting the assertions.

Recall that encrypting the assertions is optional and it should be done as long as your Identity Provider supports it.

 

If choosing to do this, then run the same previous command:

openssl req -newkey rsa:2048 -subj "[certificate_details]" -nodes -sha256 -keyout [key_name].key -out [csr_name].csr

 

SAML_OpenSSL7

 

This time, ensure that you specify a different [key_name] and [csr_name] that in the previous step so that these files are not overwritten.

For clarity purposes and for your own convenience, it is suggested that such names include the Encrypt word somewhere.

Similarly, and within the information in[certificate_details], the [display_name] should be different for each of the generated certificates.

 

Once the command is run successfully, the two output files (.key and .csr) should be shown at your <CERT_DIR> folder:

 

SAML_OpenSSL8

 

2. Sign the request.

To sign the request, you need a Certificate Authority (CA), and it should be best to use one that you may already have for your organization.

If you will be using an existing Certificate Authority of your organization, then you will need to copy its .cer and .key files into your <CERT_DIR> folder, and skip directly to step 2.2.

 

2.1. In case that you don't have an existing Certificate Authority, then you may issue a local one with the following command:

openssl req -new -newkey rsa:2048 -days [validity] -extensions v3_ca -subj "[certificate_details]" 

-nodes -x509 -sha256 -set_serial 0 -keyout [root_key].key -out [root_cer].cer

 

Consider replacing:

[validity]: The number of days to certify the certificate for. For instance setting 3650 applies for 10 years. Using a high value such as 3650 is best in order to avoid at maximum any administrative overhead related to the process of generating new certificates periodically. However, what is important to acknowledge is that: this decision is up to you according to your corporate policies, and that you will need to ensure that those certificates are maintained given that your authentication depends on it.

[certificate_details]: The identifier and displayed details of the certificate.

Such information should use the following format: /C=[CO]/ST=[ST]/L=[city]/O=[org]/OU=[unit]/CN=[display_name]/

In such format, you would replace [CO] for the 2-digit country code, [ST] for the 2-digit state code, [city] for the locality or city, [org] for your organization's name, [unit] for the organizational unit, and [display_name] for the identifier of the certificate.

For clarity purposes and for your own convenience, it is suggested that the [display_name] includes the Root word somewhere.

[root_key]: The name for the file which will be generated holding the private key.

For clarity purposes and for your own convenience, it is suggested that it includes the Root word somewhere.

[root_cer]: The name for the certificate file which will be generated with the public key.

For clarity purposes and for your own convenience, it is suggested that it includes the Root word somewhere.

 

SAML_OpenSSL9

 

Once the command is run successfully, the two output files (.key and .cer) should be shown at your <CERT_DIR> folder:

 

SAML_OpenSSL10

 

2.2. Run the following command to sign the Certificate Signing Request for assertions:

openssl x509 -req -sha256 -CAcreateserial -in [csr_name].csr -days [validity] 

-CA [root_cer].cer -CAkey [root_key].key -out [cer_name].cer

 

Consider replacing:

[validity]: The number of days to certify the certificate for. For instance setting 3650 applies for 10 years. Using a high value such as 3650 is best in order to avoid at maximum any administrative overhead related to the process of generating new certificates periodically. However, what is important to acknowledge is that: this decision is up to you according to your corporate policies, and that you will need to ensure that those certificates are maintained given that your authentication depends on it.

[root_key]: The name of the file holding the private key of the Certificate Authority.

It should match the name as defined in the previous step in case that you generated a Certificate Authority; or the name of the file copied into the <CERT_DIR> folder in case you are using an existing one.

[root_cer]: The name for the certificate file holding the public key of the Certificate Authority.

It should match the name as defined in the previous step in case that you generated a Certificate Authority; or the name of the file copied into the <CERT_DIR> folder in case you are using an existing one.

[csr_name]: The name of the Certificate Signing Request file, as defined and generated in step 1.2.

Recall that it is mandatory to do this for the certificate involved to sign assertions.

[cer_name]: The name for the final certificate file which will be generated with the public key.

For clarity purposes and for your own convenience, it is suggested that it includes the Sign word somewhere.

 

SAML_OpenSSL11

 

Notice that the subject will display the details and identifier of the certificate as generated first.

Once the command is run successfully, a .cer output file should be shown at your <CERT_DIR> folder:

 

SAML_OpenSSL12

 

2.3. Repeat the same previous step if you will be encrypting the assertions; that is, if you carried out the instructions provided in step 1.3.

If choosing to do this, then run the same previous command:

openssl x509 -req -sha256 -CAcreateserial -in [csr_name].csr -days [validity] 

-CA [root_cer].cer -CAkey [root_key].key -out [cer_name].cer

 

Consider replacing:

[validity]: The number of days to certify the certificate for. For instance setting 3650 applies for 10 years. Using a high value such as 3650 is best in order to avoid at maximum any administrative overhead related to the process of generating new certificates periodically. However, what is important to acknowledge is that: this decision is up to you according to your corporate policies, and that you will need to ensure that those certificates are maintained given that your authentication depends on it.

[root_key]: The name of the file holding the private key of the Certificate Authority.

It should match the name as defined in the previous step in case that you generated a Certificate Authority; or the name of the file copied into the <CERT_DIR> folder in case you are using an existing one.

[root_cer]: The name for the certificate file holding the public key of the Certificate Authority.

It should match the name as defined in the previous step in case that you generated a Certificate Authority; or the name of the file copied into the <CERT_DIR> folder in case you are using an existing one.

[csr_name]: The name of the Certificate Signing Request file, as defined and generated in step 1.3.

Recall that it is mandatory to do this for the certificate involved to sign assertions.

[cer_name]: The name for the final certificate file which will be generated with the public key.

For clarity purposes and for your own convenience, it is suggested that it includes the Encrypt word somewhere.

 

SAML_OpenSSL13

 

Notice that the subject will display the details and identifier of the certificate as generated first, which should be different to that one of the previous 2.2. step.

Once the command is run successfully, a .cer output file should be shown at your <CERT_DIR> folder:

 

SAML_OpenSSL14

 

3. Export the private and public key under a P12 format.

As a last step, you require a P12 file holding both the private and the public key.

 

3.1. Run the following command to do this first for the certificate employed for assertion signing:

openssl pkcs12 -export -in [cer_name].cer -inkey [key_name].key 

-CSP "Microsoft Enhanced RSA and AES Cryptographic Provider" -out [p12_name].p12

 

Consider replacing:

[key_name]: The name for the private key file, as defined and generated in step 1.2.

[csr_name]: The name for the public key file, as defined and generated in step 1.2.

[p12_name]: The name for the P12 file which will be generated.

For clarity purposes and for your own convenience, it is suggested that it includes the Sign word somewhere.

 

SAML_OpenSSL15

 

Notice that at this point, you will be prompted to define a password for the P12 file (and to confirm it).

Make sure you copy and remember such password (and that you safekeep it), given that it will be needed for configuration steps later on in Bizagi.

 

Once the command is run successfully, a .p12 output file should be shown at your <CERT_DIR> folder:

 

SAML_OpenSSL16

 

3.2. Repeat the same previous step if you will be encrypting the assertions; that is, if you carried out the instructions provided in step 1.3.

If choosing to do this, then run the same previous command:

openssl pkcs12 -export -in [cer_name].cer -inkey [key_name].key 

-CSP "Microsoft Enhanced RSA and AES Cryptographic Provider" -out [p12_name].p12

 

Consider replacing:

[key_name]: The name for the private key file, as defined and generated in step 1.3.

[csr_name]: The name for the public key file, as defined and generated in step 1.3.

[p12_name]: The name for the P12 file which will be generated.

For clarity purposes and for your own convenience, it is suggested that it includes the Encrypt word somewhere.

 

SAML_OpenSSL17

 

Notice that at this point, you will be prompted to define a password for the P12 file (and to confirm it).

Make sure you copy and remember such password (and that you safekeep it), given that it will be needed for configuration steps later on in Bizagi.

 

Once the command is run successfully, a .p12 output file should be shown at your <CERT_DIR> folder:

 

SAML_OpenSSL18

 

Checkpoint

At this point you may choose to verify that the .p12 file is well-formed and has everything you need.

Recall that you may have one .p12 file, or may have two of them depending on the decision regarding encrypting assertions or not.

 

1. For this, run the following command to verify the .p12 file you will be using for assertion signing:

openssl pkcs12 -info -nodes -in [p12_name].p12

 

Consider replacing:

[p12_name]: The name for the P12 file, as defined and generated in step 3.1.

 

Notice that at this point, you will be prompted to enter the password for the P12 file (as defined in step 3.1.).

 

SAML_OpenSSL19

 

Apart from viewing that there are errors with the command, you may verify:

That the password you defined is correct.

That a public and private key are displayed.

That the subject displays accurately the details as defined when generating the certificate.

That the issuer displays accurately the details of that Certificate Authority employed to sign the certificate.

Others, such as the employed algorithm.

 

2. If you will be encrypting the assertions (that is, if you carried out the instructions provided in step 1.3), then you may repeat the same previous step but this time for the other .p12 file.

For this, run the following command to verify the .p12 file you will be using for assertion encrypting:

openssl pkcs12 -info -nodes -in [p12_name].p12

 

Consider replacing:

[p12_name]: The name for the P12 file, as defined and generated in step 3.2.

 

Notice that at this point, you will be prompted to enter the password for the P12 file (as defined in step 3.2.).

 

SAML_OpenSSL20

 

 

Next steps

At this point you are set having issued self-signed certificates which should be valid to sign and encrypt SAML 2.0 assertions.

You have everything you need to use to configure SAML 2.0 authentication in Bizagi (against an Identity Provider of your choice).

To do this, ensure you take into hand, both the .p12 files and their corresponding passwords.