-
Notifications
You must be signed in to change notification settings - Fork 250
General Directory Setup
PWM generally requires some changes to your directory server in order to function correctly. First of all, a number of attributes are used for storing PWM’s information like password history, questions and answers needed for password reset, last password change date and optionally some information like (external) email addresses or mobile phone numbers for SMS notifications. This requires changes to the schema.
Furthermore, a number of users and groups must be selected or setup to perform specific operations. Last but not least, the users need to get credentials and permissions in order to perform their tasks.
Some directories only allow encrypted operations or require encryption for certain operations, like changing passwords. In these cases you need to connect PWM to the SSL port. This usually is 636 or alternatively 1636. PWM allows you to use a promiscuous connection, which means it will accept any server certificate, whether it is valid or not. That is useful in development and testing environments, but often unwanted in production environments. In a production environment, you would want PWM, or in fact java, to trust the LDAP server’s certificate. There are three scenario’s:
-
You use a certificate issued by a generally recognized commercial certificate authority. The certificate of this authority should already be in the certificate database. If the server name in the LDAP URL is identical to the common name of the certificate, you’re done.
-
You use a certificate issued by a private certificate authority, like from NetIQ iManager, Microsoft Active Directory or created using a tool like TinyCA. In this case the certificate(s) of that certificate authority need(s) to be imported into the java certificate database. See instructions below.
-
You use a self signed certificate. In this case, the self signed certificate needs to be imported into the java certificate database. See instructions below.
In all cases you need to make sure that:
-
The certificate and the issuer certificates are still valid and have not expired.
-
The name in the LDAP URL is identical to the name or any of the alternate names of the certificate. For example connecting to ldaps://127.0.0.1:636 will probably fail, while connecting to ldaps://ldap.example.com:636 will succeed if the certificate name is ldap.example.com.
To import the CA certificate or self signed certificate into the certificate database, make sure you have it available in PEM format, also known as base64. Such a file looks like:
-----BEGIN CERTIFICATE-----
MIICATCCAWoCCQDZ4jvO0d1ljzANBgkqhkiG9w0BAQUFADBFMQswCQYDVQQGEwJB
VTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50ZXJuZXQgV2lkZ2l0
cyBQdHkgTHRkMB4XDTExMTIxMzIwMjE1N1oXDTExMTIyMzIwMjE1N1owRTELMAkG
A1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoMGEludGVybmV0
IFdpZGdpdHMgUHR5IEx0ZDCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA0OfL
xaoClmMttdEaa2Ig4htWL1AdCgOy8unDDc0qZvwlK3izXefc63jkbuJCyTU+CDHV
H9he2x2UV1NXUArlfWBDvUanGMu12LH05S+HsFerKwpvqnVfKfGdzrfxUpd1lhTU
cARtzJk5D3USXgqXZ7kwxyx6rr1KLmTG+96V9UECAwEAATANBgkqhkiG9w0BAQUF
AAOBgQBQGUzS1knVn/snjq75enUo95e47UJVQkJjQbSrAz7ZqUA5uvooLkAYh7gG
mqY9ECpXr8WM065+wFpyo97TEGr3W0uMCAaUQ9CloyKlOzrpBbdhqeuoh/Idq9EH
Ut7YDo9Oo+tLkebq9XuIsYJWiCSbHkPYpN5vBvVsLUUa50YsLA==
-----END CERTIFICATE-----
Now locate the certificate database. It is located in $JAVA_HOME/lib/security/cacerts, where $JAVA_HOME is the directory where java is installed. Now use keytool to import the file:
keytool -import -keystore $JAVA_HOME/lib/security/cacerts -file example.pem -alias ldap.example.com
The keytool will ask for a password, which is changeit by default.
After importing the certificate, restart you application server.
In order to function correctly, PWM needs a number of attributes for application specific data storage. In theory, one could use existing, unused attributes of the right type, but to keep the directory clean and well organized, it is recommended to add new attributes to the directory schema.
See Attribute Schema for Active Directory and others
The table below shows the required attributes with the suggested (default) names and object identifiers.
| Name | OID | Type | Single |
|---|---|---|---|
| pwmEventLog | 1.3.6.1.4.1.35015.1.2.1 | OctetString | N |
| pwmResponseSet | 1.3.6.1.4.1.35015.1.2.2 | OctetString | N |
| pwmLastPwdUpdate | 1.3.6.1.4.1.35015.1.2.3 | Time | Y |
| pwmGUID | 1.3.6.1.4.1.35015.1.2.4 | DirectoryString | Y |
Next, an auxiliary object class needs to be defined that allows the attributes.
| Name | OID | Type |
|---|---|---|
| pwmUser | 1.3.6.1.4.1.35015.1.1.1 | Auxiliary |
Of course, you are free to select different or existing attributes and object classes, but you need to update the PWM configuration.
PWM needs, apart from the “normal” users, a set of “special” users and groups to perform certain actions. The sections below give an overview of the types of users and/or groups that must an may be set up. Some user/group types are optional and only necessary if a certain module is enabled.
Depending on you organization and separation of duties, it is possible to create new users or groups for the guest administrator or helpdesk functions or share the permissions with the PWM administrators.
Normal users must be allowed to self-modify their own password, pwmResponseSet and other attributes that are configured for the module Update Profile, if enabled.
The proxy user performs most actions, especially when no user is authenticated within the session. Actions that the proxy user performs are:
- Looking up users
- Testing LDAP connections
- Validation of attributes and security questions during Password reset
- Reading user data
- (Re)setting passwords
- Creating new accounts (if New User module is enabled)
The proxy user therefor needs access to the users in the user subtree and be able to read and write:
- objectClass
- userPassword or equivalent password attributes
- pwmEventLog, pwmLastPwdUpdate, pwmGUID (or other configured attributes)
Additionally, the proxy user needs to have read access to most other attributes of normal users.
U
ALL
PWM administrators can be a single user or a group of users. An administrator needs read access to the user tree of the directory, but actually does nothing to modify them. A PWM administrator can access administrative functions withing PWM, but is not a directory administrator.
U/G
ALL
Periodically, PWM tries to connect to the directory server en perform standard actions. In order to do this, PWM uses a test user account. PWM tries to set the password, perform login, etc.
The test user is a normal user account, that must be allowed to modify it’s own password and some attributes.
U
ALL
If the Guest Registration module is selected, a user or group must be allowed to perform these action. The user(s) must be granted directory permissions to:
- create users in a selected guest subtree
- read/set attributes and passwords for the guest accounts
U/G
Guest Registration
If the Helpdesk module is enabled, a special user or group is allowed to access this module. Helpdesk employees are allowed and should be given directory permissions to view user account data, password modification and login data (not the password itself!), like last login, last password change, account status, etc., and to set a new password if necessary.
U/G
Helpdesk