Configuring single sign-on (SSO) through SAML authentication

The QRadar Suite Software initial user, and all other users that you are planning to add to QRadar Suite Software, must exist with an email address in your Verify identity provider instance. If you add a user with no email address, they might experience issues when they try to access QRadar Suite Software applications.

1. Create the IBMid identity provider in your Verify instance.
2. Go to Directory > Users & Groups > Users and click Add User.
3. In the Identity provider field, select IBMid.
4. Under Basic user profile, fill the Given name and Surname fields.
   Attention: The Given name and Surname fields are labeled as Optional, but they are actually required for QRadar Suite Software.
5. Under Basic user profile, enter your IBMid user account email address in the User name field.
6. Under User information, enter your IBMid user account email address in the Preferred e-mail field.
7. Optional: Complete the other fields.

Before you configure your connection, you need the credentials for IBM Cloud Pak foundational services, so that you can enable SAML as an identity provider in QRadar Suite Software and export its metadata.

The Red Hat OpenShift CLI client helps you develop, build, deploy, and run your applications on any Red Hat OpenShift or Kubernetes cluster. It also includes the administrative commands for managing a cluster under the adm subcommand.

1. Download Red Hat OpenShift CLI 4.12 or later from https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/stable-4.12/. The file to download is called openshift-client-<platform>-<version>.tar.gz.
2. Extract the binary file that you downloaded by typing the following command, where <oc_cli_archive_file> is the name of the archive file that you downloaded.

   tar -xf <oc_cli_archive_file>

3. Modify the permissions of the binary file by typing the following command, where <oc_cli_binary> is the name of the Red Hat OpenShift binary that you extracted from the archive.
4. Move the binary file to the /usr/local/bin directory by typing the following command.

   mv <oc_cli_binary> /usr/local/bin/oc

   Tip: If this command returns a No such file or directory or Not a directory error message, create the /usr/local/bin directory by typing the following command.

   sudo mkdir /usr/local/bin

5. Ensure that the Red Hat OpenShift CLI client is working by typing the following command.

   oc version

   Tip: MacOS users might see a message that this tool cannot be opened because it is from an unidentified developer. Close this message and go to System Preferences > Security & Privacy. On the General tab, click Open Anyway or Allow Anyway. Repeat the oc version command.

1. Download Cloud Pak CLI from https://github.com/IBM/cloud-pak-cli/releases.
2. Extract the binary file that you downloaded by typing the following command, where <archive_file> is the name of the archive file that you downloaded.

   tar -xf <archive_file>

3. Modify the permissions of the binary file by typing the following command, where <binary_file> is the name of the Cloud Pak binary file that you extracted from the archive.

   chmod 755 <binary_file>

4. Move the binary file to the /usr/local/bin directory by typing the following command.

   mv <binary_file> /usr/local/bin/cloudctl

   Tip: If this command returns a No such file or directory or Not a directory error message, create the /usr/local/bin directory by typing the following command.

   sudo mkdir /usr/local/bin

5. Ensure that Cloud Pak CLI is working by typing the following command.

   cloudctl version

   Tip: MacOS users might see a message that this tool cannot be opened because it is from an unidentified developer. Close this message and go to System Preferences > Security & Privacy. On the General tab, click Open Anyway or Allow Anyway. Repeat the cloudctl version command.

1. Log in to your Red Hat OpenShift Container Platform cluster by using either of the following commands, where <openshift_url> is the URL for your Red Hat OpenShift Container Platform environment.
   • Using a username and password.

     oc login <openshift_url> -u <username> -p <password>

   • Using a token.

     oc login --token=<token> --server=<openshift_url>

2. Set the $CP4S_NAMESPACE environment variable by typing the following command, where <cp4s_namespace> is the namespace where you are installing QRadar Suite Software.
   Important: If you installed QRadar Suite Software in all namespace mode, then set the <cp4s_namespace> value as openshift-operators.

   export CP4S_NAMESPACE=<cp4s_namespace>

3. Set the $FS_NAMESPACE environment variable to your foundational services namespace by typing the following command.

   export FS_NAMESPACE=$(oc get cm cp4s-config -o jsonpath="{.data.CSNamespace}" -n $CP4S_NAMESPACE)

4. To export the foundational services cluster URL, run the following command:

   export FOUNDATIONAL_SERVICES_URL=https://$(oc get route cp-console -n $FS_NAMESPACE -o jsonpath='{.spec.host}')

5. To retrieve the admin username of the foundational services cluster, run the following command.

   oc get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_username}' -n $FS_NAMESPACE | base64 -d | awk '{print $1}'

6. To retrieve the foundational services cluster admin password, run the following command:

   oc get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' -n $FS_NAMESPACE | base64 -d | awk '{print $1}'

7. Test logging in to the cluster using cloudctl by running the following command:

   cloudctl login -a $FOUNDATIONAL_SERVICES_URL -u <username> -p <password> -n $CP4S_NAMESPACE

Placeholder

1. Ensure you are logged in foundational services admin console, as described in step 7 of Retrieve login credentials for foundational services.
2. In foundational services, enable SAML and obtain the data from foundational services that you need to create an application in Verify.
   1. Enable SAML in foundational services by running the following command.

      cloudctl iam saml-enable

   2. Export and store the metadata file from foundational services by replacing the path variable and running the following command.

      cloudctl iam saml-export-metadata --file <path_to>/<file_name>.xml

3. Create two files called signer.pem and encryption.pem, and add the following two lines in each file.

   -----BEGIN CERTIFICATE-----
   -----END CERTIFICATE-----

4. From the XML file that you obtained in step 2b, extract the certificate base64 text that Verify requires to connect with foundational services.

   Place the certificate text between the lines in each of the files that you created.

   The following XML is an example of the contents of the file that you obtain in step 2b. To locate the certificate text that Verify requires, search for "signing" and "encryption".

   <?xml version="1.0" encoding="UTF-8"?>
   <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://cp-console.itzroks-1200007eeb-je36ud-6ccd7f378ae819553d37d5f2ee142bd6-0000.us-south.containers.appdomain.cloud/ibm/saml20/defaultSP">
     <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
       <md:KeyDescriptor use="signing">
         <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
           <ds:X509Data>
             <ds:X509Certificate>MIIDljCCAn6gAwIBAgIQZpVrZ6ic+kWOsu16

   For example, from the sample file, copy and paste the text located between the signing certificate tags <md:KeyDescriptor use="signing"> into the signer.pem file.

   MIIDljCCAn6gAwIBAgIQZpVrZ6ic+kWOsu16PrSwNzANBgkqhkiG9w0BAQsFADAcMRowGAYDVQQD
   ExFjcy1jYS1jZXJ0aWZpY2F0ZTAeFw0yMjA3MTEyMTAwNTBaFw0yMzA3MTEyMTAwNTBaMB0xGzAZ
   BgNVBAMTEm1hbmFnZW1lbnQtaW5ncmVzczCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
   AMr8q6HaI7Qk4/2bC8m3HaYvAGGWn4S+ZG/kpMLzUMSY3P/wc+71d9Cgv8yUxqEPM0CpCDEIzDBZ
   awIhdC6+0znHHLUHqlivphGsCg8oMrp/cllYqaB8Y8v4Zn51Z7j7mXDIiIYw6MFR7xkRnANA9ssE
   biJ5JBy+r34ZQdoe5Rl3HIzSJim1BjyaI8LprazUTVbIjP+7WVr+Iw6vEe94XQgsrg

In this task you will create an application in Verify, provide this application with the certificates metadata retrieved directly from foundational services, and then obtain the Verify Use unique ID metadata that is required to further complete the SAML SSO configurations in foundational services.

1. Upload the certificates that you obtained in step 2 to Verify: Go to Security > Certificates and upload the signer and encryption certificate files by using the Add signer certificate option. For more information, see Managing certificates.
2. Create the emaillowercase attribute.
   1. Go to Directory > Attributes, and click Add attribute to create the email lower case and username lower case custom attributes if they don't already exist.
   2. Under the Type and Availability section, select Custom attribute, select the Single sign-on (SSO), and then click Next.
   3. Type the name and description for your custom attribute, for example emaillowercase and Transformation for SAML assertion with email lowercase.
   4. Under the Source and value section, complete the following fields.

      Field	Value
      Attribute identifer	emaillowercase
      Data type	String
      Identity provider	IBMid
      Attribute name from the identity provide	email
      Default value	Leave it blank
      Apply transformation:	Lowercase

   5. In the Constraints field, keep all values to default.
      Important: The user name and preferred e-mail used in Onboarding users to a Verify instance must be in lowercase. If you onboard users with mixed casing, you must also use the exact casing in the SAML login assertion. For example, in the application configuration Sign-on > SAML subject > Name Identifier of the table in Step 3, you should use Email instead of emaillowercase.
3. To create the application, follow the procedure in the Verify documentation. Go to Applications > Applications, click Add Application, and then select Custom Application to configure SAML sign-on. For more information, see Creating a Verify Application.
   • For the General tabs, fill the name, description and company information of your application. While the Description field might show as optional, but it is actually a required field for Verify to complete the exporting process. Enter a friendly name and description for your app.
   • For the Sign-on tabs, provide the information that is described in the following table.
   • You can leave all the other fields as default, including other tabs of the application. After reviewing the application Sign-on configuration with the table, click Save.

   Tab	Field	Value
   Sign-on	Sign-on method	Select SAML 2.0.
   Sign-on	Use metadata	Ensure that the checkbox is not checked.
   Sign-on	Provider ID	Enter the foundational services URL that you copied from the metadata.xml file that you obtained in step 2b in Configuring the SAML SSO connection in foundational services.
   Sign-on	Use unique ID	Ensure that the checkbox is checked.
   Sign-on	Assertion consumer service URL (HTTP-POST)	Enter the same Provider ID URL from the metadata.xml file, followed by /acs.
   Sign-on	Service provider SSO URL	Enter the QRadar Suite Software route URL, also known as domain.
   Sign-on > Single Logout Settings	Single logout URL (HTTPPOST)	Enter the same Provider ID URL from the metadata.xml file, followed by /acs.
   Sign-on > Signature options	Sign Authentication Response	Ensure that the checkbox is checked.
   Sign-on > Signature options	Signature Algorithm	Ensure that the RSA-SHA256 checkbox is selected.
   Sign-on > Signature options	Validate SAML request signature	Ensure that the checkbox is not checked.
   Sign-on > Signature options	Validate SAML request logout signature	Ensure that the checkbox is checked.
   Sign-on > Signature options	Validate SAML response logout signature	Ensure that the checkbox is checked.
   Sign-on > Signature options	Service Provider signer certificate	Select the certificate that you uploaded in step 1a in the signer.pem file.
   Sign-on > Encryption options	Encrypt assertion	Ensure that the checkbox is checked.
   Sign-on > Encryption options	SAML assertion encryption algorithm	Select AES-256.
   Sign-on > Encryption options	Encryption key transport algorithm	Select RSA-OAEP.
   Sign-on > Encryption options	Service provider encryption certificate	Select the certificate that you uploaded in step 1a in the encrypt.pem file.
   Sign-on > SAML subject	NameID Format	From the list, select Email
   Sign-on > SAML subject	Name Identifier	From the list, select emaillowercase, the attribute you created in step 2.
   Sign-on > Attribute mappings	Send all known user attributes in the SAML assertion	Ensure that the checkbox is checked.
   Sign-on > Attribute mappings	Attribute name Attribute Source Attribute name Attribute Source	From the list, select name. From the list, select name. From the list, select email. From the list, select email.

   Tip:

   • For more information about retrieving the QRadar Suite Software URL, see Logging in to QRadar Suite Software as initial user. For the Service provider SSO URL field value, the protocol prefix https:// must be added to the QRadar Suite Software route URL.
   • The Entitlement tab is available in the application configuration only after you save the application. This tab is not available initially when you are creating the application.
4. Click the Entitlements tab, which is only available after you initially save the application. Select Access Type with Automatic access for all users and groups.
5. After the application is created in your Verify instance, export from Verify the federation metadata of the identity provider.
   1. Go to Applications and find your application name in the list.
   2. Click the settings icon, and then click the Sign-on tab.
   3. Scroll right to the second column and down to step 4.
   4. Download the metadata XML file by clicking the URL for Use unique ID.
6. Obtain a client_id and client_secret from your Verify instance.
   1. If an API Client does not exist, create one. For more information, see API Access.
   2. Go to Security > API Access and click the edit icon for the API client.
   3. Under API credentials, copy and store the Client ID and Client secret values.

To complete the SAML SSO configuration in foundational services, register the Verify instance to connect with foundational services

1. Upload the Verify metadata XML file that you downloaded in step 3 by replacing the path variable with your XML file path, and then run the following command.

   cloudctl iam saml-upload-metadata --file <path_to>/<file_name>

2. Assign the values for USER, PASSWORD, and FOUNDATIONAL_SERVICES_URL by running the following command in your cluster.

   USER=$(oc get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_username}' -n $FS_NAMESPACE | base64 -d | awk '{print $1}') &&
   PASSWORD=$(oc get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' -n $FS_NAMESPACE | base64 -d | awk '{print $1}') &&
   FOUNDATIONAL_SERVICES_URL=https://$(oc get route cp-console -n $FS_NAMESPACE -o jsonpath='{.spec.host}')

3. Obtain a foundational services access token by running the following curl request with your QRadar Suite Software cluster URL.

   ACCESS_TOKEN=$(curl -s -k -X POST \
   --url "${FOUNDATIONAL_SERVICES_URL}/idprovider/v1/auth/identitytoken" \
   --header "Content-Type: application/x-www-form-urlencoded" \
   --data-urlencode "grant_type=password" \
   --data-urlencode "username=${USER}" \
   --data-urlencode "password=${PASSWORD}" \
   --data-urlencode "scope=openid" \
   | jq -r .access_token)

4. Edit the following command to replace the variables with values and run the command to assign those values.
   1. Replace <verify_instance_name> and <verify_instance_description> to identify the Verify instance that you are connecting to foundational services.
   2. Replace the variables for <verify_instance_url>, <verify_client_id>, and <verify_client_secret> with the values that you obtained from your Verify instance in step 3.

   Tip: If a variable value contains a space, use double quotation marks to enclose the value.

   VERIFY_INSTANCE_URL=<verify_instance_url> &&
   VERIFY_INSTANCE_NAME=<verify_instance_name> &&
   VERIFY_INSTANCE_DESCRIPTION=<verify_instance_description> &&
   VERIFY_CLIENT_ID=<verify_client_id> &&
   VERIFY_CLIENT_SECRET=<verify_client_secret>

5. To register the Verify instance with foundational services, run the following curl request.

   curl -k -X POST "${FOUNDATIONAL_SERVICES_URL}/idprovider/v2/auth/idsource/registration" \
       --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header 'Content-Type: application/json' \
       --data @<(cat << EOF
       { 
           "name": "${VERIFY_INSTANCE_NAME}", 
           "description": "${VERIFY_INSTANCE_DESCRIPTION}", 
           "protocol": "saml", 
           "idp_type": "isv", 
           "scim": "yes", 
           "scim_base_path": "${VERIFY_INSTANCE_URL}/v2.0/", 
           "token_attribute_mappings": { 
               "uid":"uid", 
               "first_name":"given_name", 
               "last_name":"family_name",  
               "groups": "groupIds",  
               "email":"email" 
           }, 
           "jit": "no", 
           "scim_attribute_mappings":{ 
               "user":{ 
                   "email": "email", 
                   "principalName":"userName", 
                   "givenName":"name.givenName", 
                   "firstName":"first_name", 
                   "middleName":"name.middleName", 
                   "familyName":"name.familyName", 
                   "formatted":"name.formatted", 
                   "displayName": "name.formatted" 
               }, 
               "group":{ 
                   "principalName":"displayName", 
                   "created":"meta.created", 
                   "lastModified":"meta.lastModified" 
               } 
           }, 
           "config": { 
               "grant_type": "client_credentials", 
               "token_url": "${VERIFY_INSTANCE_URL}/v1.0/endpoint/default/token", 
               "client_id": "${VERIFY_CLIENT_ID}", 
               "client_secret":"${VERIFY_CLIENT_SECRET}" 
           }, 
           "status": "enabled" 
       }
   EOF
   )

   To confirm the outcome, expect to see the following successful registration message.

   {"status":"Client Successfully registered."}