Articles in this section

See more

How-to: Configure SkyFormation Authentication to Use ActiveDirectory Server

Avatar
Nadav Lavy (Greenberg)
  • Updated
Follow

If you’re having trouble at any stage please contact us at support@skyformation.com

Compatible with SkyFormation App Version

This guide is compatible with SkyFormation App version 2.1.21 (see Get Your SkyFormation App Version). If you are using an older version of SkyFormation we highly recommend to update to the latest one.

Preface

SkyFormation platform is using an authentication mechanism based on local file with the relevant user:role:credentials information.

It is highly recommended to replace the default authentication mechanism with AD/LDAP based one.
This would allow an easy way to add/remove users allowed access to SkyFormation, and improve the user’s information and credentials security.

This post explains how to use AD server as the SkyFormation authentication service provider.
SkyFormation application will ask the user for his or her userPrincipalName and password and validate these with the configured AD server.

SkyFormation application will not save the user’s credentials sent to the AD.

Prerequisites

- Make sure the SkyFormation machine could communicate with the AD server

- If you plan to use LDAPS (rather than LDAP) please import the AD certificate to the SkyFormation’s trust store. Note: if there are several servers behind the LDAPS url's, and multiple certificates are used, please make sure you add all of the certificates to the trust store. 

- Have the AD server name and port number to use

- Make sure each user you would like to allow access to SkyFormation app is a member of the AD
  group that would be used to allow access to the SkyFormation app

- Have an integration user in AD with read permission (system user). This user is being used to read all the groups the authenticated user is a member of

Step

  1. SSH to your SkyFormation machine
  2. Change user to root
    sudo su -

  3. Locate your sk4_conf volume - run the first command of the two below, if the result is <no value> then run the second command of the two below to get the path.

    docker volume inspect --format='{{.Options.device}}' sk4_conf
docker volume inspect --format='{{.Mountpoint}}' sk4_conf

  4. Backup your existing <sk4_conf_location>/shiro/client-shiro.ini
    cp <sk4_conf_location>/shiro/client-shiro.ini <sk4_conf_location>/shiro/client-shiro.ini.bak

  5. Delete the [users] section

    [users]
sk4admin = password, sk4-admin

  6. If anonymous AD search is supported or for keeping the system user’s password in /shiro/client-shiro.ini file in clear text please add the following lines to the file

    ldapRealm = org.apache.shiro.realm.activedirectory.ActiveDirectoryRealm

# ldap or ldaps
ldapRealm.url = ldap://HOST_OR_IP:PORT

# Optional - to allow dan@myorg.com to authenticate with dan as the username. 
ldapRealm.principalSuffix = @myorg.com

# If white spaces exists int the AD group DN it must be put in double quotes  
ldapRealm.groupRolesMap = "REPLACE_WITH_AD_GROUP":"sk4-admin"

ldapRealm.searchBase = REPLACE_WITH_AD_BASE_SEARCH

# systemUsername and systemPassword are only required if anonymous AD search is not supported
# Existance of principalSuffix also applies to systemUsername 
# So if sk4@myorg.com is the UPN for the system user and principalSuffix is @myorg.com then systemUsername should be sk4
ldapRealm.systemUsername = REPLACE_WITH_SYSTEM_USER_UPN

ldapRealm.systemPassword = REPLACE_WITH_SYSTEM_USER_PASSWORD
securityManager.realms = $ldapRealm

  7. For keeping the system user’s password in the client-shiro.ini file encrypted (if anonymous AD search is not supported) please do the following (supported from 2.4.206):

    • Encrypt the system user’s password (SK4 root directory is either /opt/sk4 or /opt/exabeam/data/sk4 by default)

      docker run --rm skyformation/troubleshoot-utils:latest encrypt-str REPLACE_WITH_PASSWORD `grep SKYFORMATION_ENC_KEY REPLACE_WITH_SK4_ROOT_DIR/docker-compose.yml | head -1 | sed 's/.*SKYFORMATION_ENC_KEY=//'`
    • Copy the encrypted password printed to console

    • Please add the following lines to the file

      ldapRealm = com.skyformation.shiro.realms.SK4ActiveDirectoryRealm

# ldap or ldaps
ldapRealm.url = ldap://HOST_OR_IP:PORT

# Optional - to allow dan@myorg.com to authenticate with dan as the username. 
ldapRealm.principalSuffix = @myorg.com

# If white spaces exists int the AD group DN it must be put in double quotes  
ldapRealm.groupRolesMap = "REPLACE_WITH_AD_GROUP":"sk4-admin"

ldapRealm.searchBase = REPLACE_WITH_AD_BASE_SEARCH

# Existance of principalSuffix also applies to the value you put here. 
# So if sk4@myorg.com is the UPN for the system user, and principalSuffix is @myorg.com, systemUsername should be sk4
ldapRealm.systemUsername = REPLACE_WITH_SYSTEM_USER_UPN

ldapRealm.systemPassword = REPLACE_WITH_SYSTEM_USER_ENCRYPTED_PASSWORD
ldapRealm.passwordEncrypted = true
securityManager.realms = $ldapRealm

  8. Restart SkyFormation’s tomcat microservice docker container restart sk4tomcat

Done

Troubleshooting

  • Username, both the ldapRealm.systemUsername in the ini file and the one being used in the login form must be the User Principal Name (UPN).
  • If you have defined ldapRealm.principalSuffix please verify ALL users that should access the application share the same suffix. This should also be applied for the ldapRealm.systemUsername you are using. If you have more than one unique suffix, you should not define a ldapRealm.principalSuffix and set the full UPN for the ldapRealm.systemUsername and use your full UPN to authenticate.
  • In the ldapRealm.groupRolesMap field - the Active Directory group must be described by its full DN. If the DN contains white characters, it should be wrapped in double quotes.  
  • Please verify that indeed the user trying to authenticate has the active directory group set in the ldapRealm.groupRolesMap field as one of the values in the user's memberOf attribute
  • Please verify that all users that should access the application and the ldapRealm.systemUsername you are using are indeed under the ldapRealm.searchBase in the LDAP tree.
  • Default [users] section must be removed from the ini file.

Sample client-shiro-ini

[main]

sk4Authc = com.skyformation.shiro.filter.SK4FormAuthenticationFilter

sk4Authc.loginUrl = /login.html
sk4Authc.successUrl = /index.html

cacheManager = org.apache.shiro.cache.ehcache.EhCacheManager
cacheManager.cacheManagerConfigFile = classpath:ehcache.xml
securityManager.cacheManager = $cacheManager

sessionDAO = org.apache.shiro.session.mgt.eis.EnterpriseCacheSessionDAO
sessionManager = org.apache.shiro.web.session.mgt.DefaultWebSessionManager
sessionManager.sessionDAO = $sessionDAO

securityManager.sessionMode = native

cookie = org.apache.shiro.web.servlet.SimpleCookie
cookie.name = SSOcookie
cookie.path = /
sessionManager.sessionIdCookie = $cookie

securityManager.sessionManager = $sessionManager

ldapRealm = com.skyformation.shiro.realms.SK4ActiveDirectoryRealm
ldapRealm.url = ldap://ad.exabeam:389
ldapRealm.principalSuffix = @exabeam.com
ldapRealm.groupRolesMap = "CN=SK4,DC=Groups,DC=exabeam,DC=com":"sk4-admin"
ldapRealm.searchBase = DC=exabeam,DC=com
ldapRealm.systemUsername = sk4
ldapRealm.systemPassword = gATNJ0RQzDzWPSHg/kJ1Jg==
ldapRealm.passwordEncrypted = true  
securityManager.realms = $ldapRealm

[urls]
/login.html = sk4Authc
/index.html = sk4Authc, roles[sk4-admin]
/onboard.html = sk4Authc, roles[sk4-admin]
/logout = logout
/ = sk4Authc, roles[sk4-admin]
/** = anon

Related articles

Comments

0 comments

Please sign in to leave a comment.