HTTPS

Sammanfattning av användningsfall

Scenario

If SSL/TLS should be use with a Fortified ID product, a keystores must be configured containing keys and certificates to use and/or trust.

Two types of key-/truststores are supported:

• Java Keystore format ("JKS")

• PKCS#12 ("PKCS12")

Commands to create either of them will be shown below, but in the configuration examples below we will use a Java Keystore format ("JKS").

The examples will only be parts of the configuration.

Prerequisite

There are some prerequisite for this use case. You will need the following environment:

• Basic knowledge about configuration of the product and the file structure.

• The Fortified ID product of your choice installed

Certificate recommendation

We recommend the use of a keystore create from external CA like Digicert or internal PKI environment! If that is not available or for testing, you can create a self signed using one of the supported methods below.

Create self-signed certificate

Java Keystore format ("JKS")

1. Open a command prompt

2. Change directory to the bin folder of the installed JRE that came with the product. ex. ..\FortifiedID\integrity\web

3. Run the following command to create the certificate store

   jre\bin\keytool -genkey -keyalg RSA -alias server_https -keystore selfsigned_https.jks -validity 365 -keysize 2048

4. Enter keystore password, we will use password as password for the examples.

5. We will fill in information in the following questions, you can enter the information of your choice.

   1. What is your first and last name? web

   2. What is the name of your organizational unit? test

   3. What is the name of your organization? fortifiedid

   4. What is the name of your City or Locality? stockholm

   5. What is the name of your State or Province? stockholm

   6. What is the two-letter country code for this unit? se

   7. What is the name of your organization? y

6. Move the certificate to your installed product "config" folder.

PKCS#12 ("PKCS12")

If you would like to use PKCS#12 certificate make sure to change according the modules documentation section.

1. You need to have openssl installed to run the following command

2. Change directory to the folder where you have openssl or add the path to the command.

3. Run the following commands to create the certificate store

   openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj /CN=web.fortifiedid.se
   openssl pkcs12 -export -in cert.pem -inkey key.pem -out selfsigned.p12 -name "server_https"

General module configuration to use Https

In this section we will look at general module configuration needed for SSL/TLS . See the modules section in the documentation for more details.

• http_port : port that should be used

• http_use_ssl : enable SSL/TLS for the port, true / false

• http_keystore_ref : --- add text ---

• http_keystore_type : Keystore type PKCS12 or JKS, default PKCS12

• http_keystore_alias : Keystore alias

• http_keystore_password : Key password

Configuration examples

Hello module in Integrity Web

The easiest way to test SSL/TLS is to use the Hello module in Integrity Web. This is the only complete configuration example in this document.

1. Make sure that you have the certificate in the correct folder.

2. Change the path and port to suit your environment.

3. Create / modify the configuration file

   {
     "modules": [
       {
         "name": "HelloWorld",
         "config": {
           "http_port": 8443,
           "http_use_ssl": true,
           "http_keystore_ref": {
             "type": "JKS",
             "path": "../customer/config/selfsigned_https.jks",
             "password": "password"
           },
           "http_keystore_type": "JKS",
           "http_key_alias": "server",
           "http_key_password": "password"
         }
       }
     ]
   }

4. Surf to https://<address of your server>:8443,

5. You should see the following page

   
6. Verify the certificate information, if you used the same settings as in the example to create a Java Keystore above, the certificate would look similarly to the image below.

   

7. Recommendation: in more complex configurations where the certificate will be used in multiple places in the configuration, we recommend to use the "Globals" technique. In the example below we have used a mix of "globals" and values in the module. This example will give the same result as the example above.

   {
     "globals": {
       "keystores": {
         "server": {
           "type": "JKS",
           "path": "../customer/config/selfsigned_https.jks",
           "password": "password"
         }
       },
       "modules": [
         {
           "name": "HelloWorld",
           "config": {
             "http_port": 8443,
             "http_use_ssl": true,
             "http_keystore_ref": "${globals.keystores.server}",
             "http_keystore_type": "${globals.keystores.server.type}",
             "http_key_alias": "server_https",
             "http_key_password": "password"
           }
         }
       ]
     }
   }

Auth module

Add SSL/TLS to the Auth module. The examples below is only parts of the configuration.

1. Add or modify the globals part of the configuration file with the following example, change the path and port to suit your environment.

   .......
     "globals": {
       "keystores": {
         "server": {
           "type": "JKS",
           "path": "../customer/config/selfsigned_https.jks",
           "password": "password",
           "alias": "server_https"
         }
       }
     },
   .......

2. Add the following in the "config" section of the Auth module, change the configuration to suit your environment.

   .......
   "config": {
           "http_port": 8443,
           "http_use_ssl": true,
           "http_keystore_ref": "${globals.keystores.server}",
           "http_keystore_type": "${globals.keystores.server.type}",
           "http_key_alias": "${globals.keystores.server.alias}",
           "http_key_password": "${globals.keystores.server.password}",
   .......

3. Verify the configuration

OIDCModule

The examples below is only parts of the configuration.

1. Add or modify the globals part of the configuration file with the following example, change the path and port to suit your environment.

   .......
     "globals": {
       "keystores": {
         "server": {
           "type": "JKS",
           "path": "../customer/config/selfsigned_https.jks",
           "password": "password",
           "alias": "server_https"
         }
       }
     },
   .......

2. Add the following in the "providers" section of the OIDCModule, change the configuration to suit your environment.

   .......
   "providers":[
               {
                   "http_port": 8443,
                   "http_use_ssl": true,
                   "http_keystore_ref": "${globals.keystores.server}",
                   "http_keystore_type": "${globals.keystores.server.type}",
                   "http_key_alias": "${globals.keystores.server.alias}",
                   "http_key_password": "${globals.keystores.server.password}",
   .......

3. Verify the configuration

Portal module

The examples below is only parts of the configuration.

1. Add or modify the globals part of the configuration file with the following example, change the path and port to suit your environment.

   .......
     "globals": {
       "keystores": {
         "server": {
           "type": "JKS",
           "path": "../customer/config/selfsigned_https.jks",
           "password": "password",
           "alias": "server_https"
         }
       }
     },
   .......

2. Add the following in the "config" section of the Portal module, change the configuration to suit your environment.

   .......
   "config": {
           "http_port": 8443,
           "http_use_ssl": true,
           "http_keystore_ref": "${globals.keystores.server}",
           "http_keystore_type": "${globals.keystores.server.type}",
           "http_key_alias": "${globals.keystores.server.alias}",
           "http_key_password": "${globals.keystores.server.password}",
   .......

3. Verify the configuration

Enrollment modules - OathSwEnrollment and OathHwEnrollment

The examples below is only parts of the configuration.

1. Add or modify the globals part of the configuration file with the following example, change the path and port to suit your environment.

   .......
     "globals": {
       "keystores": {
         "server": {
           "type": "JKS",
           "path": "../customer/config/selfsigned_https.jks",
           "password": "password",
           "alias": "server_https"
         }
       }
     },
   .......

2. Add the following in the "config" section of the OathSwEnrollment and OathHwEnrollment modules, change the configuration to suit your environment.

   .......
   "config": {
           "http_port": 8443,
           "http_use_ssl": true,
           "http_keystore_ref": "${globals.keystores.server}",
           "http_keystore_type": "${globals.keystores.server.type}",
           "http_key_alias": "${globals.keystores.server.alias}",
           "http_key_password": "${globals.keystores.server.password}",
   .......

3. Verify the configuration