Password Reset for Entra ID

Reset a password for yourself in Microsoft Entra ID, using Swedish BankID as the verification method.

Scenario

In this use case there is one scenario:

• Password Reset using Self service. In this scenario you will login as yourself using your BankID.

This scenario could easily be copied and modified to fulfill:

• Using other eID methods to reset the password, such as SITHS, EFOS, Freja, Norwegian ID-porten, Foreign eID (eIDAS) or Suomi.fi

Prerequisite

• FortifiedID Integrity Web current version installed

• Fortified Password Reset current version installed

• BankID certificate. To be able to communicate with bankid backend.

• Entra ID (Azure AD) administration rights. Azure P1 license, or higher.

• Host (DNS) name of the Integrity service (external access)

• Host (DNS) name of the Password reset service (external access)

• Social security number (personnummer) stored on the Entra ID user object. The attribute name holding the value is also required.

• Outgoing TCP/443 communication. To be able to communicate with BankID backend and Entra ID services.

Configuration

Download and add configuration

Remember that this use case does not describe installation of the products. Products are expected to be installed in advance.

1. Download ZIP containing configuration for Web and Password Reset

   1. Click USE_CASE_LINK to download customer folders for Web and PWDReset.

2. Add Integrity WEB configuration to your environment.

   1. Rename the existing customer folder to customer_ORG and add the customer folder to your \..\fortifiedid\web\ folder. .

3. Add Password Reset configuration to your environment.

   1. Add the customer-pwdreset folder to you \..\fortifiedid\pwdreset\ folder. Rename the existing customer folder to customer_ORG and rename the added one to \customer.

Update the Entra ID configuration

Create App Registration

• Login to Entra ID as an administrator

• Select App Registrations

• Click New Registration

• Enter a name of the app registration, Fortified ID Password reset

• Select Accounts in this organizational directory only (<tenant_name> only - Single tenant)

• Register

• Click on the App Registration in the list

• Select API permissions

• Add a permission

  • Microsoft Graph->Application Permissions->User.Read.All

• In the Overview section, copy these values (they will be used in later steps):

  • Application (client) ID

  • Object ID

  • Directory (tenant) ID

• Extract the certificate chain from the keystore file referenced in the globals entra->ssl_keystore_path, using this guide. This should result in a certificate file that will be used in next step.

• Select Certificates & secrets

• Select Certificates

• Click Upload certificate

• Select the certificate file

• Click Save

• Select Microsoft Entra roles and administrators

• Open the role User administrator

• Select Add assignment

• Enter Fortified ID Password Reset

• Select and Add

Update the configuration to map your environment

The downloaded folders contains all information needed. For example, a test certificate and metadata files are included and configured to work with the example applications. However, some data needs to be changed to map your environment. You need to update the Entra settings to map your environment. Also the http ports might need to be changed if they are not available in your environment.

Integrity Web

Globals

In this section we will look at parts of the configuration and add/replace data for 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 just update it in one place.

Open the file customer/config/globals.json. Change according to the instructions below.

1. base_dir

   1. 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 should be: "base_dir": "../customer"

      2. For Docker, the value should be: "base_dir": ".",

   "base_dir": "../customer"

2. host Set the host value to your Integrity Web DNS name entry, including https://.

   "host": "https://be4f-194-68-171-97.ngrok-free.app",

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. ! The recommendation is to always use SSL to encrypt the communication to Integrity Web.

    "http": {
               "http_port": 443,
               "http_use_ssl": true
           }

4. keystore - https

   Either you use the test certificate provided by us, if so you do not need to change anything. If you have a keystore then update the values below to point to your keystore.

   1. Find in section: keystore

      "https": {
                      "ref": {
                          "path": "${globals.base_dir}/config/resources_internal/certificates/fortifiedid.p12",
                          "password": "password"
                      },
                      "http_key_alias": "1",
                      "http_key_password": "password"
                  },

5. keystore - bankid

   For connecting against BankID test environment, you don't need to do anything. For production connectivity, please use your BankID keystore and change the variables below to reflect that. Truststore changes will not be needed. Find in section: keystore

              "bid": {
                   "ssl_keystore_path": "${globals.base_dir}/config/resources_internal/certificates/BankID/bankid_test_rp.p12",
                   "ssl_keystore_password": "qwerty123",
                   "ssl_key_alias": "1",
                   "ssl_key_password": "qwerty123",
                   "ssl_truststore_path": "${globals.base_dir}/config//resources_internal/certificates/trust_jks/bankidtrust.jks",
                   "ssl_truststore_password": "password"
               },

6. keystore - entra The keystore used for connecting to Entra ID, to perform a user lookup. For test environments, you may use the test certificate provided by us, if so you do not need to change anything. For production environments, you should use your own keystore and update the values below to point to that keystore. This must map to the certificate uploaded to Entra in previous step.

               "entra": {
                   "ssl_keystore_path": "${globals.base_dir}/config/resources_internal/certificates/fortifiedid.p12",
                   "ssl_keystore_password": "password"
               },

7. keystore - saml The keystore used to sign SAML assertions. For test environments, you may use the test certificate provided by us, if so you do not need to change anything. For production environments, you should use your own keystore and update the values below to point to that keystore.

               "saml": {
           	    "alias": "1",
            	    "key_password": "password",
            	    "password": "password",
          		    "path": "${globals.base_dir}/config/resources_internal/certificates/fortifiedid.p12"
               }

8. entra Set client_id and tenant_id to the value fetched in previous step. Set mfa_identifier_attribute to the Entra ID user object attribute containing the eID identifier value (for BankID = social security number).

       "entra": {
            "client_id": "xxxx-cb9c-4dbf-yyy-ssssss",
            "tenant_id": "dddd-eeee-eeee-fff-e3f55f4afbd4",
            "mfa_identifier_attribute": "extensionAttribute1"
       }    	  

Save the globals.json file.

Start the Integrity web service and verify the start by looking through the server.log file.

Open a web browser and browse to https://<integrity_web_host>/saml/metadata/integrity_idp_entra_pwdreset

Save the downloaded file as \..\fortifiedid\pwdreset\config\resources_external\saml_meta\integrity_idp_entra_pwdreset.xml

Password reset

Globals

In this section we will look at parts of the configuration and add/replace data for 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 just update it in one place.

Open the file customer/config/config.json and locate the globals section. Change according to the instructions below.

1. base_dir

   1. 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 should be: "base_dir": "../customer"

      2. For Docker, the value should be: "base_dir": ".",

   "file_path": {
               "base_dir": "."
                },

2. http

   Update the http information to map your environment. This is the port that Integrity Web will use to host the SAML IdP service. ! The recommendation is to always use SSL to encrypt the communication to Integrity Web.

    "http": {
               "http_port": 8446,
               "http_use_ssl": true
           }

3. keystore - https

   Either you use the test certificate provided by us, if so you do not need to change anything. If you have a keystore then update the values below to point to your keystore.

   1. Find in section: keystore

      "https": {
                      "ref": {
                          "path": "${globals.base_dir}/config/resources_internal/certificates/fortifiedid.p12",
                          "password": "password"
                      },
                      "http_key_alias": "1",
                      "http_key_password": "password"
                  },

4. keystore - entra The keystore used for connecting to Entra ID, to perform a password reset. For test environments, you may use the test certificate provided by us, if so you do not need to change anything. For production environments, you should use your own keystore and update the values below to point to that keystore. This must map to the certificate uploaded to Entra in previous step.

               "entra": {
                   "ssl_keystore_path": "${globals.base_dir}/config/resources_internal/certificates/fortifiedid.p12",
                   "ssl_keystore_password": "password"
               },

5. keystore - saml The keystore used to sign SAML requests. For test environments, you may use the test certificate provided by us, if so you do not need to change anything. For production environments, you should use your own keystore and update the values below to point to that keystore.

               "saml": {
           	    "alias": "1",
            	    "key_password": "password",
            	    "password": "password",
          		    "path": "${globals.base_dir}/config/resources_internal/certificates/fortifiedid.p12"
               }

6. entra Set client_id and tenant_id to the value fetched in previous step.

       "entra": {
            "client_id": "xxxx-cb9c-4dbf-yyy-ssssss",
            "tenant_id": "dddd-eeee-eeee-fff-e3f55f4afbd4"
       }    	  

Save the config.json file.

Open the file /config/resources_internal/saml_sp_metadata_template/fortifiedid_pwdreset_saml_sp_template.xml.

Change PWDRESET-HOSTNAME to the DNS name of Password Reset.

Save the file.

Start the Password reset service and verify the start by looking through the server.log file.

Copy the file in the folder /config/resources_internal/saml_sp_metadata. Paste it into /fortifiedid/web/customer/config/resources_internal/saml_sp_metadata_files (replace existing file).

Restart Integrity Web.

Testing the use case

Self - Password Reset

1. Browse to https://PWDRESET-HOSTNAME/pwdreset

2. Authenticate with BankID

3. Enter a password (follow the on-screen instructions)

4. The password was updated.

5. Try to logon to Entra with the newly set password.

Check server.log files (both Integrity Web and Password Reset) to find errors. Fix accordingly.

Complete config.json file of Password Reset

The config.json of Password reset can be found in the associated zip-file in this use case.

{
    "globals": {
        "file_path": {
            "base_dir": "."
        },
        "http": {
            "port": 8446
        },
        "keystore": {
            "https": {
                "ref": {
                    "type": "pkcs12",
                    "path": "${globals.file_path.base_dir}/config/resources_internal/certificates/fortifiedid.p12",
                    "password": "password"
                },
                "type": "pkcs12",
                "http_key_alias": "1",
                "http_key_password": "password"
            },
            "saml": {
                "sign_ref_keystore_path": "${globals.file_path.base_dir}/config/resources_internal/certificates/fortifiedid.p12",
                "sign_ref_keystore_password": "password",
                "sign_ref_keystore_alias": "1",
                "sign_ref_keystore_key_password": "password"
            },
            "entra": {
                "ssl_keystore_path": "${globals.file_path.base_dir}/config/resources_internal/certificates/fortifiedid.p12",
                "ssl_keystore_password": "password"
            }
        },
        "entra": {
            "client_id": "xxxx-cb9c-4dbf-yyy-ssssss",
            "tenant_id": "dddd-eeee-eeee-fff-e3f55f4afbd4",
            "mfa_identifier_attribute": "extensionAttribute18"
        }
    },
    "modules": [
        {
            "name": "EntraID",
            "config": {
                "namespace": "entra_lookup",
                "http_client_name": "default",
                "client_id": "${globals.entra.client_id}",
                "tenant_id": "${globals.entra.tenant_id}",
                "certificate_file_path": "${globals.keystore.entra.ssl_keystore_path}",
                "certificate_password": "${globals.keystore.entra.ssl_keystore_password}"
            }
        },
        {
            "name": "CefEventModule",
            "config": {}
        },
        {
            "name": "HttpClient",
            "config": {
                "name": "default",
                "ssl_trust_all": true,
                "idle_timeout_ms": 5000,
                "connect_timeout_ms": 5000
            }
        },
        {
            "name": "PasswordReset",
            "config": {
                "http_port": "${globals.http.port}",
                "webroot_dir": "resources/web",
                "http_use_ssl": true,
                "http_keystore_ref": {
                    "type": "${globals.keystore.https.ref.type}",
                    "path": "${globals.keystore.https.ref.path}",
                    "password": "${globals.keystore.https.ref.password}"
                },
                "http_keystore_type": "${globals.keystore.https.type}",
                "http_key_alias": "${globals.keystore.https.http_key_alias}",
                "http_key_password": "${globals.keystore.https.http_key_password}",
                "http_context": "/pwdreset",
                "http_auth_redirect_url": "/pwdreset/authn/login",
                "overlay_dirs": [
                    "${globals.file_path.base_dir}/config/resources_external/overlays/1_pwdreset",
                    "${globals.file_path.base_dir}/config/resources_external/overlays/0_look_and_feel"
                ],
                "pipe_id": "Reset_Password",
                "rules": "@include:rules.json"
            }
        },
        {
            "name": "AuthN",
            "config": {
                "http_context": "/authn",
                "http_port": "${globals.http.port}",
                "http_use_ssl": true,
                "http_keystore_ref": {
                    "type": "${globals.keystore.https.ref.type}",
                    "path": "${globals.keystore.https.ref.path}",
                    "password": "${globals.keystore.https.ref.password}"
                },
                "http_keystore_type": "${globals.keystore.https.type}",
                "http_key_alias": "${globals.keystore.https.http_key_alias}",
                "http_key_password": "${globals.keystore.https.http_key_password}",
                "authenticators": [
                    {
                        "id": "sp_pwdreset",
                        "type": "SAMLSP",
                        "config": {
                            "context_path": "/pwdreset/authn/login",
                            "success_location": "/pwdreset/",
                            "logout_location": "/pwdreset/logged_out",
                            "metadata_output_directory": "${globals.file_path.base_dir}/config/resources_internal/saml_sp_metadata",
                            "metadata": {
                                "path": "${globals.file_path.base_dir}/config/resources_external/saml_meta/integrity_idp_entra_pwdreset.xml"
                            },
                            "entity_id": "FortifiedID_PWD_Reset",
                            "metadata_file_path": "${globals.file_path.base_dir}/config/resources_internal/saml_sp_metadata_template/fortifiedid_pwdreset_saml_sp_template.xml",
                            "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}"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        {
            "name": "Pipes",
            "config": {
                "pipes": [
                    {
                        "id": "Reset_Password",
                        "config": {
                            "valves": [
                                {
                                    "name": "PipeExec",
                                    "exec_if_expr": "request.on_behalf_of_user_name == null",
                                    "config": {
                                        "pipe": "Find_User_and_Do_Password_Reset_of_Authenticated_User"
                                    }
                                },
                                {
                                    "name": "PipeExec",
                                    "exec_if_expr": "request.on_behalf_of_user_name != null",
                                    "config": {
                                        "pipe": "Find_Selected_User_and_Do_Password_Reset_Authenticated_On_Behalf_of_User"
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "id": "Find_User_and_Do_Password_Reset_of_Authenticated_User",
                        "config": {
                            "valves": [
                                {
                                    "name": "EntraIDResetPassword",
                                    "config": {
                                        "namespace": "entra_lookup",
                                        "ignore_error": true,
                                        "user_id": "{{{request.user_name}}}",
                                        "new_password": "{{{request.new_password}}}",
                                        "force_change_password_next_signin": false
                                    }
                                },
                                {
                                    "name": "FlowFail",
                                    "exec_if_expr": "(state.items && state.items.length > 0 && state.items[0].message === 'The specified password does not comply with password complexity requirements. Please provide a different password.')",
                                    "config": {
                                        "message": "PWDRESET_ERROR_PASSWORD_RESTRICTION"
                                    }
                                },
                                {
                                    "name": "FlowFail",
                                    "exec_if_expr": "state.items && state.items.length > 0",
                                    "config": {
                                        "message": "Failed to reset password!"
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "id": "Find_Selected_User_and_Do_Password_Reset_Authenticated_On_Behalf_of_User",
                        "config": {
                            "valves": [
                                {
                                    "name": "EntraIDResetPassword",
                                    "config": {
                                        "namespace": "entra_lookup",
                                        "ignore_error": true,
                                        "user_id": "{{{request.on_behalf_of_user_name}}}",
                                        "new_password": "{{{request.new_password}}}",
                                        "force_change_password_next_signin": false
                                    }
                                },
                                {
                                    "name": "FlowFail",
                                    "exec_if_expr": "(state.items && state.items.length > 0 && state.items[0].message === 'The specified password does not comply with password complexity requirements. Please provide a different password.')",
                                    "config": {
                                        "message": "PWDRESET_ERROR_PASSWORD_RESTRICTION"
                                    }
                                },
                                {
                                    "name": "FlowFail",
                                    "exec_if_expr": "state.items && state.items.length > 0",
                                    "config": {
                                        "message": "Failed to reset password!"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

Complete config.json file of Integrity Web

The config.json of Web can be found in the associated zip-file in this use case.

{
    "globals": "@include:./globals.json",
    "modules": [
        {
            "name": "CefEventModule",
            "config": {}
        },
        {
            "name": "HttpClient",
            "config": {
                "name": "default",
                "idle_timeout_ms": 5000,
                "connect_timeout_ms": 5000,
                "ssl_trust_all": true
            }
        },
        {
            "name": "HttpClient",
            "config": {
                "name": "bankid_http_outgoing",
                "idle_timeout_ms": 5000,
                "connect_timeout_ms": 5000,
                "ssl_keystore_path": "${globals.keystore.bid.ssl_keystore_path}",
                "ssl_keystore_password": "${globals.keystore.bid.ssl_keystore_password}",
                "ssl_key_alias": "${globals.keystore.bid.ssl_key_alias}",
                "ssl_key_password": "${globals.keystore.bid.ssl_key_password}",
                "ssl_truststore_path": "${globals.keystore.bid.ssl_truststore_path}",
                "ssl_truststore_password": "${globals.keystore.bid.ssl_truststore_password}",
                "request_timeout_ms": 3500
            }
        },
        {
            "name": "EntraID",
            "config": {
                "namespace": "entra_lookup",
                "http_client_name": "default",
                "client_id": "${globals.entra.client_id}",
                "tenant_id": "${globals.entra.tenant_id}",
                "certificate_file_path": "${globals.keystore.entra.ssl_keystore_path}",
                "certificate_password": "${globals.keystore.entra.ssl_keystore_password}"
            }
        },
        {
            "name": "SAML",
            "config": {
                "http_port": "${globals.http.port}",
                "enable_http": true,
                "metadata_cache": "${globals.base_dir}/config/resources_internal/saml_cache",
                "metadata_template": [
                    {
                        "id": "integrity_idp_entra_pwdreset",
                        "metadata_file_path": "${globals.base_dir}/config/resources_internal/saml_templates/integrity_entra_idp_pwdreset_template.xml",
                        "sign_ref": [
                            {
                                "keystore": {
                                    "path": "${globals.keystore.saml.path}",
                                    "password": "${globals.keystore.saml.password}",
                                    "alias": "${globals.keystore.saml.alias}",
                                    "key_password": "${globals.keystore.saml.key_password}"
                                }
                            }
                        ]
                    }
                ],
                "metadata": [
                    {
                        "path": "${globals.base_dir}/config/resources_internal/saml_sp_metadata_files/sp_pwdreset.xml"
                    }
                ]
            }
        },
        {
            "name": "AuthN",
            "enabled": true,
            "config": {
                "context_path": "//authn",
                "webroot_dir": "web",
                "http_port": "${globals.http.port}",
                "authenticators": [
                    {
                        "id": "auth00",
                        "type": "SAMLIDP",
                        "config": {
                            "force_re_auth": false,
                            "expiry": "PT10S",
                            "context_path": "/saml/authn/idp",
                            "base_path": "/saml/authn",
                            "idp": "${globals.host}/idp",
                            "chain": [
                                {
                                    "id": "bidomd",
                                    "required": true
                                },
                                {
                                    "id": "entra_lookup",
                                    "required": true
                                }
                            ],
                            "assertion_config": [
                                {
                                    "target_sp": [
                                        "FortifiedID_PWD_Reset"
                                    ],
                                    "nameid_parameter": "oid",
                                    "additional_attribute_parameter": [
                                    ]
                                }
                            ]
                        }
                    },
                    {
                        "id": "bidomd",
                        "type": "BidOnMobileDevice",
                        "config": {
                            "mode": "test",
                            "base_path": "/saml/authn",
                            "internal_http_destination": "bankid_http_outgoing",
                            "webroot_dir": "web/authenticator/bankid/omd",
                            "exports": [
                                {
                                    "name": "amr",
                                    "value": "swk"
                                },
                                {
                                    "name": "acr",
                                    "value": "possessionorinherence"
                                }
                            ]
                        }
                    },
                    {
                        "id": "entra_lookup",
                        "type": "AuthController",
                        "config": {
                            "base_path": "/saml/authn",
                            "pipe_id": "pipe_entra_lookup",
                            "fail_location": "/error",
                            "failed_redirect": []
                        }
                    }
                ]
            }
        },
        {
            "name": "Pipes",
            "config": {
                "pipes": [
                    {
                        "id": "pipe_entra_lookup",
                        "config": {
                            "valves": [
                                {
                                    "name": "EntraIDListUsers",
                                    "config": {
                                        "namespace": "entra_lookup",
                                        "filter": "startswith(${globals.entra.mfa_identifier_attribute},'{{{request.personalNumber}}}')",
                                        "select": "id",
                                        "id_property": "id",
                                        "min": 1,
                                        "max": 1
                                    }
                                },
                                {
                                    "name": "ExportsPut",
                                    "config": {
                                        "name": "oid",
                                        "value": "{{{item.id}}}"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}