Opening notes
While there is excellent documentation provided for phantom here: https://my.phantom.us/4.5/docs/admin/user#Authentication, sometimes a screen-by-screen walkthrough can sometimes be helpful. Consequently, this answer is intended as such an example walkthrough for Active Directory as the authentication source for Phantom.
When connecting to an LDAP server you may be able to bind (ldap terminology for 'authenticate') with various levels of security. There can be a great deal of nuance to this and if what I've covered here (in my experience, > 95% of configurations), I'd recommending working with your LDAP administrator.
I will also be using Active Directory which is generally a reasonable and compliant LDAP implementation (see their conformance document here for more information: https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-adts/5b4872af-d421-42ff-9e47-2ce1715...). However, configuration for LDAP in general can be wildly different between vendors so except for Active Directory, this should be considered general guidance, at best.
Preparing Active Directory (Basic requirements)
First thing we want to do is decide where our Phantom users live in our Directory. For my case, I've created a new OU called Phantom Users which holds accounts for Sam and Robert. The path is:
ou=Phantom Users,dc=splunk,dc=lab
and looks something like this:
Next I'm going to create a service account with which Phantom can bind to the directory to perform authentication for the user. For this, I've created a new OU called Service Accounts and within it, a new user called svc-phantom (with no special group memberships or permission adjustments). This configuration looks like the following screenshot.
Finally, we're going to map user roles from a group in the directory to a role in Phantom, so we need to create a few groups. In my example here, In an OU called Groups, I've created two groups called phantom-admins and phantom-readonly. These will be mapped to Administrator and Observer within Phantom, respectively. Robert is a member of phantom-readonly and Sam is a member of phantom-admins. My groups look like the following screenshot:
Configuring Phantom
We're going to do the basic implementation on Phantom now. Note that I won't enable SSL until this basic work is done. If this approach does not work for you, please feel free to merge the sections together as you continue.
Let's log into Phantom and browse to Administration, then User Management, then Authentication. Here we'll see an LDAP tab and an on/off button. Turn LDAP on. Note that if LDAP is enabled, local authentication still works.
Plug in the relevant information for your environment. My settings can be seen in the screenshot below and will be described presently.
- Active: YES (because I'm working on it)
- Server: My local domain controller
- Domain: My domain name
- Bind Username: The user Phantom will bind with (i.e. a service account)
- Bind Password: The (hopefully very strong) password of the bind account
- Test User: The user Phantom will use to verify the settings. Since I have 'sam' who is a member of the 'phantom-admins' group, this is a good test.
- Test Group: The AD group the Test User is a member of. This is only necessary if you're doing Group mapping (which we are in this example).
Now we'll click Test Authentication and you hopefully will get a screen that looks something like the following screenshot.
NOTE: if you do not get a success status here, head down to the Troubleshooting section at the bottom of this answer.
Let's drop down the Advanced section and map our groups. My configuration looks like this:
The key pieces I've adjusted are
User Base DN: This is used on how you want to scope searching. I am searching my entire domain but I could just as easily have scoped it to ou=Phantom Users,dc=splunk,dc=lab and because of my configuration described here, everything would work perfectly.
The Group Base DN: Exactly the same as above, except we're talking about group objects.
Group: Phantom-admins → Administrator
Group: phantom-readonly → Observer
Those last two are where I am mapping group membership to Phantom role. In addition to Role mapping, I can map attributes from my directory to Phantom to more fully populate the user. For example:
So long as those attributes are populated in the directory, as soon as I log into Phantom they will be written on that account under Users:
Lockdown - Securing things
To quote Andy Dufresne, "If you've come this far, maybe you're willing to come a little further". We've got LDAP working, let's go ahead and secure it.... That is, presuming your LDAP has a certificate available and is appropriately configured for SSL or TLS.
In my case, I do have a certificate set up and my server is listening on port 636 for secure LDAP, but when I try to bind, I get the following error:
Why? Well as the documentation I linked at the top mentions, we need to load up our cert to Phantom's keystore. A process described in our docs here: https://my.phantom.us/kb/16/. Nevertheless, I will walk through this as well.
Lucky for you - if you're on Phantom 3.0+ you simply need to copy the root certificate and possibly intermediate certs to Phantom and install them with the install script. The command from the docs looks like this:
phenv python2.7 /opt/phantom/bin/import_cert.py -i /tmp/ca.crt
service uwsgi restart
...and a screenshot from the installation in my lab is just below.
At this point, clicking Test Authentication should work as expected and if it does, you can begin logging in with the appropriate directory users.
Troubleshooting
If you get an error like the following (top right), this can be caused by any of the settings outlined in red.
So, what can you do? Well, you can investigate the log file /var/log/phantom/wsgi.log on the Phantom server. I've outlined some of the errors you might see depending on which field is wrong (highlighting mine).
Bad Server Name:
> generated 184 bytes in 38 msecs (HTTP/1.1 200) 4 headers in 123 bytes (1 switches on core 0)
[04/Sep/2019 02:50:15] WARNING: Caught LDAPError while trying to bind using svc-phantom@splunk.lab: SERVER_DOWN({u'info': 'No such file or directory', 'errno': 2, 'desc': u"Can't contact LDAP server"},)
[04/Sep/2019 02:50:15] ERROR: Traceback (most recent call last):
File "../../www/phantom_ui/ui/rest.py", line 82, in rest_api
File "../../www/phantom_ui/ui/rest.py", line 201, in _rest_api
File "../../www/phantom_ui/ui/rest.py", line 219, in delegate
File "../../www/phantom_ui/ui/rest.py", line 252, in standard_request
File "/builds/phantom/phantom/www/phantom_ui/ui/models/system.py", line 2278, in rest_create
File "/builds/phantom/phantom/www/phantom_ui/ui/models/system.py", line 2123, in test_ldap
File "/builds/phantom/phantom/www/phantom_ui/auth_backends/ph_ldap.py", line 329, in test_connection
File "/opt/phantom/usr/lib/python2.7/site-packages/django_auth_ldap/backend.py", line 458, in connection
self._bind()
File "/opt/phantom/usr/lib/python2.7/site-packages/django_auth_ldap/backend.py", line 786, in _bind
sticky=True)
File "/opt/phantom/usr/lib/python2.7/site-packages/django_auth_ldap/backend.py", line 798, in _bind_as
force_text(bind_password))
File "/opt/phantom/usr/lib64/python2.7/site-packages/ldap/ldapobject.py", line 443, in simple_bind_s
msgid = self.simple_bind(who,cred,serverctrls,clientctrls)
File "/opt/phantom/usr/lib64/python2.7/site-packages/ldap/ldapobject.py", line 437, in simple_bind
return self._ldap_call(self._l.simple_bind,who,cred,RequestControlTuples(serverctrls),RequestControlTuples(clientctrls))
File "/opt/phantom/usr/lib64/python2.7/site-packages/ldap/ldapobject.py", line 329, in _ldap_call
reraise(exc_type, exc_value, exc_traceback)
File "/opt/phantom/usr/lib64/python2.7/site-packages/ldap/ldapobject.py", line 313, in _ldap_call
result = func(*args,**kwargs)
SERVER_DOWN: {u'info': 'No such file or directory', 'errno': 2, 'desc': u"Can't contact LDAP server"}
Bad Bind Name:
[04/Sep/2019 02:52:01] WARNING: Caught LDAPError while trying to bind using svc-phantom1@splunk.lab: INVALID_CREDENTIALS({'info': u'80090308: LdapErr: DSID-0C09042F, comment: AcceptSecurityContext error, data 52e, v2580', 'desc': u'Invalid credentials'},)
[pid: 24507|app: 0|req: 30/42] 192.168.54.22 () {60 vars in 1171 bytes} [Wed Sep 4 02:52:01 2019] POST /rest/system_settings/ => generated 137 bytes in 34 msecs (HTTP/1.1 200) 4 headers in 123 bytes (1 switches on core 0)
Bad User:
[04/Sep/2019 02:52:51] WARNING: Unable to locate user using search_s('dc=splunk,dc=lab', 2, '(&(sAMAccountName=sam1)(objectClass=user))')
Bad Group:
[04/Sep/2019 02:53:17] WARNING: No group named phantom-admins1 returned using search_s('dc=splunk,dc=lab', 2, '(&(member=cn=sam,ou=phantom users,dc=splunk,dc=lab)(objectClass=group))')
Finally, if you see an error like the following, it likely means your LDAP is not configured to securely bind, and troubleshooting should happen on that system.
This will likely have a corresponding event on the Domain Controller like the following. This will be definitive evidence that AD is not configured for secure binds.
Summary
Well, I hope this helps if you've configuring your LDAP/AD to allow Phantom authentication or simply troubleshooting. Feel free to leave comments for follow-up questions.
Opening notes
While there is excellent documentation provided for phantom here: https://my.phantom.us/4.5/docs/admin/user#Authentication, sometimes a screen-by-screen walkthrough can sometimes be helpful. Consequently, this answer is intended as such an example walkthrough for Active Directory as the authentication source for Phantom.
When connecting to an LDAP server you may be able to bind (ldap terminology for 'authenticate') with various levels of security. There can be a great deal of nuance to this and if what I've covered here (in my experience, > 95% of configurations), I'd recommending working with your LDAP administrator.
I will also be using Active Directory which is generally a reasonable and compliant LDAP implementation (see their conformance document here for more information: https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-adts/5b4872af-d421-42ff-9e47-2ce1715...). However, configuration for LDAP in general can be wildly different between vendors so except for Active Directory, this should be considered general guidance, at best.
Preparing Active Directory (Basic requirements)
First thing we want to do is decide where our Phantom users live in our Directory. For my case, I've created a new OU called Phantom Users which holds accounts for Sam and Robert. The path is:
ou=Phantom Users,dc=splunk,dc=lab
and looks something like this:
Next I'm going to create a service account with which Phantom can bind to the directory to perform authentication for the user. For this, I've created a new OU called Service Accounts and within it, a new user called svc-phantom (with no special group memberships or permission adjustments). This configuration looks like the following screenshot.
Finally, we're going to map user roles from a group in the directory to a role in Phantom, so we need to create a few groups. In my example here, In an OU called Groups, I've created two groups called phantom-admins and phantom-readonly. These will be mapped to Administrator and Observer within Phantom, respectively. Robert is a member of phantom-readonly and Sam is a member of phantom-admins. My groups look like the following screenshot:
Configuring Phantom
We're going to do the basic implementation on Phantom now. Note that I won't enable SSL until this basic work is done. If this approach does not work for you, please feel free to merge the sections together as you continue.
Let's log into Phantom and browse to Administration, then User Management, then Authentication. Here we'll see an LDAP tab and an on/off button. Turn LDAP on. Note that if LDAP is enabled, local authentication still works.
Plug in the relevant information for your environment. My settings can be seen in the screenshot below and will be described presently.
- Active: YES (because I'm working on it)
- Server: My local domain controller
- Domain: My domain name
- Bind Username: The user Phantom will bind with (i.e. a service account)
- Bind Password: The (hopefully very strong) password of the bind account
- Test User: The user Phantom will use to verify the settings. Since I have 'sam' who is a member of the 'phantom-admins' group, this is a good test.
- Test Group: The AD group the Test User is a member of. This is only necessary if you're doing Group mapping (which we are in this example).
Now we'll click Test Authentication and you hopefully will get a screen that looks something like the following screenshot.
NOTE: if you do not get a success status here, head down to the Troubleshooting section at the bottom of this answer.
Let's drop down the Advanced section and map our groups. My configuration looks like this:
The key pieces I've adjusted are
User Base DN: This is used on how you want to scope searching. I am searching my entire domain but I could just as easily have scoped it to ou=Phantom Users,dc=splunk,dc=lab and because of my configuration described here, everything would work perfectly.
The Group Base DN: Exactly the same as above, except we're talking about group objects.
Group: Phantom-admins → Administrator
Group: phantom-readonly → Observer
Those last two are where I am mapping group membership to Phantom role. In addition to Role mapping, I can map attributes from my directory to Phantom to more fully populate the user. For example:
So long as those attributes are populated in the directory, as soon as I log into Phantom they will be written on that account under Users:
Lockdown - Securing things
To quote Andy Dufresne, "If you've come this far, maybe you're willing to come a little further". We've got LDAP working, let's go ahead and secure it.... That is, presuming your LDAP has a certificate available and is appropriately configured for SSL or TLS.
In my case, I do have a certificate set up and my server is listening on port 636 for secure LDAP, but when I try to bind, I get the following error:
Why? Well as the documentation I linked at the top mentions, we need to load up our cert to Phantom's keystore. A process described in our docs here: https://my.phantom.us/kb/16/. Nevertheless, I will walk through this as well.
Lucky for you - if you're on Phantom 3.0+ you simply need to copy the root certificate and possibly intermediate certs to Phantom and install them with the install script. The command from the docs looks like this:
phenv python2.7 /opt/phantom/bin/import_cert.py -i /tmp/ca.crt
service uwsgi restart
...and a screenshot from the installation in my lab is just below.
At this point, clicking Test Authentication should work as expected and if it does, you can begin logging in with the appropriate directory users.
Troubleshooting
If you get an error like the following (top right), this can be caused by any of the settings outlined in red.
So, what can you do? Well, you can investigate the log file /var/log/phantom/wsgi.log on the Phantom server. I've outlined some of the errors you might see depending on which field is wrong (highlighting mine).
Bad Server Name:
> generated 184 bytes in 38 msecs (HTTP/1.1 200) 4 headers in 123 bytes (1 switches on core 0)
[04/Sep/2019 02:50:15] WARNING: Caught LDAPError while trying to bind using svc-phantom@splunk.lab: SERVER_DOWN({u'info': 'No such file or directory', 'errno': 2, 'desc': u"Can't contact LDAP server"},)
[04/Sep/2019 02:50:15] ERROR: Traceback (most recent call last):
File "../../www/phantom_ui/ui/rest.py", line 82, in rest_api
File "../../www/phantom_ui/ui/rest.py", line 201, in _rest_api
File "../../www/phantom_ui/ui/rest.py", line 219, in delegate
File "../../www/phantom_ui/ui/rest.py", line 252, in standard_request
File "/builds/phantom/phantom/www/phantom_ui/ui/models/system.py", line 2278, in rest_create
File "/builds/phantom/phantom/www/phantom_ui/ui/models/system.py", line 2123, in test_ldap
File "/builds/phantom/phantom/www/phantom_ui/auth_backends/ph_ldap.py", line 329, in test_connection
File "/opt/phantom/usr/lib/python2.7/site-packages/django_auth_ldap/backend.py", line 458, in connection
self._bind()
File "/opt/phantom/usr/lib/python2.7/site-packages/django_auth_ldap/backend.py", line 786, in _bind
sticky=True)
File "/opt/phantom/usr/lib/python2.7/site-packages/django_auth_ldap/backend.py", line 798, in _bind_as
force_text(bind_password))
File "/opt/phantom/usr/lib64/python2.7/site-packages/ldap/ldapobject.py", line 443, in simple_bind_s
msgid = self.simple_bind(who,cred,serverctrls,clientctrls)
File "/opt/phantom/usr/lib64/python2.7/site-packages/ldap/ldapobject.py", line 437, in simple_bind
return self._ldap_call(self._l.simple_bind,who,cred,RequestControlTuples(serverctrls),RequestControlTuples(clientctrls))
File "/opt/phantom/usr/lib64/python2.7/site-packages/ldap/ldapobject.py", line 329, in _ldap_call
reraise(exc_type, exc_value, exc_traceback)
File "/opt/phantom/usr/lib64/python2.7/site-packages/ldap/ldapobject.py", line 313, in _ldap_call
result = func(*args,**kwargs)
SERVER_DOWN: {u'info': 'No such file or directory', 'errno': 2, 'desc': u"Can't contact LDAP server"}
Bad Bind Name:
[04/Sep/2019 02:52:01] WARNING: Caught LDAPError while trying to bind using svc-phantom1@splunk.lab: INVALID_CREDENTIALS({'info': u'80090308: LdapErr: DSID-0C09042F, comment: AcceptSecurityContext error, data 52e, v2580', 'desc': u'Invalid credentials'},)
[pid: 24507|app: 0|req: 30/42] 192.168.54.22 () {60 vars in 1171 bytes} [Wed Sep 4 02:52:01 2019] POST /rest/system_settings/ => generated 137 bytes in 34 msecs (HTTP/1.1 200) 4 headers in 123 bytes (1 switches on core 0)
Bad User:
[04/Sep/2019 02:52:51] WARNING: Unable to locate user using search_s('dc=splunk,dc=lab', 2, '(&(sAMAccountName=sam1)(objectClass=user))')
Bad Group:
[04/Sep/2019 02:53:17] WARNING: No group named phantom-admins1 returned using search_s('dc=splunk,dc=lab', 2, '(&(member=cn=sam,ou=phantom users,dc=splunk,dc=lab)(objectClass=group))')
Finally, if you see an error like the following, it likely means your LDAP is not configured to securely bind, and troubleshooting should happen on that system.
This will likely have a corresponding event on the Domain Controller like the following. This will be definitive evidence that AD is not configured for secure binds.
Summary
Well, I hope this helps if you've configuring your LDAP/AD to allow Phantom authentication or simply troubleshooting. Feel free to leave comments for follow-up questions.
