LDAP Integration
This page discusses Stardog’s support for LDAP as a means for authenticating enterprise users.
Page Contents
Overview
Stardog can use an LDAP server to authenticate enterprise users. Stardog assumes the existence of two different groups to identify regular and superusers, respectively. Groups must be identified with the cn attribute and be instances of the groupOfNames object class. Users must be specified using the member attribute.
For example:
dn: cn=stardogSuperUsers,ou=group,dc=example,dc=com
cn: stardogSuperUsers
objectclass: groupOfNames
member: uid=superuser,ou=people,dc=example,dc=com
dn: cn=stardogModelers,ou=group,dc=example,dc=com
cn: stardogModelers
objectclass: groupOfNames
member: uid=hank,ou=people,dc=example,dc=com
dn: cn=stardogReaders,ou=group,dc=example,dc=com
cn: stardogReaders
objectclass: groupOfNames
member: uid=beth,ou=contractors,dc=example,dc=com
Credentials and other user information are stored as usual:
dn: uid=superuser,ou=people,dc=example,dc=com
objectClass: inetOrgPerson
cn: superuser
sn: superuser
uid: superuser
userPassword: superpassword
dn: uid=hank,ou=people,dc=example,dc=com
objectClass: inetOrgPerson
cn: hank
sn: hank
uid: hank
userPassword: hankpassword
dn: uid=beth,ou=contractors,dc=example,dc=com
objectClass: inetOrgPerson
cn: beth
sn: beth
uid: beth
userPassword: bethpassword
Configuring LDAP
In order to enable LDAP authentication in Stardog, we need to include the following properties in stardog.properties:
| Property | Updatable | Description |
|---|---|---|
security.realms | No | must provide a value of ldap |
ldap.provider.url | No | The URL of the LDAP server |
ldap.security.principal | No | An LDAP user allowed to retrieve group members from the LDAP server |
ldap.security.credentials | No | The principal’s password |
ldap.user.dn.templates | Yes | A list of templates to form LDAP names from Stardog usernames |
ldap.superusers.group | Yes | The distinguished name of the group identifying Stardog superusers |
ldap.role.mappings | Yes | A mapping from Stardog roles to LDAP groups |
ldap.member.attributes | No | Optional list of LDAP attributes that list a group’s members, default to member,uniquemember |
ldap.user.class.filter | Yes | Optional LDAP expression used to filter user classes. e.g., (&(|(objectClass=user)(objectClass=inetOrgPerson))(!(objectClass=device))) |
ldap.user.name.attribute | Yes | Optional A property of user DN to extract username from (if specified, takes priority over DN template) |
ldap.group.class.filter | No | Optional LDAP expression used to filter group classes, default to (|(objectClass=group)(objectClass=groupOfNames)(objectClass=groupOfUniqueNames)) |
ldap.consistency.scheduler.expression | No | Optional cron expression. See Stale Permissions/Roles |
ldap.cache.invalidate.time | No | Optional time duration to invalidate cache entries, default to 24h |
ldap.groups.ignore.nested | No | Optional ignore nested groups when determining group membership, default to true |
Example
Here’s an example stardog.properties file:
security.realms = ldap
ldap.provider.url = ldap://localhost:5860
ldap.security.principal = uid=admin,ou=people,dc=example,dc=com
ldap.security.credentials = secret
ldap.user.dn.templates = "uid={0},ou=people,dc=example,dc=com","uid={0},ou=contractors,dc=example,dc=com"
ldap.superusers.group = cn=stardogSuperUsers,ou=group,dc=example,dc=com
ldap.role.mappings = "modelers":"cn=stardogModelers,ou=group,dc=example,dc=com","queryers":["cn=stardogReaders,ou=group,dc=example,dc=com","cn=stardogModelers,ou=group,dc=example,dc=com"]
ldap.member.attributes = member
ldap.cache.invalidate.time = 1h
This properties file, when pointing to an LDAP server with the entries listed above, will create 3 users: superuser, hank and beth. superuser will be a superuser and will not be a member of any Stardog role. beth will be a member of the queryers role, and hank will be a member of both the modelers and queryers roles (note both modelers and queryers have a mapping to cn=stardogModelers,ou=group,dc=example,dc=com). Permissions can be granted to these users and roles as usual using the user grant and role grant admin commands.
User Management
When Stardog is configured to delegate to LDAP, users can no longer be added/removed/modified via Stardog. User management is performed in the LDAP server. Roles are defined by mappings to LDAP groups, as defined in the ldap.role.mappings property, and membership in those roles is controlled by membership in the mapped LDAP groups.
Permissions continue to be assigned to users and roles through Stardog, though it is recommended to manage permissions at the role level rather than at the individual user level. The benefit to doing so is that once role permissions have been set up, new users can be created and granted the appropriate permissions exclusively through LDAP (via their group memberships), without needing to interact with Stardog.
Wildcards in Templates
It is possible to use wildcards as values of relative distinguished names (RDN) in LDAP templates. For example, instead of having two templates in our configuration:
ldap.user.dn.templates = "uid={0},ou=people,dc=example,dc=com","uid={0},ou=contractors,dc=example,dc=com"
We can have a single template where the ou RDN can match any value:
ldap.user.dn.templates = "uid={0},ou=*,dc=example,dc=com"
The wildcard only matches a single RDN. This means a template uid={0},ou=people,dc=* would not match uid=hank,ou=people,dc=example,dc=com because the user DN has two dc RDNs.
Authenticated User Cache
Stardog includes a time-constrained cache with a configurable time for eviction, default to 24 hours. To disable the cache, the eviction time must be set to 0ms.
Authorization
Authorization is controlled by user and role permissions in Stardog, while role membership is controlled by membership in LDAP groups.
Stale Permissions/Roles
Permissions and roles in Stardog might refer to users that no longer exist, i.e., those that were deleted from the LDAP server. This is safe, as these users will not be able to authenticate (see above). It is possible to configure Stardog to clean up the list of permissions and roles periodically according to the latest users in the LDAP server. In order to do this, we pass a Quartz cron expression using the ldap.consistency.scheduler.expression property:
## Execute the consistency cleanup at 6pm every day
ldap.consistency.scheduler.expression = 0 0 18 * * ?
Nested Groups
In LDAP, the value of a member attribute for a group can be another group. This allows LDAP administrators to nest groups of related users under a hierarchy of parent groups.
In Stardog, you can use these nested group structures to recursively map parent roles to the users found in the nested groups.
By default, nested groups found by Stardog are ignored. To enable them, set the ldap.groups.ignore.nested property to false. Then the mapped roles of a parent group will be assigned to the users found in nested groups.
To modify how Stardog distinguishes groups from user members, you can change the default LDAP group search in ldap.group.class.filter. The default search matches any object with a group, groupOfNames, or groupOfUniqueNames object class.