21.1. ad-auth - Active Directory SSO

The following documentation is for Active Directory SSO (ad-auth) content package at version v4.7.0-alpha00.7+gc3dce18e066cc0086d10bbe54b1d4b6f15b6bbe8.

The ad-auth Plugin_Provider provides Single Sign On (SSO) integration of username, groups, and password information provided by an external Microsoft Active Directory service for authentication on a Digital Rebar Platform (DRP) Endpoint. Usernames and Groups defined in Active Directory can be used as an authentication backing service for DRP.

Internally defined users can co-exist with the external authentication service users.

21.1.1. Usage

As with all Digital Rebar Platform Plugins, you must first install the plugin_provider, and then instantiate a new plugin to configure the AD Authentication capabilities.

The operation of the ad-auth plugin can be altered by defining parameters on the plugin object for the ad-auth Plugin Provider.

21.1.1.1. Installation

There are two parts to installing plugins in the Digital Rebar Platfrom (DRP). The first is installing the Plugin Provider, which enables the given plugin capabilities to the system. The second is to instantiate a Plugin from the installed Plugin Provider. Not all Plugin Providers require an instantiated Plugin to be configured; however, you must do so for ad-auth.

Examples for installing the ad-auth Plugin Provider:

Command Line

drpcli catalog item install ad-auth

Web Portal/UX

  • Go to Catalog
  • Enter ad-auth in catalog search bar (next to the Categories filter); hit Enter
  • Select the version of the ad-auth plugin you’d like to install
  • Click on the green down arrow/install icon to the right of the version

Instantiating a Plugin from the Plugin provider is done by creating a Plugin of type ad-auth Plugin Provider. Examples below.

Command Line

drpcli plugins create /some/path/foo.yaml

Where “/some/path/foo.yaml” is a YAML (or JSON) formatted configuration that sets the Provider to type ad-auth, and sets appropriate Params values. See the Example Configuration section below for more details.

21.1.2. Configuration

21.1.2.1. Base Configuration

By default, the ad-auth plugin requires the configuration of an Active Directory URL (ad-auth/ad-url) and a Base Domain Name (ad-auth/base-dn) to query against.

With these two values, the system will verify password and username access and if it works will return a successful User object.

By default; no groups will be queried or validated against. The default role of a user if no groups are provided is defined by the ad-auth/default-role parameter on the ad-auth plugin. If no configuration is provided, the default role will be mapped to the DRP role of superuser.

If additional domains need to be queried, the ad-auth/additional-dns can be configured with more domains to query. Note that additional domains are queried in addition to the ad-auth/base-dn and only one needs to return a result.

If TLS configuration needs to be modified from the default of NONE, the ad-auth/ad-tls parameter can be used to set other modes of operation.

21.1.2.2. Group Configurations

By configuring some additional parameters, group membership can be used to allow or deny access and define DRP role operation.

The ad-auth/groups list defines the list of Active Directory groups that should be queried from Active Directory. It only returns groups that have been requested.

The Roles assocatied with the User can also be group specific. The parameter, ad-auth/group-roles-map, defines the mapping of Active Directory Group names to Digital Rebar Provision Roles. All matching groups provide the roles cumulatively to the authenticated User. These matched roles override the ad-auth/default-role value.

Setting the ad-auth/deny-if-no-groups parameter to true will allow access if user is a member of a group defined in the ad-auth/groups list and that group defines a set of roles for a group or groups in the ad-auth/group-roles-map.

21.1.2.3. User Timeouts

Digital Rebar Platform (DRP) will cache Active Directory User information if a match is found. This cache is used to ensure consistent performance and reduce impact on the external Active Directory systems. It is important that these values be adjusted to match an organizations security stance on user account credentials provided from the AD service and consumed by DRP.

To keep DRP from hammering the system and having stale Active Directory User information, the system provides two parameters to control how long a user stays in the system. The first is ad-auth/user-activity-check. This defines how often in seconds should the systems users be removed. The default is once a day.

The second parameter is ad-auth/user-activity-window. This parameter defines how long the User can stay in Digital Rebar Provision without having a password based auth in seconds. The default value is 30 days.

21.1.2.4. Example Configuration

Below are some example configurations that are known to work with existing Active Directory services. Note that some Active Directory services may be configured differently, and some of these values will have to be adjusted for your specific implementation.

21.1.2.4.1. Command Line

Below is an example Plugin configuration in YAML format that is validated to work successfully.

Name: corp-ad-sso
Provider: ad-auth
Params:
  ad-auth/ad-tls: TLS
  ad-auth/ad-url: ldaps://ldap.company.internal:3269
  ad-auth/base-dn: DC=department,DC=company,DC=com
  ad-auth/deny-if-no-groups: true
  ad-auth/group-roles-map:
    DRP_Admins:
    - superuser
  ad-auth/groups:
  - DRP_Admins
  ad-auth/user-activity-check: 86400
  ad-auth/user-activity-window: 259200

Descriptions:

  • Searches baseDN of department.company.com
  • Sets userPrincipleName as username@department.company.com, which is formed from concatenating the baseDN, testing it, then trying the additionalDNs and testing them for a first match
  • Constructed search would be CN=username,OU=Users,OU=Corporate,DC=department,DC=company,DC=com
  • NOTE that OU=Users,OU=Corporate was returned as part of the FQDN search, from the non-FQDN query
  • Found group would be set as CN=DRP_Admins,OU=Enterprise Groups,DC=department,DC=company,DC=com
  • NOTE that OU=Enterprise Groups was returned as part of the FQDN search, from the non-FQDN query (you can not specify an FQDN baseDN)
  • Denies login if the user is not found in any of the specified groups
  • Maps the AD group named DRP_Admin to the Digital Rebar Platform role of superuser
  • Only searches the Active Directory DRP_Admin group for valid users, using a memberOf query with a value using the FQDN group name as returned from the LDAP server

The above YAML example can be applied by the following use of the drpcli command:

# if not already installed, install the 'ad-auth' plugin_provider
drpcli catalog item install ad-auth

# save the above example YAML as '/tmp/ad.yaml' - modify for your use

# instantiate a plugin named 'corp-ad-sso` with the '/tmp/ad.yaml' configuration
drpcli plugins create /tmp/ad.yaml

21.1.2.4.2. Portal/UX Configuration

Install the Plugin Provider named Active Directory SSO (short name is ad-auth) via the Catalog. Ensure that you have the Enterprise Category filter selected to view it. Alternatively, you can type ad-auth in the Search bar to view it. Select the most current stable version, and click on the Install icon.

Portal/UX configuration can be accomplished by adding a new Plugin of Plugin Provider type ad-auth. Edit the newly added Plugin by adding the above example Param values.

Save the Params.

21.1.3. Architecture

21.1.3.1. Authentication Binding Details

The AD Auth plugin utilizes an LDAP BIND with the password and username style syntax (eg username@domain). Each domain that is specified will be searched, until an entry is found. The memberOf request type will be used in the getAttributes call on the attribute userPrincipleName, until an entry is found.

All domains specified in the baseDN (configured via the Param ad-auth/base-dn), and additionalDNs (configured via the Param ad-auth/additional-dns) will be searched.

The userPrincipleName is not configurable at this time within the plugin.

The search is performed as a non-FQDN search format. As such, do not specify the Organizational Units (OU) components in the ad-auth/base-dn or ad-auth/additional-dns Param configurations.

21.1.3.2. Auth Architecture Notes

The ad-auth plugin provides an extension to the default authentication system of Digital Rebar Provision to include Active Directory integration. This will use the LDAP-based Active Directory integration.

The ad-auth plugin provides the DRP system action, authenticate. This action takes two parameters as input, auth/username and auth/password. These values are used to test access against a set of configure Active Directory Domain Controllers and different domains.

Note

The auth/username and auth/password Params should not be set by an operator, they are only used internally.

If the username and password are NOT accepted by an Active Directory Server, the action returns an error and DRP will continue its authentication process.

Once successful, the action will return a User model object filled with the Secret Hash of the password and meta data fields for tracking group membership, the plugin doing the authentication, and the time authentication. Optionally, user roles can be assigned based upon Active Directory group membership.

These internal User objects are used to generate placeholder users to hold token information for continued access to the Digital Rebar Platform. To limit the scope and visibility of these tokens, the ad-auth/user-activity-check and ad-auth/user-activity-window allow for configuration of user timeouts and cleanup stale users on the DRP side.

21.1.4. Object Specific Documentation

21.1.4.1. params

The content package provides the following params.

21.1.4.1.1. ad-auth/ad-tls

This parameter defines the tls mode for the AD server to authenticate against.

Supported values are:
  • TLS
  • STARTTLS
  • NONE

The default value if not specified is NONE.

21.1.4.1.2. ad-auth/ad-url

This parameter defines the url for the AD server to authenticate against.

Example:
ldap://my.server.com:389

If using TLS or STARTTLS, specify ldaps:// as the protocol in the URL.

21.1.4.1.3. ad-auth/additional-dns

Additional domains to authenticate against. This is an array of strings, that should NOT contain the Organizational Unit (OU) but should contain the Domain Components (DC) necessary to find users in.

Example:

[ "DC=drp-readonly,DC=example,DC=com", "DC=drp-admins,DC=example,DC=com" ]

21.1.4.1.4. ad-auth/default-role

This parameter provides the default role for a user that matches no groups. The default value is superuser.

21.1.4.1.5. ad-auth/groups

This is a list groups that will be returned by AD if the user is a member of them.

These will be used against the maps to set roles and tenants.

Example:
[ "group1", "group2", "group3" ]

21.1.4.1.6. ad-auth/user-activity-window

DRP caches User objects and password hashes. This value changes the caching behavior for these credentials.

This parameters specifies how long a user should be idle (not having logged in with a password) before being removed (in seconds). The default is 259200 seconds (or 30 days).

The minimum must be one day (86400 seconds).

21.1.4.1.7. ad-auth/base-dn

The base DN for the queries. This is a single string, that should NOT contain the Organizational Unit (OU), but should contain the Domain Components (DC) necessary to find users in.

Example:
"DC=drp-admins,DC=example,DC=com"

21.1.4.1.8. ad-auth/deny-if-no-groups

This parameter, if set to true, denies access to users who authenticate but do not match any AD groups specified in the ad-auth/groups parameter. The default value is false.

21.1.4.1.9. ad-auth/group-roles-map

This is a map of group names to a list of roles for that group.

All matches will be applied.

Example:
{
  "group1": [ "role1", "role2" ],
  "group2": [ "role2", "role3" ]
}

21.1.4.1.10. ad-auth/user-activity-check

DRP caches User objects and password hashes. This value changes the caching behavior for these credentials.

This parameters specifies how often ad-auth should check for stale users (in seconds). The default is 86400 seconds (or 1 day).

The minimum allowed value is one hour (3600 seconds). There is no defined maximum value.

21.1.4.1.11. auth/password

This parameter provides the password to attempt to authenticate on an authenticate call. It is passed as an argument on an authenticate call.

The auth/username and auth/password Params are only used for internal authentication tracking. Please see the Auth Architecture Notes section for more details.

Note

DO NOT set this value anywhere, it is only used internally.

21.1.4.1.12. auth/username

This parameter provides the username to attempt to authenticate on an authenticate call.

The auth/username and auth/password Params are only used for internal authentication tracking. Please see the Auth Architecture Notes section for more details.

Note

DO NOT set this value anywhere, it is only used internally.