The LDAP Web Service Configurator will help you set up one or more LDAP Web Services that can be used by Safewhere*Identify’s LDAP.
The Configurator can be launched from Start > Safewhere LdapWS > Safewhere LdapWS Configurator.
Initially, the Configurator checks that you have MVC 4.0 installed on your server. If it is missing, you must close down the Configurator and install it before trying again.
Setting up tenants
The following step offers a number of options for an LDAP Web Service tenant, including creating, deleting, and upgrading them:
Create new instance: When you want to set up a new LDAP Web Service tenant.
Delete an instance: When you want to delete one of the LDAP Web Service tenants already installed. Currently, you can manage it through “LdapConfiguration.xml” in the Tools folder.
Upgrade existing instance: If you have upgraded the LDAP Web Service installation (which is done by running the system installer with a newer version of Safewhere*LDAP Web Service), then all LDAP Web Service tenants that have not yet been upgraded to this newest version will be listed in this drop-down list. Simply choose a tenant to upgrade it to the newest installed version of Safewhere*LDAP Web Service. Notice that tenants have no problem running on older versions of Safewhere*LDAP Web Service, 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 want to delete all of the Safewhere*LDAP Web Service tenants already installed.
Let’s assume that the Create new instance option was selected and the Next button was clicked.
Configuring the LDAP Web Service Settings and the Directory Connection
- Select location where LdapWS has been installed: By default, the Configurator uses the folder where you initially installed Safewhere*LDAP Web Service. In the rare case that you have moved the codebase manually, you have a chance to change the location here and avoid tenant code being placed in a wrong folder.
- Enter service id: The name you want the Safewhere*LDAP Web Service tenant to be known by. This identifier is used in several places in the setup of the system, for example, as proposed default values for domain names and application pool names. Because it will be used as a proposed name for the 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 an LdapWS at https://ldapwebservice.safewhere.com, the service ID will, by default, be set to ldapwebservice. You should only need to edit the service identifier if you’re using the same host names inside different domains.
- LDAP path: The LDAP path you want to input for Safewhere*LDAP Web Service. You can input the value manually or use the Browse button to search the entire computer (only applies to Microsoft Active Directory).
You can then select your desired computer through a pop-up dialog box, as shown below:
Click OK to update the LDAP path.
- Domain root: The domain root you want to use for Safewhere*LDAP Web Service. You can input the value manually or use the automatic value when you select the Browse button on the LDAP path (only applies to Microsoft Active Directory).
- Dispose search result collection: The setting for preventing memory leaks in long-running processes. By default, this setting is set to True.
- Authentication type: The type of authentication that will be used. This is set to ServerBind by default. MSDN has explained in depth all these options in the article found at http://msdn.microsoft.com/en-us/library/system.directoryservices.authenticationtypes.aspx
- Impersonate: The XXX. This is set to True by default, which indicates that the application pool identity is used, else the account specified below will be used.
- Authentication username: The user account that will be used by Safewhere*LDAP Web Service. You can input it manually (remember to include the domain name) or use the Search button to select the account.
- Authentication password: The password for the user account.
- Encrypt password: The setting that determines if the authentication password is encrypted or not. This setting is set to True by default. The above password is encrypted in web.config when this setting is True. An encryption tool has also been installed with Safewhere*LDAP Web Service and can be found in the Windows Start menu.
- Server IP: The IP address of the Safewhere*LDAP Web Service tenant’s site.
- Port number: The port number of the Safewhere*LDAP Web Service tenant’s site.
- Domain name: The DNS name, where the Safewhere*LDAP Web Service 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 Safewhere*LDAP Web Service 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. The authentication name and password will be autofilled with the information from the previous step.
Safewhere*LDAP Web Service uses SSL certificate mutual authentication binding between LDAP Web Service and the client (currently, Safewhere Identify and Safewhere ADFSX Login both include support for the LDAP Web Service). This type of binding requires that:
- A Safewhere*LDAP Web Service tenant must have its own certificate (referred to as the server certificate in the remainder of the section).
- A client that needs to communicate with a Safewhere*LDAP Web Service tenant must also have its own certificate (referred to as the client certificate in the remainder of the section).
- The machine that the Safewhere*LDAP Web Service is running on must trust the client certificate. This means that the public key of the client certificate must be imported to the LocalMachine/TrustedPeople store on the server machine.
- The machine that the client is running on must trust the server certificate. This means that the public key of the server certificate must be imported to the LocalMachine/TrustedPeople store on the server machine.
In the next step of the wizard, you need to specify the server certificate and the client described above:
- Default certificate: Safewhere*LDAP Web Service comes with a default server certificate, making it quick to set up for testing purposes.
- Autogenerated certificate: A new server certificate is generated for the Safewhere*LDAP Web Service tenant.
- Import from file: Use an existing certificate as the server certificate.
- Password: When importing a new server certificate to the computer’s certificate store, you are required to specify its password to activate it. The password of the default certificate is Test!234
- Select from server’s certificate store: Select this option if the needed certificate is already stored in the server’s certificate store (it should be stored in the CertStore that applies to the Local Computer to be visible for the installer). You can choose it using this drop-down.
- Export public key to file: The public key of the server certificate will be exported to the default location: [installed_path]\Certificates\[ldapws_service_id].
- Import certificate to Trusted Root Certification Authorities: This field is just a supporting field for uploading a root certificate, which identifies the server certificate as trustworthy (if this does not already exist on your server).
The Create Client Cert. & import to LocalMachine/TrustedPeople option allows you to easily set up a certificate that can be used for the test tool as well as for other clients. This step is optional. Note that the public key will automatically be imported to the Trusted People store.
The generated certificates will be input at: [installed_path]\Certificates\[ldapws_service_id]
Licensing: After the 30-day trial period, the user will need to apply a license key.
After clicking the Next button, you will reach the step where the tenant is actually created. Click the Next button again to start this process.
After execution, you will reach the last step. A link will be available for you to immediately access the test tool with the information of the new Safewhere*LDAP Web Service tenant.
When you click the Click here link, a Test Tool dialog box opens with the information from the newly created LDAP Web Service tenant automatically filled in.
LDAP Web Service Test Tool
The test tool, described in the prior chapter, is a dialog box that will have information from the created Safewhere*LDAP Web Service automatically filled into the offered fields.
When accessing the tool this way, you only need to input the valid LDAP user account to see if your configuration for Safewhere*LDAP Web Service is correct. There are two buttons that help do the verification:
Request service: Calls the VerifyUser Operation. When successful, it returns a user object.
Query service: Calls the QueryUser Operation. When successful, it returns the user object’s LDAP attributes.
To verify that the service works with Safewhere*Identify, we recommend that you test the Query service.
When the Safewhere*LDAP Web Service tenant is in use, it logs information to a file identified by the key LogConfigurationFileName in the web.config file.
By default, all error logs and information logs can be found in the folder tenant_folder\LogFiles.
In case you need more detailed information from the Safewhere*LDAP Web Service tenant, you can enable the below shown section in the tenant’s web.config file (by simply removing comments from the <system.diagnostics> node).