Active Directory SSO¶
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.
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.
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.
Configuration¶
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.
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
.
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.
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.
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
asusername@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 ofsuperuser
- 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
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.
Architecture¶
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.
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.