AD data source configuration
From Swivel Knowledgebase Wiki
Contents |
Overview
PINsafe carries out a Read Only lookup of the AD server using LDAP so no information is written to the AD server and there is no software to install on the AD server.
Also see the Active Directory FAQ
The following steps are required for AD Configuration:
- On the AD server create distribution or security groups and populate with users
- On the AD server create a service account for PINsafe to use
- On the PINsafe server create an AD Repository
- On the PINsafe server configure the Repository Groups
- On the PINsafe server configure Transport Attributes
- On the PINsafe server configure Transport Groups
- On the PINsafe server Synchronise the AD Users
PINsafe reads users from Containers (CN), groups in AD, and nested groups, but not directly from containers (OU). It is not possible to traverse domains unless Global Catalog is used, or PINsafe reads that domain.
For further information on LDAP data sources see the LDAP How to Guide
Prerequisites
PINsafe 3.x system
Repository Configuration Importing users from External Sources
AD configuration checks
Ensure network connectivity from the PINsafe server to the AD server for LDAP
Check AD Groups exist
Check PINsafe error logs for messages
Check Service account username and password
Use and LDAP browser to confirm the LDAP path (PINsafe 3.6 has a built in LDAP browser)
Ensure Transport Attribute is correct in Transport\Attributes, this is usually mail for SMTP and mobile for SMS by Cell Phone.
If SMTP is to be used, ensure SMTP gateway has been configured under Servers/SMTP
PINsafe can read the Global Catalog if this is configured on the AD server, this saves each appliance having to be connected to individually. The Global Catalog port must be configured and the PINsafe server must connect to the Global Catalog server.
Active Directory Server Configuration Steps
There is no software to install on the AD server, and PINsafe reads AD groups. For multiple AD Domains create the required groups on each domain, or use a global catalog server.
Create the Active Directory Groups
Users are added to Active Directory (AD) groups to allow them access to differing authentication resources. By creating additional AD groups different configurations can be made to suit the required environment. Existing groups can be used. The following documentation assumes the following configuration:
PINsafe Users - who have access to all authentication methods
PINsafe Administrators – who have access to all authentication methods and admin rights
On the AD server:
Create a Swivel Organizational Unit (OU) Right Click on the domain then select New and then OU, enter the name Swivel
Within the Swivel OU create a PINsafeAdmin Group (CN) Right click on the Swivel OU then select New Group, enter the name PINsafeAdmin
Within the Swivel OU create a PINsafeUsers Group (CN) Right click on the Swivel OU then select New Group, enter the name PINsafeUsers
Note: Ensure that Distribution or Security Groups are used and not an OU, as PINsafe cannot directly read an OU. PINsafe will not read users in CN=Users,DC=domain,DC=com
Add users to the Active Directory Groups
On the AD server:
Add users to the PINsafeUsers and PINsafeAdmin group as appropriate. Ensure users have the correct information for transport, i.e. an email address and mobile phone number. It is recommended to test with a small number of users first to ensure all settings such as transports etc are correct.
NOTE: PINsafe cannot handle primary groups or group membership that refers to trusted domains. These relationships are handled by Active Directory in a non-standard way that standard LDAP queries cannot discover. Do not use groups that are configured as primary groups for any user within PINsafe, and do not use groups that contain users from trusted domains. If you need to include user from other domains, use Global Catalog as described above.
PINsafe Server Configuration Steps
Configure SMTP Server Settings
On the PINsafe server:
Select Server then SMTP, enter the IP address/Hostname of the SMTP gateway
click Apply to save the settings
Add the AD Repository Servers
On the PINsafe Server:
Select Repository/General and create an Active Directory Repository, the name is descriptive and must be unique and up to 32 characters in length, and when created it should appear on the left hand side below Repository. Create additional PINsafe servers for each AD Domain, or use a global catalog server.
Click Apply to save settings
Configure the AD Repository Server Settings
On the PINsafe Server:
Select Repository then the required AD server.
The following information needs to be entered on each AD Repository Configuration
- Hostname/IP address of AD Server
- Service Account User Name
- Service Account Password
Do not configure Synchronization schedule at this stage
For further details see AD Repository Configuration Settings below
Click Apply to save settings.
For information on changing AD Credentials see AD Credential Change How to Guide
Create PINsafe Groups
On the PINsafe Server:
Select Repository/Groups and enter the Repository Group names corresponding to those created in Active Directory. Leave the fields blank that are not required. The input fields are case sensitive. Use an LDAP browser if unsure of the path, or if using PINsafe 3.6 or higher use the inbuilt LDAP browser.
The format must be:
CN=<AD Container>,OU=<Organizational Unit>,DC=<mydomain>,DC=<com>
Example: CN=PINsafeAdmin,OU=Swivel,DC=swivelsecure,DC=com
Configure Transport Attributes
On the PINsafe Server:
Select Transport then Attributes. Ensure the settings are correct for each AD repository, usually:
- mobile for mobile phone
- mail for email
Other fields that are used may be telephoneNumber
For further information see Transport_Attribute
Configuring Transport Groups
Assign the AD groups to the required Transport class, the following Transport attributes are used for assigning groups:
- Group: Where security strings are sent to
- Alert Repository Group: Where information is sent regarding the user such as PIN numbers
For further information see Transport_Configuration
Sync the AD Database
On the PINsafe Administration console, select User Admin and from the Repository drop down menu select the required AD server name then click on sync now. Users from the AD repository should appear.
Enable Automatic AD Synchronisation
If all the synchronisation is working as fully expected, the PINsafe server can now be configured to automatically read the AD server at regular intervals.
On the PINsafe Server:
Select Repository then the required AD server. Set the required Synchronisation Schedule.
Click Apply to save the settings
Appendix:
AD Repository Configuration Settings
AD Import Information on the PINsafe server is required as follows:
Repository Domain Qualifier: AD Domain name, this is used with the Add domain qualifier:
Reformat Phone Number: Yes No When the phone number is imported then PINsafe will carry out some basic formatting as determined by the prefix to remove and add. PINsafe will also remove extraneous characters and white spaces.
Prefix to remove: PINsafe will remove a prefix from the phone number
Prefix to add: PINsafe will add a prefix to the phone number, this could be for instance a country code.
Hostname/IP: AD server name, or entering an AD domain will pick up available AD server. If an AD replica is used, be aware that it may take some time for user information to be pushed out to replica AD servers. For redundancy an active directory with a Virtual IP or DNS can be used. Additionally two PINsafe servers could be used, but ensure that they synchronise at differing times.
Username: AD service account, usually it is best to use a fully qualified domain name e.g. swivel@swivelsecure.com. The user needs to have permission to connect and bind using LDAP to the AD server.
Password: AD service account password, ensure that password ageing is not set or it is changed regularly
Allow self-signed certificates: Yes No Are certificates used on the AD server?
Username attribute: The username that the AD account reads. By default this is the SAM Account name, sAMAccountName for example; bob. It is possible to use the User Principle Name userPrincipalName so that the user has to enter their full username, for example bob@swivelsecure.com, users would need to enter this full address to authenticate. It is also possible to use the email address of a user by setting the Username attribute to mail. Note that this should be set during initial configuration, if the attribute is changed, then new users will be created with this different username and the old users deleted.
PIN attribute: PINsafe can read an AD LDAP attribute that contains the users first PIN number, this AD LDAP attribute can be added here. It is not recommended to have a default PIN, but instead to use a randomly generated PIN that is sent to the user.
Password attribute: PINsafe can read an AD LDAP attribute that contains the users first password, this AD LDAP attribute can be added here. It is not recommended to have a default password, but instead to use a randomly generated Password that is sent to the user. Note this is not the AD password but a PINsafe password.
Import disabled state: Yes No If the account is disabled in AD, should it be disabled or enabled when imported into PINsafe. Contractors and 3rd parties can be configured as disabled so they cannot login to AD, but may still authenticate using PINsafe.
Ignore FQ name changes: Yes No Changes to the AD infrastructure can lead to users account being deleted and re-created, users see this as new PIN numbers being generated. To stop this occurring PINsafe can be set to ignore these changes.
Mark missing users as deleted: Yes No If a user is deleted from the AD group that PINsafe references, PINsafe can mark it as deleted without actually deleting the account. If it is reinstated, then the user can be undeleted/restored in PINsafe, and the user will retain their current PIN and security strings.
Port: 389 (Domain LDAP) 636 (Domain LDAP SSL) 3268 (Global Catalog LDAP) 3269 (Global Catalog LDAP SSL) Select the required port for communication.
Add domain qualifier: None Prefix Suffix When the user is imported from Active Directory into PINsafe, the AD domain qualifier can be added either as a prefix or suffix to the username, or not used. For example a user imported from ad as bob may have the suffix @swivelsecure.com added and stored in pinsafe as bob@swivelsecure.com.
Synchronization schedule: Choose how often PINsafe will synchronise with the AD server. Note: an immediate synchronisation can be performed from the User Admin Screen
Check Password With Repository
It is possible for PINsafe to check the AD password with some access devices. For Active Directory The username must be passed to AD as username@domain in order to authenticate via LDAP. This can be specified by using the the administrator or service account username for the repository configuration as administrator@domain.name, rather than just administrator or service account username, PINsafe will automatically append the domain to the username when authenticating to AD, if one is not specified.
Upgrading from Active Directory on a 2003 server to a 2008 server
PINsafe support Active Directory on 2008 Server
When upgrading from a 2003 to a 2008 server, ensure that the BaseDN remains the same. or you will encounter issues when attempting to sync. Specifically, it would be trying to look for the old FQDN and then abort. If you intend to change the BaseDN then you can avoid this issue by upgrading to the latest version of PINsafe before migrating to AD 2008. The latest version would attempt to find the user elsewhere in the directory when performing a user sync if the BaseDN had changed, thus avoiding the abort issue.
PINsafe log AD Error Messages
Repository "Active Directory", cannot be added to the database: possibly already exists.
This error can occur if the repository name already exists or the Database is still set to shipping mode. The repository "local" can be used but will also generate this error but can be ignored.
ERROR - Exception occurred during repository group member query, group: CN=PinSafeUsers,CN=Users,DC=swivelsecure,DC=com, exception 192.168.0.100:389; socket closed
Synchronisation with the data source has been stopped after the port was closed, this could be caused if the system is shutdown or rebooted. Check to see if this is a one off instance or occurs multiple times
AcceptSecurityContext error, data 525, vece ]
This is usually caused by when incorrect authentication is made against an AD domain. Check the username and password being used for the LDAP synchronisation, check the password has not been changed and the account is still active.
Test the user account with an LDAP browser.
Other possible errors for AcceptSecurityContext: AcceptSecurityContect error, data xxx, vece are as follows:
- 525 user not found
- 52e invalid credentials
- 530 not permitted to logon at this time
- 531 not permitted to logon at this workstation
- 532 password expired
- 533 account disabled
- 701 account expired
- 773 user must reset password
- 775 user account locked
Exception occurred: during repository attribute query, object: ERROR Exception occurred: during repository attribute query, object:<name>, attribute: sAMAccountName, exception:java.naming.InvalidNameException:<name>: [LDAP: error code 34 – 000208F: NameErr: DSID-031001B3, problem 2006 (BAD_NAME), data 8350, best match of:’<name>’]; remaining name <name>
Names have failed to be found and existing names are not found. Check the AD paths and names.
No value for username attribute “sAMAccountName”. The user "CN=x-x-x-x,CN=y,DC=z,DC=company,DC=com" has no value for username attribute "sAMAccountName". User not added.
A user has been added to a trusted domain where PINsafe is looking for users within that group.
Java.net.NoRouteToHostException: No route to host?
Exception occurred: during repository group member query, group: javax.naming.CommunicationException: xxx.xxx.xxx.xxx:389 [Root exception is java.net.NoRouteToHostException: No route to host],exception %2
or
Exception occured during repository group member query, group: CN=PINsafeUsers,OU=Groups,DC=swivelsecure,DC=com, exception javax.naming.CommunicationException: ad.swivelsecure.com:389 [Root exception is java.net.UnknownHostException: ad.swivelsecure.com]
Check the network connectivity to the AD server, ports, firewalls, routing, DNS, IP, etc.
ERROR 192.168.1.1 admin:Exception occurred during repository group member query, group:
CN=PINsafeusers,OU=PINsafe,DC=xxx,DC=swivelsecure,DC=com, exception ADserver1.xxx.swivelsecure.com:389
This can be caused by a user who is a member of the group PINsafeusers but is part of another domian. PINsafe will not be able to read the attributes for that user. PINsafe would need to connect to that AD domain or read a Global Catalogue Server.
No value for username attribute <attributeName> The user CN=x-x-x-x,CN=y,DC=z,DC=company,DC=com has no value for username attribute <AttributeName>. User not added
ERROR - Exception occured during repository attribute query, object: CN=something,OU=oux,offices,OU=Com,DC=bob,DC=corp, attribute: sAMAccountName, exception:javax.naming.NameNotFoundException: [LDAP: error code 32 -0000208D: NameErr: DSID-031001CD, problem 2001 (NO_OBJECT)
The user within the repository has no value set for the attribute that is configured to be used as the PINsafe username; therefore an account cannot be created for that user. For example if PINsafe was configured to use the Active Directory attribute for email address for the PINsafe account name and this value was not set in AD for a given user.
This may happen when a user has been added to a trusted domain where PINsafe is looking for users within that group, only the fact that the user is a member of the group is available, and not the attributes of that user.
admin:Sending alert to user "username" failed, error: The user does not have an associated alert transport.
A transport has not been defined for the user
Exception occured during repository group member query, group: CN=PINsafe2factor,CN=Users,DC=PINsafe,DC=swivel,DC=secure,
exception javax.naming.CommunicationException: 192.168.0.1:389 [Root exception is java.net.NoRouteToHostException: No route to host]
The error No Route to Host indicates a networking issue. Check to see if the PINsafe server can Ping or Telnet on port 389 (or required port) to the AD or LDAP server.
Known Issues
PINsafe cannot use the Active Primary Group as a Data Source of users, the effects of this are:
- A PINsafe user must have a Primary Group (usually the Domain Users group), and a member of the group for which PINsafe users are being read from.
- The Domain User group cannot be used as a group of PINsafe users (unless another Primary Group is defined for the users)
User Sync Issues
PINsafe 3.8 release 2 onwards, any error retrieving user details will skip over that user, but mark it as deleted (or actually delete the user, if mark as deleted is disabled).
PINsafe 3.5 to 3.8 first release, if an error occurs trying to read a specific user’s details, it will only skip that particular user if the error is “Not found”. Any other LDAP error will cause it to abort.
Group Sync Issues
PINsafe 3.5 and later, Errors attempting to access LDAP or to read the group details will cause the user sync to abort. In earlier versions of PINsafe, such errors could cause all users to be deleted.
<username> Failed to login.
RADIUS: <86> Access-Request(1) LEN=57 <IP address>:12004 Access-Request by <username> Failed: AccessRejectException:
PINsafe 3.8 userPrincipleName (UPN) fails, but using the sAMAccountName (SAM) account name authentication succeeds. This is caused by a bug and is resolved in PINsafe 3.9
Note, this error can also be caused by other issues:
If RADIUS based auth attempt and RADIUS logging enabled. Possible options are: This indicates the user has failed to authenticate successfully. If no other errors are logged in relation to the authentication attempt then the cause is that the user entered the wrong credentials.
This can be caused when an SMS message is to be entered but a Single Channel Image is started, if so then it is expecting a single channel OTC login, until the image times out (default 120 seconds).
The wrong security string index was used (use OTC-String Index, Example 9381-01).
A previously used OTC was attempted to be used again.
Troubleshooting
Membership of multiple alert transport group is not permitted for user
This occurs when users are member of more than one group that is assigned to a string transport entry or alert transport entry. The cause for this can be when users are added either purposely or accidentally to additional groups on the Active Directory or whichever repository type you are syncing with and a subsequent User Sync takes place in PINsafe.
To resolve this issue, on the PINsafe administration console select the User Administration screen. Find a user that is suffering from this problem. Change the View drop down on the User Administration screen to be 'Groups'. Make a note of the groups that the user is assigned to (represented by a tick/check mark). Then visit the Transport -> General screen. You now need to look for Transports you have defined, where these groups have a 'Alert repository group' drop down containing either of the groups you noted in the previous step. It is not possible to have a user assigned to more than one transport sting or transport alert. So you will need to remove the users from the offending group which has led to this situation.
LDAP: error code 49 and AcceptSecurityContext error
PINsafe cannot authenticate to the AD server. Has the AD service account password Expired. Is the username/password correct. Try using use userPrincipalName (username@domain) for the service account to login to AD.
Test the user account with an LDAP browser.
Cannot import users into AD
Is the AD Server accessible? Check by making a telnet connection from the PINsafe server on port 389 or required port. Possible causes are firewalls, routing and network issues, SSL communications only to the AD server. AD server is down. PINsafe Log will report an error.
Is DNS functioning? Check with a NSlookup. PINsafe Log will report an error.
Does the AD group have any users in it?
License exceeded. PINsafe Log will report an error.
Can the AD group be browsed through AD and does it show any users?
Are some users imported and not others?
Cannot import some users
Are users across multiple domains? PINsafe can only read domains for AD domains that it is configured to read. Either create another AD domain or use Global Catalog.
If using the Global Catalog, is PINsafe reading from the Global Catalog AD server? Is the Global Catalog port selected?
The same username exists on multiple AD servers? Use userPrincipalName
No Transport Attribute found for User or No Alert Transport Attribute found for User Possible causes are:
Email Address (optional), if no value exists in AD a no transport attribute error message is logged
Phone Number (optional), if no value exists in AD a no transport attribute error message is logged
Transport has not been defined for user, see Transport_Configuration
Transport Attribute has bot been defined, see Transport_Attribute
Modifications have not been made but PINsafe has not been Synchronised with Active Directory
Network Troubleshooting
Can you ping the AD server?
Can you Telnet to the AD server?
Telnet using diagnostics or the command line of the appliance to see if you can initiate a connection to port 389 (or port being used) of the ip address of the AD server?
Try the following:
[admin@primary ~]# telnet AD_Server_IP 389
If the connection succeeds you will get:
Trying 192.168.0.1...
Connected to 192.168.0.1(192.168.0.1).
Escape character is '^]'.
(You can press Ctrl-C to exit at this point) Connection closed by foreign host.
If the connection fails you will get:
Trying 192.168.0.1...
telnet: connect to address 192.168.0.1: Connection refused
telnet: Unable to connect to remote host: Connection refused
Null Values
If you try and read a user from an Active Directory but get a Null Value error message, it may be that there is no referential integrity. This means that a user can be deleted from AD but when you perform a get Members on the group that user will still be returned.
