SAML Single Sign-on Authentication

Configuring SAML Authentication

You can configure JSA to use the Security Assertion Markup Language (SAML) 2.0 single signon framework for user authentication and authorization.

To complete SAML configuration in JSA, you must generate an XML metadata file on your Identity Provider (SAML) server.

Follow these steps to configure SAML authentication on your JSA host. After you complete this task, you must configure the Identity Provider to work with JSA.

1. On the Admin tab, click Authentication.

2. Click Authentication Module Settings.

3. From the Authentication Module list, select SAML 2.0.

4. In the Identity Provider Configuration section, click Select Metadata File, browse to the XML metadata file that was created by your Identity Provider, and then click Open.

5. In the Service Provider Configuration section, type the Entity ID URL.

6. Select a NameID format:

   • Unspecified (default)

   • Persistent

   • Email Address

   • X509 Certificate Subject Name

   • Windows Domain Name

   • Kerberos

   Note:

   Use Unspecified unless your Identity Provider does not support it.

7. Select the Request Binding Protocol:

   • HTTP-POST

   • HTTP-Redirect

8. Select Yes for Request Signed Assertion, unless the device you are connecting to does not support signed assertions.

   CAUTION:

   Selecting No leads to unauthenticated communication with the SAML device and is not recommended because it allows an unauthenticated network-based attacker to access protected resources.

9. If you want the assertion that is returned by the Identity Provider to be encrypted using a JSA certificate, select Yes for Request Encrypted Assertion.

   Note:

   Enabling encryption requires Installing Unrestricted SDK JCE Policy Files.

10. If you want to sign the authentication request by using a JSA certificate, select Yes for Sign Authentication Request.

11. If you want to automatically log users out of the Identity Provider when they log out of JSA, select Yes for Enable Service Provider Initiated Single Logout.

    Note:

    This option is available only if supported by your Identity Provider.

12. Use one of the following methods to configure a certificate for signing and decrypting:

    Table 1: Configure a Certificate for Signing and Decrypting

    Option	Description
    Use the provided QRadar_SAML certificate	Use the links in the tooltip to download the Root CA, Root CA CRL, Intermediate CA, and Intermediate CA CRL files of the certificate, which should be uploaded to the trusted certificate store of the Identity Provider server.
    Add a new certificate	Click Add and follow the instructions in Importing a New Certificate for Signing and Decrypting to add a custom certificate.
    Renew or update an existing certificate	Click Renew to renew the QRadar_SAML certificate if it has expired or expires soon. Click Update to update a custom certificate that has expired or expires soon. These options appear based on which certificate you are using

13. Select one of the following methods to authorize users:

    Table 2: Configure a Certificate for Signing and Decrypting

    Option	Description
    Local	You must create local JSA users and configure their roles and security profiles in User Manager.
    User Attributes	JSA uses the attributes provided in SAML assertions to create local users automatically upon authentication requests. Roles and security profiles are assigned according to the value of the role attribute and the security profile attribute. These attributes must be provided in the assertions, and the roles and security profiles must already exist in JSA. Usernames, user roles and security profiles are case sensitive. Note: When using a role with Admin capabilities, the value of the security profile attribute must be Admin. Note: In a multi-tenancy environment, you must configure the Tenant attribute as well to assign users to tenants. If the tenant attribute is not provided, the user that is created is not assigned to any tenant.

14. Click Save Authentication Module.

    The JSA SAML metadata file is automatically downloaded.

15. On the Admin tab, click Deploy Changes.

    After you configure JSA, you must configure your Identity Provider using the saved XML metadata file.

    If you selected Local authorization, go to User Management to create local users. If you selected User Attributes, create roles, security profiles, and tenants as needed, then deploy.

Installing Unrestricted SDK JCE Policy Files

Use of encryption technology is controlled by United States law. JSA Solution Developer Kits (SDKs) include strong but limited jurisdiction policy files. To support encrypted SAML assertions, with JSA, you must first obtain the unlimited jurisdiction Java Cryptography Extension (JCE) policy files.

1. Download the unrestricted Java Cryptography Extension (JCE) policy files.

2. Unpack the compressed file.

   Select the following JAR files from the unrestricted folder:

   • local_policy.jar

   • US_export_policy.jar

3. Place the files in the following directory on your JSA Console:

   /opt/ibm/java-x86_64-80/jre/lib/security/

4. On the Admin tab, click Deploy Changes.

5. Click Advanced Settings > Restart Web Server.

Importing a New Certificate for Signing and Decrypting

The JSA SAML 2.0 feature has options to use an x509 certificate other than the provided QRadar_SAML certificate for signing and encryption.

1. For Certificate for signing and encryption, click Add.

2. In the Import New Certificate window, type a Friendly Name for the certificate.

3. Click Browse to select a Private Key File, and then click Open.

4. Click Browse to select a Certificate File, and then click Open.

5. If the certificate to upload has an Intermediate CA, click Browse to select the Intermediate CA File, and then click Open.

6. If the certificate's Root CA is not a common Root CA that is preinstalled with the operating system, click Browse to select the Root CA File, and then click Open.

7. Click Upload to upload the certificate.

Setting up SAML with Microsoft Active Directory Federation Services

After you configure SAML in JSA, you can configure your Identity Provider by using the XML metadata file that you created during that process. This example includes instructions for configuring Microsoft Active Directory Federation Services (AD FS) to communicate with JSA using the SAML 2.0 single sign-on framework.

To configure the AD FS server, you must first configure SAML in JSA. Then copy the JSA SAML XML metadata file you created during that process to a location accessible to the AD FS server.

1. On the AD FS Management console, select the Relying Party Trusts folder.

2. On the Actions sidebar, click Standard Relying Party Trust, and click Start. This opens the Add Relying Party Trust wizard.

3. On the Select Data Source window, select Import data about the relying party from a file, browse to the JSA SAML XML metadata file, and click Open.

4. Click Next.

5. Type a Display name and add any relevant Notes, then click Next.

6. Select an access control policy, and click Next.

7. Configure any additional options you require, and click Next.

8. Click Close.

9. In the Relying Party Trusts folder, select the new trust you created, then click Edit Claim Issuance Policy.

10. Click Add Rule.

11. Select Send LDAP Attributes as Claims from the Claim rule template menu, then click Next.

12. Type a Claim rule name, and select the Attribute store.

13. Select the attributes to be sent in the assertion, map to the appropriate Outgoing Claim Type, and click Finish.

14. Click Add Rule.

15. Select Transform an Incoming Claim from the Claim rule template menu, then click Next.

16. Configure the following options:

    • Claim rule name

    • Incoming claim type - use value UPN

    • Outgoing claim type as NameID

    • Outgoing NameID format

17. Select Pass through all claim values, then click Finish.

18. If you configured JSA to use the provided QRadar_SAML certificate for SAML, copy the previously downloaded Root CA, intermediate CA, and CRL files to a directory on the Windows server. Then open a command line window as administrator on Windows OS and type the following commands:

    content_copy zoom_out_map

    certutil -addstore -f ROOT <local_path>root-qradar-ca_ca
    certutil -addstore -f CA <local_path>QRadarSAML_ca.crt
    certutil -addstore -f ROOT <local_path>QRadarSAML_ca.crl
    certutil -addstore -f Root <local_path>root-qradar-ca_ca.crl

    The files are located in /opt/qradar/ca/www.

Troubleshooting SAML Authentication

Use the following information to troubleshoot errors and issues when using SAML 2.0 with JSA.

• Sign on or logout failure
• Account not authorized
• Log files
• Restore system login for investigation
• Unable to reach the JSA console after logging in with an identity provider
• Login or logout failures on the IDP server
• Identity provider certificate is expired
• QRadar_SAML certificate is expired
• Third-party certificate is expired

http://<yourjsaserverhostname>:9381/root-qradar-ca_ca
http://<yourjsaserverhostname>:9381/QRadarSAML_ca.crt
http://<yourjsaserverhostname>:9381/root-qradar-ca_ca.crl
http://<yourjsaserverhostname>:9381/QRadarSAML_ca.crl