ID-porten (Norway) (SAML IdP with OIDC RP)

How to consume authentication from ID-porten (Norway) using Integrity

Scenario

IIn this scenario, we will setup Integrity as a SAML Identity Provider, protecting a SAML Service Provider (samltest.id).

The authentication method used in this scenario is ID-porten.

To setup ID-porten as an authentication method, we will setup Integrity as an OpenID Relying Party and connect it to ID-porten, acting as an OpenID Connect Provider.

After successful authentication with ID-porten, we will query an LDAP using the provided identifier (pid) from ID-porten, to fetch the user email which will be the SAML assertion identifier value. ​

NB! The authentication method for ID-porten can also be used in scenarios where Integrity protects a service using another protocol (OIDC, WS-fed etc)

Prerequisite

• LDAP directory. The example code is configured using an Active Directory. We are using the AD attributes serialNumber (as search key, this attribute contains the personal id value) and mail.

• Access to https://samltest.id/ from the server.

• The integrity server must sit behind a reverse proxy. The reverse proxy handles SSL offloading and proxies the traffic to the Integrity web server.

• Integrity web server domain name. In this configuration example, we use https://integrity.example.org.

• IDPorten admin must add Integrity as an OpenID Connect Relying party (web application). Whitelisted uri: https://integrity.example.org/saml/authn/oidc_rp IDPorten admin will provide you with a client_id and a client_secret to be used. See below.

Note. All configuration and testing is done on your scenario server.

Configuration

Install and prepare configuration

1. Download and install Integrity Web

   1. To install Integrity Web, se documentation and the installation section.

2. All data in the config.json will be replaced with data from this use case.

   1. At the bottom of this page you have the entire configuration to copy/paste to your config.file. In the steps below we will explain the part of the configuration you need to change to map to your environment.

3. Go to the bottom of the page and copy and paste the information to your config.json file.

Update the configuration to map your environment

In this section we will look at parts of the configuration and add/replace data to map your environment. In this use case we are using the globals concept which is using variables to easily replace data specific to an environment or if a value is used in many places so change in only one place is needed.

1. file_paths The file paths below is created where a folder called /customer is root and a subfolder is called config which stored the config.file. Then there are a number of subfolders under customer depending in the use case. The file paths might be different depending if you install in Windows/Linux or Docker. Below is an example of a folder structure.

   1. Find in module globals section: file-paths

   2. base_dir is the top folder where data is located that you do not want to be overwritten by an upgrade. Update the base_dir folder to map your installation.

      1. For Windows the value is correct

      2. If you use Docker, the change the value to ".", result should look like: "base_dir": "."

         "file_paths": {       
          "base_dir": "../customer"

2. ldap Update the ldap information to map your environment.

   1. Find in module globals section: ldap

      "ldap": {
          "base_dn": "dc=company,dc=local",
          "host": "127.0.0.1",
          "port": 636,
          "bind_dn": "CN=admin,CN=Users,DC=company,DC=local",
          "bind_password": "password_for_the_ldap_account" }

   2. Create a test ldap user Make sure you have a test user to test with. Make sure the user has a value in the mail attribut since it is used as username to login with.

3. http

   Update the http information to map your environment. This is the port that Integrity Web will use to host the SAML IdP service.

   1. Find in module globals section: http.

      "http": {
          "http_port": 8080 }

4. keystore

   Either you download and use the test certificate in this scenarion provided by us, if so you do no need to change anything. If you have a certificate then update the values below to map your certificate.

   1. Find in module globals section: keystore

      "keystore": {
          "alias": "fortifiedid",
          "key_password": "fortifiedid",
          "password": "fortifiedid",
          "path": "/config/resources_internal/certificates/fortifiedid.p12"
          }

5. OIDC RP

   1. Add to module globals

      "oidc_rp": {
          "client_id": "client_id_given_to_you_by_IDPorten_admin",
          "client_secret": "client_secret_given_to_you_by_IDPorten_admin"
          }

Overview of SAML metadata file and entityID

This section will explain the mapping between the IdP metadata-file and the entityID of the IdP. The SAML support in FortifiedID allows the running of several IdP parallell. In our case we only use one IdP.

Overview of SAML metadata-file

To create a metadata-file for our IdP to provide for an SP, we need two things to create the file:

• A Metadata template file. See line 8 below.

• Some configuration from the config.json file. Example of configuration is certificate data.

The id fortifiedid_web_saml_idp_1 (see line 7 below) is part of the download URL and map to correct metadata file. When download the metadata file for an SP the URL could look like: https://integrity.example.org/saml/metadata/fortifiedid_web_saml_idp_1

"name": "SAML",
"config": {
	"metadata_cache": "${globals.file_paths.base_dir}/cache",
	"http_port": "${globals.http.http_port}",
	"enable_http": true,
	"metadata_template": [{
	                "id": "fortifiedid_web_saml_idp_1",
			"metadata_file_path": "${globals.file_paths.base_dir}/config/resources_internal/saml_idp_templates/fortifiedid_web_saml_idp_1_template.xml",

Overview of SAML IdP EntityID

Inside the template file mentioned in previous section there is an EntityID. When an SP connects to the FortifiedID WEB for authentication, the WEB/SAML needs to understand what authenticator to send to in config.json file. This is done using the EntityID. In previous section we used a metadata-file, that file includes an EntityID. the value of our EntityID in this use case is: https://fortifiedid.se/test_idp_1. In the example configuration below you have configuration of the WEB/SAML authenticator we like to use for our SP. To map the SP to correct authenticator, the authenticator has an IdP parameter that uses the same EntityID as in the metadata file. (see line 5).

"config": {
	"context_path": "/saml/authn/chain",
	"base_path": "/saml/authn",
	"force_re_auth": true,
	"idp": "https://fortifiedid.se/test_idp_1",
	"chain": [{

Generate and upload the IdP metadata to samltest.id

Trust need to be established between the IdP and the SP.

Generate metadata-file for SAML test

1. Start the Integrity WEB service

2. Open a browser and browse to: http://integrity.example.org/saml/metadata/fortifiedid_web_saml_idp_1

3. This will download the metadata XML-file for your IdP.

Upload the IdP metadata to samltest.id

For the SP to trust the IdP you will fetch the metadata file of the IdP and upload it to the SP.

1. Open a browser and browse to: https://samltest.id/upload.php

2. Upload the XML-file.

Verify metadata URL of the SP, samltest.id

The SP in this case will present the metadata through an url. This is already configured in the IdP config.json file. Below is a screenshoot of that location in the config.json file.

"metadata": [{
    "url": "https://samltest.id/saml/sp"

Test the configuration

Login to samltest.id using Integrity WEB as IdP

1. Open a browser

2. Browse to https://samltest.id/start-idp-test/

3. Type the name of the IdP entityID your created before, e.g. testip123, in the login initiator and then click Go!

4. You should be redirected to the IdP and see the following:
5. Login as StaticSAMLData or as a LDAP user. StaticSAMLData uses a user from the configuration file. This is to rule out any external connection to a e.g. LDAP user store. This is to test the SAML communication only. A good practice is to always test this first and then testan LDAP user. In the configuration file you will find StaticSAMLData user data on line 126-141.

6. You should now be redirected back successfully to samltest.id. The user data that also will be send to the SP if available, we call this additional_attribute_parameter in the config-file, is ["givenName", "sn", "mail", "roles", "display_name"].

   1. StaticSAMLData. Use data is added to json file.

   2. LDAP. For LDAP you might need to query LDAP to fetch data to send with the SAML session. This can be done using pipes. Before wending user back to SP you can use a parameter called pre_assertion_pipe to call a pipe to fetch necessary data.

   3. Tip. Use a SAML tracers for your browser to view the data added.

Complete config.json file

{
  "globals": {
    "file_paths": {
      "base_dir": "../customer"
    },
    "http": {
      "http_port": 8080
    },
    "ldap": {
      "base_dn": "dc=company,dc=local",
      "host": "127.0.0.1",
      "port": 636,
      "bind_dn": "CN=admin,CN=Users,DC=company,DC=local",
      "bind_password": "password_for_the_ldap_account"
    },
    "keystore": {
      "alias": "fortifiedid",
      "key_password": "fortifiedid",
      "password": "fortifiedid",
      "path": "/config/resources_internal/certificates/fortifiedid.p12"
    }
  },
  "modules": [
    {
      "name": "CefEventModule",
      "config": {}
    },
    {
      "name": "LdapClient",
      "enabled": true,
      "instances": 1,
      "config": {
        "name": "default",
        "connection": {
          "host": "${globals.ldap.host}",
          "port": "${globals.ldap.port}",
          "bind_dn": "${globals.ldap.bind_dn}",
          "bind_password": "${globals.ldap.bind_password}",
          "use_ssl": true,
          "ssl_trust_all": true
        }
      }
    },
    {
      "name": "HttpClient",
      "config": {
        "name": "default",
        "idle_timeout_ms": 5000,
        "connect_timeout_ms": 5000
      }
    },
    {
      "name": "SAML",
      "config": {
        "metadata_cache": "${globals.file_paths.base_dir}/cache",
        "http_port": "${globals.http.http_port}",
        "enable_http": true,
        "metadata_template": [
          {
            "id": "fortifiedid_web_saml_idp_1",
            "metadata_file_path": "${globals.file_paths.base_dir}/config/resources_internal/saml_idp_templates/fortifiedid_web_saml_idp_1_template.xml",
            "sign_ref": [
              {
                "keystore": {
                  "alias": "${globals.keystore.alias}",
                  "key_password": "${globals.keystore.key_password}",
                  "password": "${globals.keystore.password}",
                  "path": "${globals.file_paths.base_dir}${globals.keystore.path}"
                }
              }
            ]
          }
        ],
        "metadata": [
          {
            "url": "https://samltest.id/saml/sp"
          }
        ]
      }
    },
    {
      "name": "AuthN",
      "enabled": true,
      "config": {
        "context_path": "/authn",
        "webroot_dir": "web",
        "authenticators": [
          {
            "id": "auth00",
            "type": "SAMLIDP",
            "config": {
              "context_path": "/saml/authn/chain",
              "base_path": "/saml/authn",
              "force_re_auth": true,
              "idp": "https://fortifiedid.se/test_idp_1",
              "chain": [
                {
                  "id": "oidc_rp",
                  "required": true
                }
              ],
              "assertion_config": [
                {
                  "target_sp": [
                    "*"
                  ],
                  "nameid_paramter": "mail",
                  "additional_attribute_parameter": [
                    "mail"
                  ],
                  "pre_assertion_pipe": "Retrieve_data_for_SAML_response"
                }
              ]
            }
          },
          {
            "id": "oidc_rp",
            "type": "OIDCRP",
            "config": {
              "base_path": "/saml/authn",
              "discovery_metadata_url": "https://oidc.difi.no/idporten-oidc-provider/.well-known/openid-configuration",
              "internal_http_destination": "default",
              "client_id": "${globals.oidcrp.client_id}",
              "client_secret": "${globals.oidcrp.client_secret}",
              "redirect_uri": "https://integrity.example.org/saml/authn/oidc_rp"
            }
          }
        ]
      }
    },
    {
      "name": "Pipes",
      "config": {
        "pipes": [
          {
            "id": "Retrieve_data_for_SAML_response",
            "config": {
              "valves": [
                {
                  "name": "LDAPSearch",
                 "enabled": true,
                  "config": {
                    "destination": "default",
                    "base_dn": "${globals.ldap.base_dn}",
                    "scope": "SUB",
                    "filter": "serialNumber={{{request.pid}}}",
                    "attributes": [
                      {
                        "name": "mail",
                        "multivalue": false
                      }
                    ]
                  }
                }
                
              ]
            }
          }
        ]
      }
    }
  ]
}