Configure single sign-on authentication for Splunk Phantom

Integrate Splunk Phantom with your existing authentication system using single sign-on (SSO).

You can configure SSO in Splunk Phantom with the following identity providers:

• LDAP
• OpenID
• SAML2

You can have any combination of local users and SSO users in your Splunk Phantom instance, any combination of SSO providers, and multiple instances of any provider type.

Configure SSO authentication using LDAP

To configure SSO authentication using LDAP as the identity provider, perform the following steps:

1. From the Main Menu, select Administration.
2. Select Users > Authentication.
3. LDAP is selected by default. Toggle the switch in the LDAP field to enable LDAP configuration.
4. Complete the fields to configure SSO authentication using LDAP:
   

   Field	Description
   Active	Use this checkbox in conjunction with Add Another at the bottom of the page. You can have multiple LDAP servers and the Active checkbox determines which ones are used by Splunk Phantom for authentication. The toggle button in the LDAP field enables LDAP authentication for all servers which are marked Active. If there are multiple LDAP servers, Splunk Phantom searches each server in a random order to find a match for the username. If the same username exists on multiple servers, the first one matched is used. If this match happens to be for a different user and not the user who is attempting to login, then authentication fails.
   Require TLS/SSL encryption	Determines whether secure LDAP connections are required. Enable TLS/SSL encryption to check the server certificate against the Splunk Phantom certificate store. See Manage the Splunk Phantom certificate store.
   Provider Name	The name of the SSO provider. Specify a unique name to easily identify this provider.
   Server	The DNS name or IP address for your AD/LDAP Server, without http:// or https://. If you plan to use SSL, you must supply a DNS name that matches the certificate.
   Domain	The domain name of your organization such as corp.yourorganization.cpom, used to generate DNS. This field is used as part of the LDAP query.
   Bind Username	The username for authenticating to the LDAP server. It will ideally be a service account specifically set up for this purpose, not one belonging to a human user.) This will allow you to grant the account the minimal permissions necessary, set account expiration off, and other protective measures to track how the account is used. If the account is set to expire or requires a password change, do these tasks manually and also update the Splunk Phantom system settings to reflect the same. The account will need to be able to query LDAP users and their properties.
   Password	The password for the username to authenticate to the LDAP server.
   Test User	The username of an active user who would typically log in to Splunk Phantom. Use this to verify that user search is working correctly.
   Test Group	The name of a group of which the Test User is a member. Use this to confirm that the group mapping will work. Leave this field blank if you are not using group mapping.
   Manage password using Hashicorp Vault	Use a password vault to manage user credentials. See Manage your organization's credentials with a password vault.

5. Click Test Authentication to test that Splunk Phantom can communicate with and query the LDAP server. Your LDAP settings will automatically be saved if the result is success. Or you can click Save Changes to save the settings without testing them.

LDAP provider names must be unique. Using multiple LDAP providers with the same name is not supported.

On Microsoft Active Directory LDAP servers, the user authentication uses the email-like form of the username, such as ldap-client@splunk.com. The specified username is appended with the domain name. Advanced settings may be required for non-Microsoft LDAP servers. Contact Phantom Support for assistance. See Where to get help.

Configure group mappings for LDAP SSO authentication

Configure a group mapping to map an LDAP group such as Incident Response to a Splunk Phantom role such as Automation Engineer. Doing so enables you to automatically use your LDAP groups to determine who can log into Splunk Phantom and which actions each user is able to perform after they log in. Click Add Mappings to create a new mapping. You can configure multiple mappings.

Each LDAP user must be mapped to at least one group to enable that user to login to Splunk Phantom without manually creating the user account in Splunk Phantom.

Role mapping is done at login time, meaning that if the Splunk Phantom administrator changes a role mapping that would affect a logged-in user, then that user will retain the old role(s) until they log out and log back in again.

Configure external attribute mapping for LDAP SSO authentication

In some cases you may need to specifically call out external attributes which should be mapped to Splunk Phantom user attributes. Click Add Mapping to select a Splunk Phantom user attribute to map, then use the text field to enter the name of the attribute found in your LDAP user's profile.

Configure SSO authentication using SAML2

To configure SSO authentication using SAML2 as the identity provider, perform the following tasks:

1. From the Main Menu, select Administration.
2. Select Users > Authentication.
3. Click SAML2.
4. Click the toggle in the SAML2 field to enable SAML2 configuration.
5. Complete the fields to configure SSO authentication using SAML2:
   

   Field	Description
   Active	Use this checkbox in conjunction with Add Another at the bottom of the page. You can have multiple SAML2 servers and the Active checkbox determines which ones are used by Splunk Phantom for authentication. The toggle button in the SAML2 field enables SAML2 authentication for all servers which are marked Active. If there are multiple SAML2 servers, Splunk Phantom searches each server in a random order to find a match for the username. If the same username exists on multiple servers, the first one matched is used. If this match happens to be for a different user and not the user who is attempting to login, then authentication fails.
   Require TLS/SSL encryption	Determines whether encrypted connections are required. Enable TLS/SSL encryption to check the server certificate against the Splunk Phantom certificate store. See Manage the Splunk Phantom certificate store.
   Provider Name	The name of the SSO provider. Specify a unique name to easily identify this provider.
   Single sign-on URL	The URL that users are directed to for logging in.
   Issuer ID	The unique identifier provided by the identity provider.
   Metadata URL	The URL hosted by your identity provider containing information about the provider configuration. If you specify a valid Metadata URL, do can leave the Metadata XML field blank.
   Metadata XML	XML code containing information about the provider configuration. If you specify valid XML in this field, you can leave the Metadata URL field blank.
   Phantom Base URL	The URL used to redirect users back to Splunk Phantom. This URL must be reachable by users trying to log in.
   Advanced Settings	Click Advanced to configure the following advanced settings: Select Response Signed to require a signed response from the identity provider. Select Request Signed to require a signed request from the identity provider. Select Assertion Signed to require a signed assertion containing the user attributes from the identity provider. Enter an EntityID/Audience to configure an entity ID for the service provider. This is used when defining the audience restriction on the identity provider. Enter a Group Key to identity identify the group membership data within the attributes passed back from the identity provider. Also specify a Group Delimiter if groups are passed back as a single element with a delimiter, instead of separate attribute values. Configure Groups. See Configure group mappings for LDAP SSO authentication for more information about group mapping. Configure External Attributes. See Configure external attribute mappings for LDAP SSO authentication for more information about external attributes mapping.

6. Click Save Changes.

Configure SSO authentication using OpenID

To configure SSO authentication using OpenID as the identity provider, perform the following tasks:

1. From the Main Menu, select Administration.
2. Select Users > Authentication.
3. Click OpenID.
4. Click the toggle in the OpenID field to enable OpenID configuration.
5. Complete the fields to configure SSO authentication using OpenID:
   

   Field	Description
   Active	Use this checkbox in conjunction with Add Another at the bottom of the page. You can have multiple OpenID servers and the Active checkbox determines which ones are used by Splunk Phantom for authentication. The toggle button in the OpenID field enables OpenID authentication for all servers which are marked Active. If there are multiple OpenID servers, Splunk Phantom searches each server in a random order to find a match for the username. If the same username exists on multiple servers, the first one matched is used. If this match happens to be for a different user and not the user who is attempting to login, then authentication fails.
   Require TLS/SSL encryption	Determines whether encrypted connections are required. Enable TLS/SSL encryption to check the server certificate against the Splunk Phantom certificate store. See Manage the Splunk Phantom certificate store.
   Provider Name	The name of the SSO provider. Specify a unique name to easily identify this provider.
   Issuer	The base endpoint provided by OpenID. Configuration is based on the discovery document located at <endpoint>/.well-known/openid-configuration.
   Client ID	Provided by OpenID.
   Client Secret	Provided by OpenID.
   Phantom Base URL	The URL used to redirect users back to Splunk Phantom. This URL must be reachable by users trying to login.
   Advanced Settings	Click Advanced to configure the following advanced settings: Enter Scopes to include custom scopes or to limit the scopes requested by Splunk Phantom. The openid scope is required. Set the Token Auth Method to client_secret_post or private_key_jwt, depending on the configuration of your identity provider. Specify a Resource Identifier if a specific resource other than the default userinfo endpoint is required to obtain user data. Enter a Group Key to identity identify the group membership data within the attributes passed back from the identity provider. Also specify a Group Delimiter if groups are passed back as a single element with a delimiter, instead of separate attribute values. Configure Groups. See Configure group mappings for LDAP SSO authentication for more information about group mapping. Configure External Attributes. See Configure external attribute mappings for LDAP SSO authentication for more information about external attributes mapping.

6. Click Save Changes.

Manage the Splunk Phantom certificate store

Splunk Phantom has a certificate store used to validate certificates when forming connections to other servers. The certificates in the store are trusted certificate authority (CA) certificates from mkcert.org and are updated periodically. In almost all cases, Splunk Phantom can use its certificate store to validate any certificate issued by a commercial certificate authority (CA).

The default certificate store cannot be used to validate self-signed certificates, or certificates issued by an internal CA. You must add these custom certificates to the Splunk Phantom certificate store. To so this, use the following commands:

phenv python2.7 /opt/phantom/bin/import_cert.py -i /tmp/ca.crt
service uwsgi restart

In this example, the import_cert.py script is copying the certificate file ca.crt to the /opt/phantom/etc/certs/ directory, then consolidating all the files in that directory to the /opt/phantom/etc/cacerts.pem file. The cacerts.pem file is used by Splunk Phantom to verify all server certificates.

The service uswgi restart restarts the web server so the updated cacerts.pem file is reloaded.

If you need to remove a certificate that you have previously installed, perform the following tasks:

1. Delete the file for that certificate from /opt/phantom/etc/certs/.
2. Run the import_cert.py script with no parameters.
3. Restart the web server.

Even after importing the correct certificate, you might notice that the server still reports connectivity issues, which could be related to the certificate. In addition to the certificate being available for validation, it is important to remember some key points about certificate validation:

• The OpenSSL library used must validate a full certificate chain. This means that you cannot just install the end certificate, such as the one on the web server. If it was signed by a parent certificate, then the parent certificate is the one that must be installed. Though, if it's a true self-signed certificate, where it is signed by itself, and has no other parent, then install that certificate.
• Any required intermediate certificates must be present. Many CAs have a root certificate, and then one or more levels of intermediate, issuer, certificates, and then the actual server certificate. It's customary that the server be configured to serve both its own certificate as well as the intermediates, and that the client has the root to complete the chain. However, if the server is not configured to serve the intermediates, then the intermediates must also be installed in the certificate store.
• Certificates must be within their date range. That is, it must be after the valid from date and before the expiration date in the certificate.
• Certificates must use a valid Common Name (CN) or Subject Alternate Name (SAN) field and Phantom must be configured to use the resource by that name. Wildcard certificates will also work as expected. For example, you might have a server known as server.example.com at IP address 10.1.1.1. In order for the SSL/TLS connection to it to succeed, Splunk Phantom must be configured to use the full name, server.example.com. Using a short name of "server" or using the IP address 10.1.1.1 does not work.