Security

How to configure Phantom to use LDAP/Active Directory for authentication?

sam_splunk
Splunk Employee
Splunk Employee

I want to configure Phantom to use Active Directory for authentication instead of the built-in authentication mechanism. How can I get this working?

0 Karma
1 Solution

sam_splunk
Splunk Employee
Splunk Employee

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:

alt text

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.

alt text

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:

alt text

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.

alt text

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).

alt text

Now we'll click Test Authentication and you hopefully will get a screen that looks something like the following screenshot.

alt text

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:

alt text

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:

alt text

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:

alt text

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:

alt text

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.

alt text

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.

alt text

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.

alt text

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.

alt text

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.

View solution in original post

ucz350
Path Finder

Thanks for the above! Really nice guide. Does anyone know if it is possible to do get phantom to use LDAP but not through Active Directory?

0 Karma

sam_splunk
Splunk Employee
Splunk Employee

Yes, I believe so but I don't have a non-AD directory with which to test. Feel free to reach out on Phantom-Community slack to @sam_phantom and I'd be happy to work with you.

0 Karma

rgresham_splunk
Splunk Employee
Splunk Employee

This is great work!

0 Karma

sam_splunk
Splunk Employee
Splunk Employee

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:

alt text

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.

alt text

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:

alt text

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.

alt text

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).

alt text

Now we'll click Test Authentication and you hopefully will get a screen that looks something like the following screenshot.

alt text

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:

alt text

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:

alt text

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:

alt text

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:

alt text

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.

alt text

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.

alt text

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.

alt text

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.

alt text

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.

aropaltioali
Engager

Hey @sam_splunk !

Cheers for the guide!

I think these types of guides should be included in every admin guide that even has the troubleshooting part; love it! 

Noticed that the logs now reside in /opt/phantom/var/log/phantom/wsgi.log (using OVA:  Phantom 4.10.4.56260)

0 Karma
Get Updates on the Splunk Community!

Index This | I am a number, but when you add ‘G’ to me, I go away. What number am I?

March 2024 Edition Hayyy Splunk Education Enthusiasts and the Eternally Curious!  We’re back with another ...

What’s New in Splunk App for PCI Compliance 5.3.1?

The Splunk App for PCI Compliance allows customers to extend the power of their existing Splunk solution with ...

Extending Observability Content to Splunk Cloud

Register to join us !   In this Extending Observability Content to Splunk Cloud Tech Talk, you'll see how to ...