Safewhere*PasswordReset

(1)

Page 1

Safewhere*PasswordReset

(2)

Page 2

Safewhere*PasswordReset

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.

(4)

Page 4

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.

(5)

Page 5 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.

(6)

Page 6 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.

(7)

Page 7 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 willallow 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).

(8)

Page 8

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.

(9)

Page 9

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.

(10)

Page 10

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: Theidentifier of the target system. This value must be unique for this PasswordReset tenant instance.

Target Name: Thedisplay name of the target system which will be displayed in PasswordReset site.

Enter LdapWS URL: The serviceURL of LDAP Web Service.

LdapWS service certificate raw: Theservice certificate of LDAP Web Service

LdapWS endpoint identity: Theservice identity of LDAP Web Service. This value automatically filled in after LdapWS service certificate raw is inputted.

Select client certificate from (Local Computer/Personal): Theclientcertificate 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.

(11)

Page 11

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.

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/en-us/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.

(12)

Page 12

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.

(13)

Page 13

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).

(14)

Page 14

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.

(15)

Page 15

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 Signingcertificate 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.

(16)

Page 16 After execution you will have reached the last step. A link will here be available for you to

(17)

Page 17

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.

(18)

(19)

Page 19

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 setupthe 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”.

(20)

Page 20

(21)

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

(22)

Page 22

At the “Configure URL” step, input the URL of the PasswordReset web site in the form https://[PWR applicationid]/WSFederationAuthentication.

(23)

Page 23

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.

(24)

Page 24



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 onPasswordReset Relying Party Trust, which you created above, and select Edit Claim Rules.

(25)

Page 25

(26)

Page 26

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

(27)

Page 27

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.

(28)

Page 28 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.

(29)

Page 29 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.

(30)

Page 30 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.

(31)

Page 31

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 setissuervalue to WS Federation issuer URL, realmpoint 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

(32)

Page 32

8.3. Common settings:

Modify Target config file which mentions in TargetSystemPlugin.

Element name map

Description Setting map criteria Child element

Element name search-root

Description Define the root level of search.

Element name filter

Description Define how to search user base on "user id". Example

<map>

<search-root>OU=Safewhere,DC=safewhere,DC=local</search-root>

</filter> <scope>0</scope> </map>

Element name filter

Description Setting filter criteria which will filter the result returned from above "map" phase. Attributes

operator _{Define Combination Operator. Available values are: And, Or} Child element

Element name property-filter

Description Define the Property and Operator which use in the filter Child element

Element name 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

<name>postalCode</name>

<property-filter>

<name>displayName</name>

(33)

Page 33 Element name password-policy

Description Define validation rules for new password Attributes

operator _{Define Combination Operator. Available values are: And, Or} Child element

Element name expression

Description The expression which define the validation rules

Element name complexity-requirements

Description Validation rules will include Active Directory complexity requirement property or Not. Available values are: True, False.

Element name message

Description Error message which will display when fail to validate the new password against above rules.

Example

<password-policy>

<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>

(34)

Page 34

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.

Safewhere*PasswordReset

Safewhere*PasswordReset

Safewhere*PasswordReset

Contents

1.

System Requirements

2.

Introduction

3.

Glossary

-

4.

PasswordReset installer

4.1.

Installer

4.2.

Configurator

4.2.1.

Prerequisite

4.2.2.

Setting up tenants

4.2.3.

Configuring target system settings

4.2.4.

Configuring common settings:

4.2.5.

Configuring IIS

4.2.6.

Configuring Certificates

4.2.7.

Authentication settings

4.2.8.

Execution

4.3.

Logs

5.

Authentication

5.1.

Settings for Safewhere*Identify

5.2.

Setting for ADFS:



6.

Target systems

7.

Reset the password: Default Use Case

8.

Manual configuration

8.1.

Authentication:

8.2.

Target system:

8.3.

Common settings:

9.

Dummy Authentication and Dummy Target Systems

**Settings for Safewhere*Identify**