On this page:

13.5LDAP Inbound Security Module


The LDAP Inbound Security module can be used to delegate authentication decisions to an external user directory – such as a Microsoft Active Directory server or an OpenLDAP directory.

Unlike the Local Inbound Security module, the LDAP Inbound Security module authenticates against an external directory, and it does not store any passwords in the Smile CDR database.

This type of authentication is useful when deploying Smile CDR in an enterprise context since many organizations have a corporate user directory that allows users to use the same credentials across multiple servers.

Note that each user account that is successfully authenticated by the LDAP server will have a corresponding entry created in the Smile CDR User Database. This locally stored account will not store credentials and cannot be used directly for authentication but it is needed in order to provide a reference point for audit log entries, etc.


When configuring the BaseDN for Groups property of the LDAP Inbound Security Module, point it at a small subset of the tree within the LDAP, and not at the root of the entire LDAP tree, or there could be performance problems. For example, if you know that there will only be 3 users who might need access to administer your SmileCDR deployment, then create a separate LDAP Group, add them to that Group, and point the BaseDN to that small LDAP subtree.



In order to connect to an LDAP server, Smile CDR requires credentials for a system account in the server that it will use to locate accounts, look up groups, etc.

Mandatory Group

If only a subset of users in the LDAP server should have access to Smile CDR, you may wish to create a group in the directory for this purpose, and add all relevant users to this group. The CN for this group should then be listed in the authenticator.require_group_membership.dn configuration property.

In this scenario, any user who is not a member of the given group will not be permitted to authenticate via this module even if they supply correct credentials.



In most cases, simply authenticating is not sufficient to provide useful functionality. A user also requires permissions in order to perform actions within Smile CDR.

There are several ways that a user can be granted permissions:

  • Global Permissions – Any permissions configured as global permissions will be automatically granted to any users who authenticate via this module.
  • Native Permissions – An LDAP user attribute may be declared in Smile CDR configuration to be a native permission user attribute. With this setting, values in this attribute will be treated as Smile CDR permissions that should be granted to that user. For example, if the smileCdrPermission LDAP attribute is configured as a native permission attribute and a user in the LDAP server has a smileCdrPermission attribute with a value of FHIR_ALL_READ, that user will be granted the FHIR_ALL_READ permission.
  • Local Permissions – After a user has successfully authenticated at least once, they will have an entry in the Smile CDR User Database. Permissions may be directly assigned to the user via the Web Admin Console or the JSON Admin API User Management Endpoint.

13.5.3Callback Scripts


When using an LDAP directory to perform user authentication, in a real-world scenario you will likely have a mapping of LDAP group memberships and/or user attributes to Smile CDR permissions.

For example, you might have a group in your LDAP for administrative superusers, and another group for FHIR Clients. Users who sign in with an account that is a member of the first group might be assigned one set of Smile CDR permissions, while other users who sign in with the second group would get different Smile CDR permissions.

The Smile CDR Authentication Callback Scripts functionality can be used to programatically supply these mappings.

Function: onAuthenticateSuccess(theOutcome, theOutcomeFactory, theContext)

This function is called after the user has successfully authenticated aganst the LDAP directory (i.e. the credentials have been confirmed to be correct) but before Smile CDR has created a user session. The function can enhance the session (e.g. by adding authorities) or can even abort it.


  • theOutcome – This parameter is of type UserSessionDetails. It will be pre-populated by the module with basic demographic details pulled from the authenticated user's LDAP entry, but may have no assigned authorities by default. The script will likely want to add some.

  • theOutcomeFactory – This parameter is of type ScriptAuthenticationOutcomeFactory. This parameter can be used to create a failure object if you wish to abort the login from your script.

  • theContext – This parameter is of type SecurityInLdapAuthenticationContext. It can be used to query the LDAP directory for details about the authenticated user.


function onAuthenticateSuccess(theOutcome, theOutcomeFactory, theContext) {

   // Grant authorities based on whether the user has a specific attribute
   if (theContext.getStringAttributes("adminUser").includes("true")) {
   // Grant authorities based on group membership
   if (theContext.isMemberOfGroup("DC=FHIR-Admins,OU=Groups,O=example.com")) {

   return theOutcome;



A complete reference of configuration items follows: