Safewhere*PasswordReset

Safewhere*PasswordReset User Guideline 1.0 Page 1

Safewhere*PasswordReset Contents Safewhere*PasswordReset... 2 1. System Requirements... 3 2. Introduction... 3 3. Glossary... 3 4. PasswordReset installer... 4 4.1. Installer... 4 4.2. Configurator... 7 4.2.1. Prerequisite... 8 4.2.2. Setting up tenants... 8 4.2.3. Configuring target system settings... 9 4.2.4. Configuring common settings:... 10 4.2.5. Configuring IIS... 12 4.2.6. Configuring Certificates... 13 4.2.7. Authentication settings... 14 4.2.8. Execution... 15 4.3. Logs... 17 5. Authentication... 19 5.1. Settings for Safewhere*Identify... 19 5.2. Setting for ADFS:... 19 6. Target systems... 26 7. Reset the password: Default Use Case... 27 8. Manual configuration... 31 8.1. Authentication:... 31 8.2. Target system:... 31 8.3. Common settings:... 32 9. Dummy Authentication and Dummy Target Systems... 34 Page 2

1. System Requirements The recommended hardware setup for running Safewhere*PasswordReset 4 GB Memory Dual Core CPU Minimum hardware setup is: 2 GB Memory Single Core CPU 2 GHz The required software for running Safewhere*Identify: Microsoft Server 2008 R2 /2012.Net Framework 4.5 MVC 4.0 Active Directory Safewhere*LDAP Web Service Safewhere*Identify 4.2 or ADFS2.0 2. Introduction The purpose of this product is to be able to offer a simple and convenient self service solution for resetting ones passwords across various platforms from just one place. In this first version, it will focus on just one platform, namely active directory. Authentication to the site will be controlled using WS Federation authentication, meaning that the solution needs to be set up as a relying party of an Identity Provider (IdP) solution. The Safewhere*PasswordReset web site will interact with Active Directory through the Safewhere*LDAP Web Service, which is another product of Safewhere. This product is explained in a different user guideline. 3. Glossary - Target System: A target system is an external system on through or on which a user will be offered to reset passwords. Safewhere*LDAP Web Service, which helps interact with Active Directory, is such a target system. A target system will be coded as a plug in. - UserId: A user id is a string used to identify users in various target system. By default CPR number is used (the Danish personal registration code). But dependent on the target system, the user id can be converted or set appropriately to map most easily to users of those systems. - Mapping: Mapping is the process of finding user accounts based on User Id in a target system. Usually this process will be invoked via direct communication with the target system, such as an Active Directory call. - Filtering: Filtering is the process of filtering the results from Mapping phase. It is usually done in memory using filter criteria defined in the configuration file. Page 3

4. PasswordReset installer To ease the installation process of Safewhere*PasswordReset, both a System Installer and a Configurator is offered. Basically they are both Installers, but the System Installer just sets up the basic files, whereas the Configurator sets up the actual tenant installations. In the following chapter, we will introduce the Installer and the Configurator and show how easy it can in fact be, given that the environment has no unique requirements. 4.1. Installer The Installer sets up the Safewhere*PasswordReset Configurator. When the installer is launched, it will perform a pre-installation check to see if a previous version of PasswordReset exists. If a previous version exists, a message saying that The prior version of PasswordReset will be uninstalled will be presented. Click Next to remove the previous version. Once the removal is complete, proceed to the next step. Page 4

Accept the End User License Agreement by ticking the checkmark at the bottom. Notice that the Next button will not be enabled before you have ticked the checkmark. Supply your name as well as the name of your company. Select the folder on your server where PasswordReset files will be located. Page 5

The default location should work perfectly for most companies, so keep this unless your company has some specific requirements in this regard. Installer asks to specify a name for the Start Menu group (the name of the system as presented in the Windows Start Menu) as well as decide which users should have access to the PasswordReset system. After specifying this, the system will be ready to install PasswordReset on your server. Page 6

You are now ready to set up PasswordReset tenants. The Configurator will be launched after clicking the Finish button. Otherwise you can launch the Configurator from Start > PasswordReset > PasswordReset. After installation, the PasswordReset Configurator will be available from the start menu. It will allow you to set up the PasswordReset tenants (aka web sites). 4.2. Configurator The PasswordReset Configurator will help you set up one or more PasswordReset tenants, aka web sites. Through the Configuration editor you will be able to set up new target systems such as the Safewhere*LDAP Web Service (LdapWS). Page 7

4.2.1. Prerequisite The configurator can be launched from Start > PasswordReset > PasswordReset. Initially the configurator will check that you have MVC 4.0 installed on your server. If missing, you must close down the configurator and install it before trying again. 4.2.2. Setting up tenants In the following step it will therefore offer a number of actions that can be taken on a PasswordReset tenant including creating, deleting and upgrading them. Page 8

Create new instance: When you wish to set up a new PasswordReset tenant. Delete an instance: When you wish to delete one of the PasswordReset tenants already installed. Currently, we manage it through PWRConfiguration.xml under Tools folder. Upgrade existing instance: If you have upgraded the PasswordReset installation (which is done by running the system Installer with a newer version of PasswordReset), then all PasswordReset tenants, which have not yet been upgraded to this newest version, will be listed in this dropdown. Simply choose a tenant to upgrade it to the newest installed version of PasswordReset. Please notice that tenants have no problem running on older versions of PasswordReset, even when other tenants on the same installation may have been upgraded. Upgrading tenants from a working version always bares some risks; so many companies choose not to upgrade tenants that are working well and do not require any new features. Delete all instances: When you wish to delete all of the PasswordReset tenants already installed. Let us assume that Create new instance was selected and the Next button clicked. 4.2.3. Configuring target system settings This following step will configure the default target system for PasswordReset. In the first version, PasswordReset only supports LDAP Web Service as a target system. Page 9

Select location where PasswordReset has been installed: By default the Configurator will use the folder where you initially installed PasswordReset. In the rare case that you have moved the codebase manually, you will have a chance to change location here and avoid tenant code being placed in a wrong folder. Target Id: The identifier of the target system. This value must be unique for this PasswordReset tenant instance. Target Name: The display name of the target system which will be displayed in PasswordReset site. Enter LdapWS URL: The service URL of LDAP Web Service. LdapWS service certificate raw: The service certificate of LDAP Web Service LdapWS endpoint identity: The service identity of LDAP Web Service. This value automatically filled in after LdapWS service certificate raw is inputted. Select client certificate from (Local Computer/Personal): The client certificate of the LDAP Web Service, which must already be stored in the server s certificate store. You can choose it using this dropdown. LdapWS connection timeout: The Timeout property sets or returns the timeout period for a connection to LDAP Web Service, in seconds. Default value is 60 seconds. 4.2.4. Configuring common settings: This step will configure the Map and Filter criteria, which are used to find and filter the users accounts based on User Id as specified in the target system. It also defines password validation policies and the error message that will be displayed when the new password does not meet these policies. Page 10

Search root: Defines the root level of search, in other words, the highest location scope of the search. Ex: OU = Safewhere, DC=Safewhere, DC = local: mean the system will find users under Organizational Unit Safewhere in Domain Safewhere.local. If empty, mean the root directory. Filter: Define how to search the user base for "user id". This is called the mapping phase. The example below will match users which have employeenumber equal to a specified input. Input will be case insensitive. <filter><![cdata[(&((&(objectcategory=person)(objectclass=user)))(employeenumber={0}))]]></filt er> Password policy: Define validation rules for new password using regex. Validate password against Active Directory complexity requirement property: If this checkbox is checked, then validation rules will include Active Directory complexity requirement property. (More detail about Active Directory complexity requirement: http://technet.microsoft.com/enus/library/cc786468%28v=ws.10%29.aspx) Password error message: The error message that will be displayed when system fails to validate the new password against the rules specified in the Password policy field. Filter combine operation: Configure how to filter the result returned from the "mapping phase using And or Or combinations. There are many filter properties. Each filter property is a rule to filter the result returned from the Mapping phase. This filter combine operation decides how to combine these filter properties. That means an account needs to match all of the filter properties (if the chosen operation is AND) or match any of the filter properties (if the chosen operation is OR). Filter configuration fields: Define filter expression by attribute -name from AD user properties. More information about Filter operator, please read in Manual configuration. Name: Attribute-name from AD user properties, e.g. displayname or postalcode. Page 11

Operator: operators (*) for string comparison (Equals, EqualsIgnoreCase...), for numeric (=, <, >=), and For Regular Expression (regex). Expression: define expression for the above operator. (*)Operators Description For numeric comparison: = value = expression > value > expression < value < expression >= value >= expression <= value <= expression between expression will be: {start} {end}. Ex: 3 5 translated to: >=3 and <=5 For Regular Expression: regex Means that the attribute's value will be validated against an expression in expression node For string comparison: Equals value of attribute equals to expression, case sensitive EqualsIgnoreCase value of attribute equals to expression, case insensitive StartsWith value of attribute start with expression, case sensitive StartsWithIgnoreCase value of attribute start with expression, case insensitive EndsWith value of attribute end with expression, case sensitive EndsWithIgnoreCase value of attribute end with expression, case insensitive Contains value of attribute contains expression, case sensitive ContainsIgnoreCase value of attribute contains expression, case insensitive Excepts value of attribute does NOT equal to expression, case sensitive ExceptsIgnoreCase value of attribute does NOT equal to expression, case insensitive 4.2.5. Configuring IIS You are now ready to specify settings for the IIS step of the Safewhere*PasswordReset tenant setup that controls how it is set up in IIS. Page 12

Enter Application id: The name you wish the PasswordReset tenant to be known by. Currenly, it is automatically filled by the Target Id from Target system settings step. This Identifier is used several places in the setup of the system, e.g. as proposed default values for domain name and application pool names. Since it will be used as proposed name for domain, you must not use spaces, symbols, or characters/numbers other than a to z and 0 to 9. For example, if you want to create a PasswordReset at https://pwrdemo.globeteam.com, the application id will by default be set to pwrdemo. Server IP: The IP address of the PasswordReset tenant s site. Port number: The port number of the PasswordReset tenant s site. Domain name: The DNS name, where the PasswordReset tenant resides (the Host Name that is specified in the IIS Site Bindings property sheet). Tenant site name: The name of the tenant site as it will be displayed in the IIS Manager MMC console. This is just for display and has no functional importance. Site application pool: This setting specifies the name of the application pool that will be set up and used by the PasswordReset tenant site. The options are: Apply Network Service as application pool identity: Generally used in case the current machine does not belong to the domain. Use specified domain account as application pool identity: Generally used in case the current machine belongs to the domain. This option is checked as default. 4.2.6. Configuring Certificates PasswordReset uses SSL certificate mutual authentication binding between Safewhere*PasswordReset and the client (currently, Safewhere*Identify supports Safewhere*PasswordReset). Page 13

Default certificate: Safewhere*PasswordReset comes with default certificates making it quick to set up for testing purposes. Since these certificates are obviously not identifying you uniquely, they should not be used for actual production installations. Auto-generated certificate: Auto-generate is used for testing when Safewhere*PasswordReset is not set up using the installer, but rather set up manually. Import from file: If you have a certificate file, you can immediately import it to your server s certificate store as well as relate the tenant to it. Password: When importing a new certificate to your server s certificate store, you will be required to specify its password in order to activate it. Select from server s certificate store: If the needed certificate is already stored in the server s certificate store, you can choose it using this dropdown. Import certificate to Trusted Root Certification Authorities: This field is just a supporting field for uploading a root certificate which identifies the other certificates as trustworthy (if this does not already exist on your server). The generated certificates will be input at: [installed_path]\certificates\ Licensing: After the 30-day trial period, the user will need to apply a license key. 4.2.7. Authentication settings The following step will configure the WS Federation authentication setting for PasswordReset. Currently only Safewhere*Identify support WS Federation authentication for PasswordReset. Page 14

Enter WS Federation issuer URL: The WS Federation issuer URL of IdP. Ex: with Safewhere*Identify, it should be https://[identifytenantid]/runtime/wsfederation/wsfederation.idp, with ADFS: https://[adfs domain]/adfs/ls/ Required https: This checkbox requires system to use HTTPS connections. If this checkbox is checked but WS Federation issuer URL is HTTP only, user will get the required HTTPS error message when click Next. Select WS Federation encrypt certificate: The encrypt certificate uses for WS Federation authentication connection, get from store LocalMachine/My. Select Signing certificate is used to sign requests to WS Federation: The Signing certificate uses for WS Federation authentication connection, get from store LocalMachine/My. 4.2.8. Execution On clicking the Next button you will reach the step where the tenant is actually created. Click Next again to start this process. Page 15

After execution you will have reached the last step. A link will here be available for you to immediately access the PasswordReset site for the new tenant. Page 16

4.3. Logs When you create/upgrade/delete a PasswordReset tenant using the PasswordReset configurator, it will be written into the log file located in the C:\IdentityPWRLogs folder. When the PasswordReset tenant is in use, it will log information to a file identified by the C:\Program Files\Safewhere\PasswordReset\Tenants\[Application id]\log4net.config file. As default, all error logs and info logs can be found in the folder tenant_folder\logs. Page 17

Page 18

5. Authentication Currently, PasswordReset works with any IdPs supporting WS Federation authentication method for resetting a password, such as Safewhere*Identify and, AFDS. 5.1. Settings for Safewhere*Identify At PasswordReset: User can setup the WS Federation authentication at step Authentication setting in PasswordReset Configurator or in web.config file. At Identify*Admin, we need create a WS Federation Protocol Connection, and set some below values: o Entity ID: https://[pwr applicationid]/wsfederationauthentication o Passive requestor endpoint: https://[pwr applicationid]/wsfederationauthentication. o Encrypt certificate: the certificate which was set in Authentication Settings step. 5.2. Setting for ADFS: You must select Add Relying Party Trust Wizard and choose Enter data about the relying party manually. Page 19

Input Display Name and click Next. Page 20

Choose the certificate chosen as WS Federation encrypt certificate in the authentication setting step of the Configurator. Page 21

At the Configure URL step, input the URL of the PasswordReset web site in the form https://[pwr applicationid]/wsfederationauthentication. Page 22

After clicking Finish, you must change the AD FS 2.0 Signature Algorithm to use the Secure Hash Algorithm 1 (SHA-1). To do this right-click on Properties, then on the Advanced tab, in the Secure hash algorithm list, select SHA-1 and click OK. Page 23

Claim settings: In AD FS 2.0 you will needs to set up a claim rule describing the user information that needs to be issued to PasswordReset. The following example maps the attribute Employee Number of Active Dicrectory to the claim type called Name, which will then be issued to PasswordReset as the UserId. PasswordReset will then use this value during the Mapping phase. To set this claim simply right click on PasswordReset Relying Party Trust, which you created above, and select Edit Claim Rules. Page 24

Page 25

6. Target systems PasswordReset supports Safewhere*LDAP Web Service as default target system in which passwords can be reset. To add or remove target systems, just include the config file to WindsorServices.config. Page 26

7. Reset the password: Default Use Case After opening the PasswordReset site, the user will typically be requested to choose an authentication method. After authenticating the user is directed to the PasswordReset site with a token containing the user s ID. PasswordReset looks up the user accounts in AD corresponding to this ID. Page 27

If more than 1 account is found, the user is asked to select whether the password should be reset for all accounts or just for specific accounts. If only 1 account is found, then itis automatically selected and this step is skipped. After selecting account(s), the user is asked to enter a new password. Page 28

If the chosen password passes all validation rules, then PasswordReset will reset the pasword on the target systems and send the user to Done page. User may the choose to Start Over to reset more passwords. If users fails to validate the new password against the password-policy rules, an error message (which could be defined in the Configurator) will be displayed. Page 29

In case new passwords meet all password-policy rules of PasswordReset, but do not meet Active Directory complexity requirement, PasswordReset will send the user to an error page as shown below. User may then click Retry to return to the Update password page, or Start Over to restart the whole progress. Page 30

8. Manual configuration This section explains how you can configure the authentication, target system, and common settings. 8.1. Authentication: Modify the Web.config file: a. In the identityconfiguration element, can set AUDIENCE_URI point to PasswordReset s WS Federation authentication, set TRUSTED_ISSUERS with Encrypt certificate and Signing Certificate. b. In federationconfiguration element, can set issuer value to WS Federation issuer URL, realm point to PasswordReset s WS Federation authentication, and servicecertificate is Encrypt certificate. 8.2. Target system: a. Modify the LdapTargetSystemPlugin.config file: Edit the Target info, such as Targetid, Target Name, and Location of Target config file. b. Modify Target config file which mentions above: In LdapService element, can set ServiceUrl which points to TargetSystem service s url, e.g LdapCredentialsService.svc, and set EndpointIdentity, as well as ServiceCertificate and ClientCertificate. Page 31

8.3. Common settings: Modify Target config file which mentions in TargetSystemPlugin. Element name Description map Setting map criteria Child element Element name Description Element name Description search-root Define the root level of search. filter Define how to search user base on "user id". Example <map> <search-root>ou=safewhere,dc=safewhere,dc=local</search-root> <filter><![cdata[(&((&(objectcategory=person)(objectclass=user)))(employeenumber={0}))]]> </filter> <scope>0</scope> </map> Element name Description filter Setting filter criteria which will filter the result returned from above "map" phase. Attributes operator Child element Element name Description Child element Element name Define Combination Operator. Available values are: And, Or property-filter Define the Property and Operator which use in the filter name Description Attribute-name from AD user properties (case sensitive) Element name operator Description Supported operators (*) Element name expression Description The expression uses in this operator Example <filter operator="or"> <property-filter> <name>postalcode</name> <operator><![cdata[between]]></operator> <expression><![cdata[700 800]]></expression> </property-filter> <property-filter> <name>displayname</name> <operator><![cdata[regex]]></operator> <expression><![cdata[(?=.*[a-z])]]></expression> </property-filter> </filter> Page 32

Element name Description Attributes operator Child element Element name Description Element name Description Element name Description password-policy Define validation rules for new password Define Combination Operator. Available values are: And, Or expression The expression which define the validation rules complexity-requirements Validation rules will include Active Directory complexity requirement property or Not. Available values are: True, False. message Error message which will display when fail to validate the new password against above rules. Example <password-policy> <expression><![cdata[^(?=[^\d_].*?\d)(?=.*[a-z])(?=.*[a- Z])(\w [!@#$%<>/]){6,20}$]]></expression> <complexity-requirements>false</complexity-requirements> <message><![cdata[the format of the password is incorrect. It should has 6 to 20 characters; at least 1 upper and 1 lower alphanumeric character; at least 1 digit; selected symbols!@#$%<>/ are optional. The password also cannot start with a digit or underscore. The password must meet AD complexity.]]></message> <resource-key></resource-key> </password-policy> Page 33

9. Dummy Authentication and Dummy Target Systems For testing purposes, PasswordReset supports Dummy authentication and Dummy target systems, which can be resolved by editing DummyPlugIn.config file. 1. Dummy authentication: user will be authenticated as admin. 2. Dummy target systems: o Dummy1: where Password validation always fail. o Dummy2: where Set password always fail. Page 34