Configuring single sign-on (SSO) through SAML authentication

Placeholder

1. Required: 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. Required: 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.

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 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-secret-default -o json | jq -r .data.admin | base64 -d) &&
   PASSWORD=$(oc get secret platform-secret-default -o json | jq -r .data.key | base64 -d) &&
   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."}