Articles in this section

Active Directory Integration

Avatar
Phil Havlik
  • Updated

Active Directory Integration

With PolicyStat, you have the option to integrate with your organization’s existing Active Directory (AD) infrastructure, simplifying user and group management for your site administrators. 

What AD Integration Provides

Active Directory integration provides four primary benefits:

1. AD Username/Password Login

Users use their existing AD username and passwords to log in to PolicyStat.

2. User Provisioning

User accounts that are created, updated and deleted in AD automatically have that action mirrored in PolicyStat.

3. User Group Synchronization

Email distribution groups (Exchange/Outlook groups) are mirrored as User Groups In PolicyStat for use in assigning policy acknowledgments.

4. Password Policy Enforcement

All passwords are handled by your existing AD infrastructure, so any password policies you have will be automatically enforced. Any password complexity criteria, required rotations, N-back reuse, etc. that you already require will thus be “mirrored” by PolicyStat.

What AD Integration DOES NOT Provide

AD integration does not synchronize permissions in any way. That process is still managed by site administrators through the User Management screen. It’s important to realize that only the minority of users that edit and approve policies will need special permissions. Synchronized users have guest permissions (read-only access for approved, active documents) by default, which is correct for the majority of your users.

We find that the granular permissions that PolicyStat allows almost never exist as attributes or security groups in an existing Active Directory implementation. These permissions are also fairly fluid and difficult to define at the start of a new PolicyStat implementation, so requiring IT to mirror this structure in AD actually puts a burden on both parties and slows things down. Also, because only users who need to edit policies actually need special permissions, even for a facility with thousands of actual “users,” only 100-200 might need any permission management.

Choosing an AD Connectivity Integration Method

There are two available connectivity options for performing an Active Directory integration, all of which utilize the LDAP protocol. 

Option A: Secure LDAP via an External IP

Price quote available upon request

With this option, your IT department provides an LDAP account with read-only access to your tree of users and also exposes an SSL-secured LDAP port to each of PolicyStat’s six IP addresses. This connection is secured via whichever certificates you choose. This option is generally quickest for organizations that already expose LDAP over SSL (LDAPS) to other applications.

Option B: Site-to-Site Virtual Private Network (VPN)

Price quote available upon request

With this option, your IT department initiates a secure site-to-site VPN between each of PolicyStat’s six AD synchronization IP addresses. PolicyStat will provide its standard connection options, along with a unique Pre-Shared Key. Upon confirmation, your IT department will be able to initiate the site-to-site VPN connection and test the synchronization using the configuration testing dashboard inside PolicyStat.

Note

If none of these options meet your needs, we are open to custom integration work.

FAQ

Q: Do I need to perform AD integration up front?

A: No. AD integration can be performed at any time. In fact, as long as the users you’ve manually created match the usernames used in your Active Directory, there is no additional work needed from site administrators. Even in cases where usernames don’t quite match up, our user merge utility makes it as simple as a few clicks to fix that problem. We do recommend that AD usernames are used from the beginning, even with no AD integration, because it makes it easier for users to remember their login credentials.

Q: What kind of groups are synchronized?

A: By default, the synchronized groups are the email groups that you might see auto-completed when using Outlook. An example might be the “Human Resources” group containing all staff members in the HR department. In technical terms, we sync AD distribution groups, but the LDAP filter to choose groups is actually something your IT department can customize to meet your needs.

Q: Do you provide SSO (Single Sign On)?

A: Yes. We offer SAML 2.0 Single Sign On as a separate integration option. You can combine SSO with AD integration, or you can choose them independently. SSO allows users to be automatically authenticated if they’ve already logged in to other SSO-supporting services. This makes PolicyStat easier to use, especially for your policy owners and approvers.

SAML 2.0 SSO is supported by Microsoft’s Active Directory Federation Services. That means that if your organization runs Windows Server 2008, you should be capable of using this integration.

For more details, please refer to our documentation on Single Sign On

Q: When are users synchronized?

A: User changes are synchronized automatically every evening at 8:12pm Eastern time and manual synchronizations can be performed by your site administrators on demand through the “User Management” screen. Passwords are always up-to-date because every username/password authorization is forwarded in real time to your servers, ensuring password changes are instantly available. PolicyStat does not in any way store or log your password information.

Q: Can I synchronize users and groups whenever I’d like?

A: Yes. Anyone with site administrator permissions can perform an on-demand sync by clicking a button on either the User Management or Create Group pages.

Q: Can I create a user that doesn’t exist in our Active Directory?

A: Yes. If you have a situation that requires you to provide uniquely-authenticated access (for approvals or collaboration) to an individual who cannot be added to your AD, you can create them in PolicyStat as a user managed outside AD. In general, we recommend avoiding this if possible, because it increases potential user management headache for your site administrators.

Q: Can I create or customize groups in PolicyStat?

A: No. If you choose to synchronize groups from Active Directory, all group management must occur there. We find that coordinating with your IT department and using existing groups is the best way to keep groups useful, up to date and manageable. The flexibility of customizing groups in PolicyStat is outweighed by the headache of deciding when to use the changes from Active Directory and when to use changes from PolicyStat. It creates a situation where not only are your site administrators potentially confused about where changes are coming from, but PolicyStat support would struggle to help you meet your goals due to lack of visibility in to AD changes.

Q: Does PolicyStat store user passwords?

A: No. We don’t log or store any user authentication information. We don’t need this information, so we feel that compartmentalizing that information increases security and decreases risk for everyone involved.

Q: What happens if your LDAP service is unavailable?

A: If your LDAP service becomes unavailable, your staff will continue to have read-only access to approved documents via the guest access link. In addition, in instances where LDAP service might be unavailable for an extended period of time, you can temporarily disable AD integration and use the “Forgot Password” link to set up temporary passwords while you work to get your LDAP service restored.

Technical Integration Details

Overview

We recommend first completing the entire integration process on Your Sandboxed, training PolicyStat instance and most of these instructions are geared toward that. Once you have a successful integration there, you can control the process for enabling the integration on your production PolicyStat instance to minimize impact on the whole PolicyStat implementation process.

The general process for configuring the technical side of your integration is:

  1. Follow the process to Enable LDAP Connectivity.
  2. Test LDAP Connectivity.
  3. Then Create A PolicyStat LDAP Synchronization Account.
  4. Configure your LDAP options.

At this point, if everything is successful, you’ll want to copy over all of the configuration from your training to your production PolicyStat instance, without checking the Enable Active Directory Integration box. This insures that if Your Sandboxed, training PolicyStat instance is wiped, you still have the configuration options.

Enable LDAP Connectivity

The process for enabling LDAP connectivity varies based on the option you chose. The following are guidelines for each option.

Option A: Secure LDAP via an External IP

With this option, you’re using Secure LDAP (which is LDAP over SSL, LDAPS) for the connection. The distinction between normal LDAP and LDAPS is important, because normal LDAP is an insecure, clear-text protocol. To enable connectivity, you’ll need to:

  1. Enable LDAPS on your LDAP endpoint.
  2. Configure firewall rules.

Once this is complete, you can then Test LDAP Connectivity.

1. Enable LDAPS on your LDAP endpoint

The process for enabling LDAPS varies based on your environment, so check with your vendor for details. Sometimes, LDAPS will already be enabled. In the case of Windows Server, instructions are available on Microsoft’s Support Site.

Note

You do not need to purchase a commercial SSL certificate. A self-signed certificate will provide the required security.

2. Configure Firewall Rules

Depending on your firewall configuration, you will likely need to add exceptions to allow the PolicyStat servers to access your LDAP endpoint.

The default port for LDAPS is 636, so if you’re configuring LDAPS with default settings, you’ll need to create a firewall ACL allowing access for TCP port 636 from each of the PolicyStat IP Addresses.

Enhanced Security Options

When using LDAPS, we recommend using a firewall rule to specifically disable access on port 389, just so someone doesn’t accidentally try and use normal non-LDAPS LDAP connectivity, which would be a security risk. PolicyStat’s configuration GUI only allows using port 389 because of connectivity Option B: Site-to-Site VPN, which securely tunnels all network traffic. Otherwise we wouldn’t allow access on port 389, just to avoid accidental foot-shooting during configuration.

For organizations with the available resources, we also encourage the use of a Read-Only Domain Controller (RODS) as your LDAPS endpoint. This provides yet another layer of security, allowing you to completely eliminate the possibility of writes and giving you the ability to filter out any sensitive attributes.

Option B: Site-to-Site VPN

This option will require the configuration of an IPSec Site-to-Site VPN using your existing VPN infrastructure (Cisco, Nortel, etc). This process is detailed in the Site-to-Site VPN Guide.

Test LDAP Connectivity

At this point, the PolicyStat servers should be able to reach your LDAP endpoint. During integration kickoff, you will have been provided with a site administrator PolicyStat account. You’ll use this account to login to PolicyStat and then test connectivity through the Active Directory Configuration page.

1. Login to Your Training PolicyStat Instance

Along with your account, you were emailed a URL to a sandboxed, training instance of PolicyStat.

Visit the URL to Your Sandboxed, training PolicyStat instance and log in.

Note

If you have trouble logging in, remember our Tips on your training account password.

2. Navigate to the Active Directory Configuration page

Once you’re logged in, you’ll see the Admin tab in the middle of the screen. Navigate to this tab and then navigate to the Active Directory page, which is located in the Configuration menu.

3. Enter your server information

At this stage, we’re just attempting to verify that we have network connectivity to your LDAP endpoint. To do this, we only need to enter the Server URI corresponding to your LDAP endpoint.

4. Test the configuration

Press the Test This Configuration button, and examine the message for the Server URI field. If that’s a success, then connectivity has been achieved, and you’re ready to move on to LDAP configuration.

If there is an error, you’ll need to double check your configuration. Until this test passes, the integration can’t proceed.

Connectivity Troubleshooting
Is your LDAP endpoint listening?

To eliminate potential firewall issues, use a machine inside your network to attempt to contact your LDAP endpoint.

On a windows machine, you can run the following command:

telnet <host> <port>

eg.

telnet 10.10.100.1 636

If the connection is accepted, it’s likely a firewall issue.

If you the connection is refused, your LDAP endpoint is not properly configured.

If there’s a timeout, you might still have a firewall between you and the endpoint.

Is the connection being blocked by your firewall?

If your LDAP endpoint is listening, it’s likely to be a firewall issue. The process of troubleshooting this varies wildly, depending on your network, but a suggestion is to turn on detailed logging, then perform a Test This Configuration, then examine your logs for incoming traffic from one of the PolicyStat IP Addresses.

Create A PolicyStat LDAP Synchronization Account

All integration methods require that you provide a Bind DN and password that PolicyStat can use to crawl a DN to locate your users. Generally, this will mean creating a new service account in Active Directory, and then providing that account with permission to read your user tree.

Note

When creating this service account, be sure to opt this account out of any mandatory password rotation requirements. Otherwise, your site will lose connectivity when the account’s password expires.

Test the credentials

To ensure the account is properly configured, it’s important to actually test these credentials before moving on. We can do so through the same Active Directory Configuration page that we used to Test LDAP Connectivity.

1. Navigate to the Active Directory Configuration page

Follow the instructions from Test LDAP Connectivity to reach the Active Directory Configuration page.

2. Try your credentials
  1. Use the PolicyStat LDAP Synchronization account’s credentials as the Bind DN and Bind Password.
  2. Click Test This Configuration and ensure authentication succeeded.

Configure your LDAP options

Now that we are successfully authenticating to your LDAP endpoint, we can configure exactly what users and groups are synchronized, along with details about how to map user properties to PolicyStat.

Before you start: Configuration Tips

  1. Don’t check the Enable Active Directory Integration checkbox until you’re 100% sure everything is working correctly on all of the tabs. If your configuration is wrong, you might not be able to login again (since the system will try to authenticate you via active directory, which will fail).
  2. Start by getting the Server URI correct and verifying that with Test This Configuration. If that isn’t correct, nothing will work.

At any time, you can consult the LDAP Configuration Options for reference.

Now you’re ready to login to Your Sandboxed, training PolicyStat instance and navigate to the Active Directory Configuration page.

1. Define User Search Criteria

First, we need to decide what users to pull in. This is done via the User Search Criteria tab. Start with the User Search DN.

For ideas on how to only synchronize a subset of your users, see: Q: How do I synchronize only some of my users?.

2. Define User Attributes

Now that we’ve decided which users to grab, it’s time to decide how to map their properties to the fields that PolicyStat uses. This is done from the User Attributes tab.

3. Optionally define Group Search Criteria

You don’t actually need to sync user groups as part of your integration. If you choose to, this can be configured from the Group Search Criteria tab. Unless the Enable Group Synchronization checkbox is checked, you won’t actually sync groups.

Technical FAQ

Q: How do I synchronize only some of my users?

It’s not uncommon for only some of the users in your Active Directory tree to need individual PolicyStat accounts. Limiting the synchronization to only necessary users eases the user maintenance burden for your site administrators and makes the user search functionality more relevant.

PolicyStat provides two methods for specifying exactly which users will be synchronized.

Filtering By Organizational Unit (OU)

An OU is the place where an object/user lives in the directory tree (think of it like their folder in a file system). You can use the User Search DN option to filter by Organizational Unit (OU). If the users that need individual PolicyStat accounts are already in a separate OU from the users who don’t, then the configuration is simple. Just set the User Search DN to that specific OU. Then, only users in that OU will be included.

Filtering On A User Attribute

If you need to synchronize users from multiple OUs, or if you don’t want to pull in all of the users from a single OU, you’ll need to use an attribute filter. Filter Attribute and Filter Values allow you to synchronize only users matching your User Search DN that also have a specific user attribute.

For example, you might be using PolicyStat to manage your contracts. In that case, it’s likely that only a small group of your users will need to acknowledge the contracts or be given permissions to edit or approve them. These users are probably spread throughout the organization in different OU’s, though, so the User Search DN is not sufficient by itself. In that case, an Active Directory Administrator will need to add a custom attribute to your Active Directory schema to identify the users who need individual PolicyStat accounts. You might call this attribute canAccessPolicyStatContracts, and you might use a Syntax of Boolean when creating the customer attribute. You would then need to add that attribute to the Person class.

Note

You should understand the implications of changing your AD schema.

Once your custom attribute is created, you’ll need to edit the necessary user accounts to set that attribute to 1. Then, in your PolicyStat Active Directory Configuration, you would use a Filter Attribute of canAccessPolicyStatContracts and a Filter Value of 1. By clicking Test This Configuration, you’ll be able to test whether the expected number of users are being filtered.

References

PolicyStat IP Addresses

LDAP connections from the following six IP addresses must be allowed for synchronization to occur. PolicyStat utilizes a geographically-redundant architecture, maintaining connections from two separate servers simultaneously. PolicyStat also provides beta and training versions of PolicyStat, along with the production version, to allow users to test new features and to train against a sandbox without affecting their production environment.

Sandboxed/Training environment:

  • 174.129.226.255
  • 174.129.250.147

Production/Live environment:

  • 184.72.224.151
  • 184.72.224.167

Beta environment:

  • 184.72.236.214
  • 184.72.237.166

Your Sandboxed, training PolicyStat instance

PolicyStat provides each of our customers with a sandboxed, training PolicyStat instance for testing. When testing your integration, we always recommend using this instance first, so that any potential mistakes will not affect your production site.

URL provided via email

During your implementation kickoff, you will receive an email with the URL to your training PolicyStat instance.

Completely Sandboxed

This training instance of PolicyStat is completely separated from your production instance, which allows you to test your configuration without potentially affecting the ongoing implementation. With this training instance, data will be periodically erased and replaced with the data from your production PolicyStat instance (every other Sunday evening during our maintenance window), so be aware that training is for throw-away things.

Tips on your training account password

Because the training PolicyStat instance is synchronized with production regularly, your password might change. If the password you were given and the password you chose don’t work, try the password you used on your production PolicyStat instance.

If you have any account trouble at all, please don’t hesitate to contact us via phone at 317.644.1296 x2 or via email at support@policystat.com. If you’re emailing about a password reset, please mention that the reset needs to happen on your training PolicyStat instance.

LDAP Configuration Options

The following options are available via Admin ‣ Active Directory and define how the LDAP connection is made, along with which users are included and how user attributes map to PolicyStat user attributes.

Server URI

This is the URL of your LDAP server.

Examples:

ldap://ldap1.example.com
ldaps://ldap1.example.com:389
ldaps://192.168.1.1:389
Bind DN

The LDAP binding credential Distinguished Name that PolicyStat will use to synchronize your users. This account needs access to the tree where your users live.

Example:

policystat
Bind Password

The LDAP binding credential password that PolicyStat will use to synchronize your users.

Example:

someThings3cure
Validate LDAPS SSL Certificate

If you are using secure LDAP, you can protect yourself from Man in the Middle attacks by requiring your server’s certificate to be validated. If not enabled, the connection will still be securely encrypted, but an attacker on your local network who is able to successfully spoof IP addresses might be able to intercept and decrypt data.

Certificate Authority Public Certificate

If you are using a self-signed certificate you must specify your server’s public certificate in .pem format. If you’re using a certificate signed by a public, commercial Certificate Authority (e.g. Verisign, GeoTrust, Rapidssl), leave this field blank.

User Search DN

The search Distinguished Name that maps to the users you’d like to synchronize to PolicyStat. These can optionally be filtered by the Filter Attribute and Filter Values options described later.

Example:

OU=HOSPITAL,DC=MY-HOSPITAL,DC=ORG
User ID Attribute

The attribute that will map to a user’s PolicyStat username. This can optionally be filtered by the User ID Suffix in a case where the attribute is namespaced with something like @myhospital.com

Example:

userPrincipalName
User ID Suffix

This value is optionally removed from the end of the attribute specified by User ID Attribute to determine the username used by PolicyStat. Generally, this field can be left blank unless you are using userPrincipleName for the User ID Attribute.

The userPrincipleName LDAP attribute for accounts will often have a common suffix for all users (e.g. jsmith@mycompany.local, bob.jones@mycompany.local). We would prefer to not require users to type the @mycompany.local part to login to PolicyStat. The User ID Suffix allows us to eliminate that need.

For example, to allow the user bob.jones@mycompany.local to login with just bob.jones (eliminating the need to type @mycompany.local), you would use a value of @mycompany.local.

Example:

@myhospital.local
User First Name Attribute

The user attribute that maps to the user’s first name.

Example:

givenName
User Last Name Attribute

The user attribute that maps to the user’s last name.

Example:

sn
User E-Mail Attribute

The user attribute that maps to the user’s email address.

Example:

mail
User Title Attribute

The user attribute that maps to the user’s title.

Note: This field is optional, and if the attribute is left blank, you can still manage user titles manually within PolicyStat. If this attribute is configured, users won’t be able to edit their titles and they will only come through with synchronization.

Example:

title
Filter Attribute and Filter Values

These two non-required options can be used to filter which users are included in the sync.

If given, the value of the Filter Attribute must match the Filter Values in order for this user to be synced. This is actually a simple filter in an LDAP search query that separates the two options by an equal sign and surrounds them in a parenthesis, so more complex queries are possible. Multiple Filter Values values can be a part of the query if they are separated by a comma.

Example:

If the Filter Attribute is givenName and the Filter Values is steve, then a filter will be added like:

(givenName=steve)

This will result in only users with the givenName of steve being synced to PolicyStat.

For further example usage of this field, see Q: How do I synchronize only some of my users?.

Use Active Directory Account Control

If checked, we will assume that all users in your Active Directory have the attribute userAccountControl. Additionally, we will filter out all users that are not considered active or normal users.

For further information about userAccountControl please see this MSDN article

Group Search DN

The search DN that maps to the distribution groups you’d like to synchronize to PolicyStat. These groups will be available for assigning document acknowledgments and for collaboration.

Generally, this will be something like:

OU=GROUPS,DC=MY-HOSPITAL,DC=ORG

In PolicyStat, the group’s name will be the same as its Name attribute (not the Display Name attribute).

Related articles

Comments

0 comments

Please sign in to leave a comment.