Microsoft Entra (SAMLSPBroker)

Scenario

In this scenario, a web resource, Fortified ID Portal, will be protected by an "external SAML IdP" for authentication.

The external SAML IdP is Microsoft Entra. The web resource Fortified ID Portal will act as an SAML SP. Fortified ID WEB will act as a SAML SP to Microsoft Entra and SAML IdP for Fortified ID Portal.

The user is also authorized against an LDAP directory for additional attributes to be fetched. This step is optional.

Prerequisite

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

• This use case assumes that you have good knowledge of the product in question.

• You need an Microsoft Entra tenant.

• Fortified ID WEB installed and configured.

• LDAP directory. The remote authenticated users are validated against this directory and attributes are fetched from the LDAP object. The example configuration is configured using an Active Directory. We are using mail attribute on the Active Directory user for authentication.

• Fortified ID Portal installed and configured. (you can use any SAML SP connected to Fortified ID WEB SAML IdP of course).

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

Basic configuration of Fortified ID Web and Portal

Install and prepare configuration

1. Download and install Fortified ID Web and Fortified ID Portal

   1. To install Integrity Web and Integrity Portal, see documentation and installation.

2. Add files and folders from ZIP-file to Fortified ID Web and Fortified ID Portal.

   1. Download the microsoft_entra_use_case.zip.

3. Replace the customer folders for your installations with the ones from the zip-file. Note. This use case was initially done on a Windows server, if you run Container/Docker or Linux you might have to changes something to work in your environments like file paths e.g..

4. Open the globals.json in both customer folders and update to match your environment.

Configure your Microsoft Entra tenant

Login to Entra admin portal

1. Open a browser and browse to https://entra.microsoft.com

2. Login to access your Microsoft Entra tenant

Create and configure an enterprise application

1. Find Enterprise application admin view

   1. Click in the search field

   2. Type Enterprise applications

   3. Click Enterprise applications in result

2. Create an application

   1. Click New application

   2. Click Create your own application

   3. Type a name, e.g. Fortified ID Integrity WEB

   4. Click Create

3. Configure your application

   1. Under heading Getting Started

   2. Under heading 1. Assign users and groups, click Assign users and groups

      1. Click Add user/group

      2. Select the users that should be able to login

      3. Click Assign

   3. Click Overview in settings for your applications

   4. Under heading 2. Set up single sign on, click Get started

      1. Click SAML if asked

      2. Under Basic SAML Configuration click Edit

         1. In Identifier (Entity ID) section

         2. Click Add identifier In our example it is https://fortifiedid.se/sp_entra You will see where this value is created later when we look at SAML SP metadata template file

         3. In Reply URL (Assertion Consumer Service URL) section

         4. Click Add reply URL In our example it is https://dev.fortifiedid.se/saml/authn/microsoft_entra Change the URL for dev.fortifiedid.se to your address You will see where this value is created later when we look at SAML SP metadata template file

      3. Under Attributes & Claims click Edit (for this use case I have added two additional claims)

         1. display_name_from_entra < - > user.displayname

         2. username_from_entra < - > user.department In department I added the userid used in Active Directory for mapping identities. In this use case we use mail in Active Directory. For example. If I login as [e-mail] I need to map it to an identity in Active Directory, for example [e-mail]. In this use case I added [e-mail] to department corresponding user [e-mail] in Entra.

Save some values for later

Save value for "App Federation Metadata Url"

1. Click Overview for your Enterprise applications

2. Under heading 2. Set up single sign on, click Get started

3. Under heading SAML Certificates (section 3)

4. Copy value of App Federation Metadata Url and save it for later

5. Value look like https://login.microsoftonline.com/xxx/federationmetadata/2007-06/federationmetadata.xml?appid=yyy xxx and yyy are unique values for your Entra tenant

Save value for "Microsoft Entra Identifier"

1. Click Overview for your Enterprise applications

2. Under heading 2. Set up single sign on, click Get started

3. Under heading Set up your app name (section 4)

4. Copy value of Microsoft Entra Identifier and save it for later

5. Value look like https://sts.windows.net/zzz zzz is a unique value for your Entra tenant

Configure Fortified ID WEB

Summary of things to configure in Fortified ID WEB

Note that the config.json file of Fortified ID WEB is already configure, you just going to add your environment data like Microsoft Entra values from previous step.

• Update config.json

• Update SAML metadata template file

Open and configure config.json

You can also have globals.json open as reference.

There are three (3) parts in config.json to mention/configure.

1. Change metadata URL to your Microsoft Entra IdP metadata URL

   1. Go to line 73

   2. Change the url address below to your App Federation Metadata Url value (this is the value you copied in the previous step) https://login.microsoftonline.com/xxx/federationmetadata/2007-06/federationmetadata.xml?appid=yyy

2. Change value for target_idp_entity to your Microsoft Entra Identifier URL value

   1. Go to line 150

   2. Change the url address below to your Microsoft Entra Identifier value (this is the value you copied in the previous step) https://sts.windows.net/zzz

3. Verify configuration for SAML metadata for Fortified ID WEB acting as SAML SP.

   1. Go to line 53-64

   2. This is data you might like to change or use the use case data for testing.

Open and configure SAML SP metadata template file

1. In file system, open folder drive:\FortifiedID\web\customer\config\resources_internal\saml\metadata_template

2. Open the file fortifiedid_samlspbroker_entra_template.xml

3. In entityID you will find the value we used in previous step when configure Entra to use this Fortified ID SAML SP We use https://fortifiedid.se/sp_entra as entityID

4. In Location you will find the value we used in previous step when configure Entra to use this Fortified ID SAML SP Change the URL for Location from dev.fortifiedid.se to your address

Start services and test solution

Start the Fortified ID WEB service

Start the service and verify the start by looking thru the server.log file.

Start the Fortified ID Portal service

Start the service and verify the start by looking thru the server.log file

Login to Portal using your Microsoft Entra account

1. Open a browser

2. Browse to https://dev.fortifiedid.se/portal/ Change dev.fortifiedid.se to map your environment.

3. You should now been redirected to Entra login page

4. Login using your Microsoft Entra ID

5. You should now be logged in to Fortified ID Portal

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

Complete config.json file for Fortified ID WEB

{
    "globals": "@include:globals.json",
    "modules": [
        {
            "name": "CefEventModule",
            "config": {}
        },
        {
            "name": "HttpClient",
            "config": {
                "name": "default",
                "idle_timeout_ms": 5000,
                "connect_timeout_ms": 5000
            }
        },
        {
            "name": "LdapClient",
            "enabled": true,
            "instances": 1,
            "config": {
                "name": "${globals.ldap.ldap1.name}",
                "connection": {
                    "host": "${globals.ldap.ldap1.connection.host}",
                    "port": "${globals.ldap.ldap1.connection.port}",
                    "bind_dn": "${globals.ldap.ldap1.connection.bind_dn}",
                    "bind_password": "${globals.ldap.ldap1.connection.bind_password}",
                    "use_ssl": "${globals.ldap.ldap1.connection.use_ssl}",
                    "ssl_trust_all": "${globals.ldap.ldap1.connection.ssl_trust_all}"
                }
            }
        },
        {
            "name": "SAML",
            "config": {
                "metadata_cache": "${globals.saml.idp1.metadata_cache}",
                "http_port": "${globals.http.port}",
                "enable_http": true,
                "metadata_template": [
                    {
                        "id": "${globals.saml.idp1.metadata_id}",
                        "metadata_file_path": "${globals.saml.idp1.metadata_file_path}",
                        "sign_ref": [
                            {
                                "keystore": {
                                    "alias": "${globals.keystore.saml.sign_ref_keystore_alias}",
                                    "key_password": "${globals.keystore.saml.sign_ref_keystore_key_password}",
                                    "password": "${globals.keystore.saml.sign_ref_keystore_password}",
                                    "path": "${globals.keystore.saml.sign_ref_keystore_path}"
                                }
                            }
                        ]
                    },
                    {
                        "id": "${globals.saml.samlspbroker_microsoft_entra.metadata_id}",
                        "metadata_file_path": "${globals.saml.samlspbroker_microsoft_entra.metadata_file_path}",
                        "sign_ref": [
                            {
                                "keystore": {
                                    "alias": "${globals.keystore.saml.sign_ref_keystore_alias}",
                                    "key_password": "${globals.keystore.saml.sign_ref_keystore_key_password}",
                                    "password": "${globals.keystore.saml.sign_ref_keystore_password}",
                                    "path": "${globals.keystore.saml.sign_ref_keystore_path}"
                                }
                            }
                        ]
                    }
                ],
                "metadata": [
                    {
                        "path": "${globals.file_paths.base_dir}/config/resources_internal/saml/sp_metadata_files/sp_portal.xml"
                    },
                    {
                        "url": "https://login.microsoftonline.com/xxx/federationmetadata/2007-06/federationmetadata.xml?appid=yyy"
                    }
                ]
            }
        },
        {
            "name": "AuthN",
            "enabled": true,
            "config": {
                "context_path": "/authn",
                "webroot_dir": "web",
                "http_csrf": {
                    "enabled": false
                },
                "authenticators": [
                    {
                        "id": "auth00",
                        "type": "SAMLIDP",
                        "config": {
                            "context_path": "/saml/authn/chain",
                            "base_path": "/saml/authn",
                            "expiry": "PT1S",
                            "force_re_auth": false,
                            "idp": "${globals.saml.idp1.idp_entityid}",
                            "chain": [
                                {
                                    "id": "selector_root",
                                    "required": true
                                }
                            ],
                            "assertion_config": [
                                {
                                    "target_sp": [
                                        "FortifiedID_Portal"
                                    ],
                                    "nameid_parameter": "mail",
                                    "auth_context_parameter": "AuthnContextClassRef",
                                    "additional_attribute_parameter": [
                                        "givenName",
                                        "sn",
                                        "mail",
                                        "roles",
                                        "display_name",
                                        "distinguishedName"
                                    ],
                                    "pre_assertion_pipe": "Retrieve_data_for_SAML_response_for_Portal"
                                }
                            ]
                        }
                    },
                    {
                        "id": "selector_root",
                        "type": "Selector",
                        "config": {
                            "base_path": "/saml/authn",
                            "webroot_dir": "web/authenticator/selector",
							"auto_select": false,
                            "overlay_dirs": [
                                "${globals.file_paths.base_dir}/config/resources_external/overlays/1_selector_root",
                                "${globals.file_paths.base_dir}/config/resources_external/overlays/0_look_and_feel"
                            ],
                            "options": [
                                {
                                    "id": "1",
                                    "target": "microsoft_entra",
                                    "label": "samlspbroker_label",
                                    "logo": "assets/svg/microsoft.svg"
                                }
                            ]
                        }
                    },
                    {
                        "id": "microsoft_entra",
                        "type": "SAMLSPBroker",
                        "config": {
                            "base_path": "/saml/authn",
                            "issue_as_sp_entity": "https://fortifiedid.se/sp_entra",
                            "target_idp_entity": "https://sts.windows.net/zzz"
                        },
                        "exports": [
                            {
                                "name": "used_auth",
                                "value": "microsoft_entra"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "name": "Pipes",
            "config": {
                "pipes": [
                    {
                        "id": "Retrieve_data_for_SAML_response_for_Portal",
                        "config": {
                            "valves": [
                                {
                                    "name": "DumpRequest",
                                    "config": {
                                        "label": "*** DumpRequest från DumpData Portal****"
                                    }
                                },
                                {
                                    "name": "DumpExports",
                                    "config": {
                                        "label": "*** DumpExports från DumpData Portal****"
                                    }
                                },
                                {
                                    "name": "ExportsPut",
                                    "exec_if_expr": "exports.used_auth == ('microsoft_entra')",
                                    "enabled": true,
                                    "config": {
                                        "name": "LDAP_search_filter",
                                        "value": "mail={{{exports.username_from_entra}}}",
                                        "replace": true
                                    }
                                },
                                {
                                    "name": "LDAPSearch",
                                    "enabled": true,
                                    "config": {
                                        "destination": "${globals.ldap.ldap1.name}",
                                        "base_dn": "${globals.ldap.ldap1.connection.base_dn}",
                                        "scope": "SUB",
                                        "filter": "{{{exports.LDAP_search_filter}}}",
                                        "attributes": [
                                            {
                                                "name": "givenName",
                                                "multivalue": false
                                            },
                                            {
                                                "name": "sn",
                                                "multivalue": false
                                            },
                                            {
                                                "name": "sAMAccountName",
                                                "multivalue": false
                                            },
                                            {
                                                "name": "mail",
                                                "multivalue": false
                                            },
                                            {
                                                "name": "carLicense",
                                                "multivalue": true
                                            },
                                            {
                                                "name": "displayName",
                                                "multivalue": false
                                            },
                                            {
                                                "name": "distinguishedName",
                                                "multivalue": false
                                            }
                                        ]
                                    }
                                },
                                {
                                    "name": "ExportsPut",
                                    "enabled": true,
                                    "config": {
                                        "name": "username",
                                        "value": "{{{item.mail}}}",
                                        "replace": true
                                    }
                                },
                                {
                                    "name": "ItemPropertyAdd",
                                    "enabled": true,
                                    "config": {
                                        "name": "display_name",
                                        "value": "{{{exports.display_name_from_entra}}}"
                                    }
                                },
                                {
                                    "name": "ItemPropertyRename",
                                    "enabled": true,
                                    "config": {
                                        "old_name": "carLicense",
                                        "new_name": "roles"
                                    }
                                },
                                {
                                    "name": "DumpExports",
                                    "config": {
                                        "label": "*** DumpExports****"
                                    }
                                },
                                {
                                    "name": "DumpState",
                                    "config": {
                                        "label": "*** DumpState ***"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}