Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

SAML Single Sign-on Authentication

Security Assertion Markup Language (SAML) is a framework for authentication and authorization between a service provider (SP) and an identity provider (IDP) where authentication is exchanged using digitally signed XML documents. The service provider agrees to trust the identity provider to authenticate users. In return, the identity provider generates an authentication assertion, which indicates that a user has been authenticated.

By using the SAML authentication feature, you can easily integrate JSA with your corporate identity server to provide single sign-on, and eliminate the need to maintain JSA local users. Users who are authenticated to your identity server can automatically authenticate to JSA. They don't need to remember separate passwords or type in credentials every time they access JSA.

JSA is fully compatible with SAML 2.0 web SSO profile as a service provider. It supports both SP and IDP initiated single sign-on and single logout.

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:

    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

When single sign on or single logout fails, make sure that the JSA SAML metadata that you uploaded to the Identity Provider matches the latest deployed metadata at https://<yourjsaserverhostname>/console/SAMLMetadata. Also, make sure that you uploaded the root CA, root CA CRL, intermediate CA, intermediate CA CRL files of your selected certificate to the right location of the IDP server's certificate stores. When the provided QRadar_SAML certificate is used, you can download these files at:

Note:

If you are using the provided QRadar_SAML certificate, the above steps are required after you restore JSA from a backup.

Account not authorized

Certain configuration issues can produce this error:

This account is not authorized to access JSA. Logout from your SAML identity provider and use an authorized account to login.

If you are using Local authorization, ensure that the NameID in the SAML assertion matches an existing JSA user name and that the user is deployed.

If you are using User Attribute authorization, ensure that the SAML assertion contains the configured role attribute and security profile attribute with values that match an existing deployed role and security profile in JSA. When using a role with Admin capabilities, the value of the security profile attribute must be Admin. If the assertion contains a tenant attribute in a multi-tenancy environment, ensure that the value of the attribute matches an existing tenant in JSA.

Log files

You can diagnose many other issues by using the Identity Provider server logs and the /var/log/ qradar.error log.

Restore system login for investigation

To investigate issues with SAML 2.0, you can restore JSA to use the default system login.

Copy the content of the /opt/qradar/conf/templates/login.conf into /opt/qradar/conf/ login.conf

Alternatively, edit the /opt/qradar/conf/login.conf file and change

ModuleClass=com.q1labs.uiframeworks.auth.configuration.SAMLLoginModule

to

ModuleClass=com.q1labs.uiframeworks.auth.configuration.LocalPasswordLoginConfiguration

Clear the browser cache and login as an Admin user. After you complete your investigation, change the attribute back to SAMLLoginModule and clear the browser cache again.

Unable to reach the JSA console after logging in with an identity provider

Ensure that the host name for the JSA console can be resolved by the local DNS server. Also, ensure that your computer can reach the JSA console by using the host name.

Login or logout failures on the IDP server

Check the IDP server logs to determine if the failures are caused by errors in the CRL revocation checks. If so, import the QRadar_SAML certificate CRLs to the IDP server, or make sure that the IDP server can reach the JSA console by using an HTTP connection.

Identity provider certificate is expired

When the certificate in the identity providers metadata file is expired, you cannot log in to JSA, and the following error appears in the /var/log/qradar.error file:

com.q1labs.uiframeworks.auth.saml.metadata.DefaultMetadataServiceImpl: [ERROR] NotAfter: <date> java.security.cert.CertificateExpiredException: NotAfter:

To resolve this issue, ask your identity provider to update the certificate in the metadata file, and then reconfigure SAML in JSA to use the new IDP metadata file.

QRadar_SAML certificate is expired

A JSA system notification is shown when the QRadar_SAML certificate is about to expire.

Before the certificate expires, you must renew it.

  1. On the Admin tab, click Authentication.

  2. Click Authentication Module Settings.

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

  4. Click Renew to renew the QRadar_SAML certificate.

  5. Click Save Authentication Module.

    The JSA SAML metadata file is automatically downloaded.

  6. Click the links in the tooltip to download the JSA root CA and intermediate CA certificate, as well as the CRL files.

  7. On the Admin tab, click Deploy Changes.

  8. Send the following files to your IDP server to deploy the changes.

    • JSA metadata file

    • JSA root CA certificate

    • JSA intermediate CA certificate

    • CRL files

Third-party certificate is expired

You do not have to use the QRadar_SAML certificate that is provided with JSA; you can use your own thirdparty certificate. When the certificate is about to expire, a JSAsystem notification is shown.

Before the third-party certificate expires, you must update the existing certificate or add a new certificate.

  1. Click Authentication Module Settings.

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

  3. Click Add or Update.

  4. Click Save Authentication Module.

    The JSA SAML metadata file is automatically downloaded.

  5. Click the links in the tooltip to download the JSA root CA and intermediate CA certificate, as well as the CRL files.

  6. On the Admin tab, click Deploy Changes.

  7. Send the following files to your IDP server to deploy the changes.

    • JSA metadata file

    • JSA root CA certificate

    • JSA intermediate CA certificate

    • CRL files

Related Documentation