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 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.
Setting up tenants
In the following step it will therefore offer a number of options for a LDAP Web Service tenant including creating, deleting and upgrading them.
Create new instance: When you wish to set up a new LDAP Web Service tenant.
Delete an instance: When you wish to delete one of the LDAP Web Service Web Service tenants already installed. Currently, we manage it through “LdapConfiguration.xml” under Tools folder.
Upgrade existing instance: If you have upgraded the LDAP Web Service 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, 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 Safewhere*LDAP Web Service. Please 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 wish to delete all of the Safewhere*LDAP Web Service tenants already installed.
Let us assume that “Create new instance” was selected and the ‘Next’ button clicked.
Configuring the LDAP Web Service Settings and the Directory Connection
- Select location where LdapWS has been installed: By default the Configurator will use the folder where you initially installed Safewhere*LDAP Web Service. In the rare case that you have moved the code base manually, you will have a chance to change location here and avoid tenant code being placed in a wrong folder.
- Enter Service ID: The name you wish the Safewhere*LDAP Web Service tenant to be known by. 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 LdapWS at https://ldapwebservice.globeteam.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 as 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 select the “Browse” button on LDAP path (only applies to Microsoft Active Directory).
- Dispose search result collection: is set to ‘True’ by default. This setting is for preventing memory leaks in long running process.
- Authentication type: is set to ‘ServerBind’ by default. MSDN has explained in depth all these options at following article: http://msdn.microsoft.com/en-us/library/system.directoryservices.authenticationtypes.aspx
- Impersonate: is set to ‘True’ by default, indicates that the application pool identity is used, else the account specified below will be used.
- Authentication username: Specifies 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.
- Password: Specifies the password of the user account.
- Encrypt password: Is by default set to ‘True’. The above password will be encrypted in the 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 auto-filled 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, which 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, which 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, which the client is running on, must trust the server certificate. This means that the public key of the server certificate must be imported to 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.
- Auto-generated certificate: A new server certificate is generated for the Safewhere*LDAP Web Service tenant.
- Import from file: Use an existing certificate as server certificate.
- Password: When importing a new server certificate to the computer’s certificate store, you will be required to specify its password in order to activate it. The password of the default certificate is “Test!234”.
- Select from server’s certificate store: 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 dropdown.
- 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 which can be used for the test tool as well as other clients. This step is optional. Please note that the public key will automatically be imported to 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.
On clicking the ‘Next’ button you will reach the step where the tenant is actually created. Click ’Next‘ again to start this process.
After execution you will have reached the last step. A link will be available for you to immediately access the test tool with the info of the new Safewhere*LDAP Web Service tenant.
When you click ’Click here‘, a Test Tool dialog will be opened with the info 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 that will have info from the created Safewhere*LDAP Web Service automatically refilled into the offered fields.
When having accessed the tool this way you will thus 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 will return a user object.
Query service: Calls the “QueryUser Operation”. When successful it will return 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 will log information to a file identified by the key “LogConfigurationFileName”in the web.config file.
As default, all error logs and info 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 (by simply remove comments from the <system.diagnostics> node).