Configuring a client certificate for certificate-based authentication

To configure a client certificate in Azure DevOps

1. Import your client certificate into Azure DevOps:
   1. On the Azure DevOps dashboard, click Pipelines to expand it.
   2. Click Library.
   3. On the Secure files tab, click + Secure file.
   4. In the Upload file dialog box, drag and drop the client certificate file, or click  Browse to select a client certificate file and click OK.
2. Define a variable for the client certificate password:
   1. On the Azure DevOps dashboard, click Pipelines to expand it.
   2. Click Library.
   3. Select your Variable group from the list, and click +Add.
   4. Enter the name for the password variable, that is, CERT_PASS. Use all caps to distinguish from actual value in the config YAML file.
   5. Enter the value for the password, and select the lock icon to change this variable type to secret.
   6. Click Save.
3. Edit the config YAML file in the authentication step:
   1. For authenticationType, enter certBased.

   2. For certificatePath and certificatePassword, enter the variable names that you created in step

      Example

      authenticationType: certBased    
      certificatePath: CERT_PATH_AUTH
      certificatePassword: CERT_PASS_AUTH
   3. Save the config YAML file.
4. Edit the pipeline YAML file to use your client certificate:
   1. Add the task, enter DownloadSecureFile@1.
   2. Enter a value for the displayName enclosed in single quotation marks.

   3. For the secureFile, enter the name of the PKCS #12 client certificate name (enclosed in single quotation marks) used to run the pipeline:

      Example

      steps:
      - task: DownloadSecureFile@1
        name: clientCertificate
        displayName: 'Download client certificate'
        inputs:
          secureFile: '<clientCertificateName>.p12'

      Important

      BMC AMI SQL Assurance supports PKCS #12 client certificates with DER encoded in binary format only.

   4. Add the Linux sed commands to replace the variable values for the new certificate variables:

      Example

      sed -i "s|CERT_PATH_AUTH|$(clientCertificate.secureFilePath)|" Test_config.yml
      sed -i "s/CERT_PASS_AUTH/$(cert_pass)/" Test_config.yml
   5. Save the pipeline.

To configure a client certificate in GitHub Actions

There are several methods to add a client certificate for GitHub Actions. We suggest the following procedures for using a password-protected zip file for your client certificate with certificate-based authentication:

1. Create a password-protected client certificate zip file in your Linux VM by running the following zip command:

   zip -P <password> <target-file> <source-file>

   Replace the variables with a zip file password, target zip file name, and PKCS #12 client certificate source file name.

   Important

   • The zip and unzip utility must be available in your Linux VM.
   • BMC AMI SQL Assurance supports PKCS #12 client certificates with DER encoded in binary format only.
2. Upload the zipped client certificate to your GitHub repository:
   1. On the GitHub repository Code tab, navigate to your designated directory to upload the zipped client certificate
   2. Click Add file > Upload files.
   3. On the Upload page, drag and drop the zipped client certificate, or click choose your files  to select the zipped client certificate and click Commit changes.
3. Define your repository secret and variables for the client certificate:
   1. On the GitHub repository Settings tab, to expand the list, click Secrets and variables.
   2. Click Actions.

   3. Define the secret password for the zipped client certificate in the Secrets tab, and click New repository secret.

      Important

      Perform this step only if you are using a password-protected zip file for your client certificate.

      1. Enter the secret name for the password for the zipped client certificate, that is, ZIP_CERT_PASS
      2. Enter the secret value for the zipped client certificate password.
      3. Click Add secret.
   4. Define the secret password for the client certificate in the Secrets tab, and click New repository secret.
      1. Enter the secret name for the client certificate password, that is, CERT_PASS_AUTH.
      2. Enter the secret value for the client certificate password.
      3. Click Add secret.
   5. Define the repository variable for the client certificate path in the Variables tab, and select New repository variable.
      1. Enter the variable name for the client certificate path, that is, CERT_PATH.
      2. Enter the variable value for the client certificate path.
      3. Click Add variable.
4. Edit the config YAML file in the Authentication step:
   1. For authenticationType, enter certBased. 

   2. For certificatePath and certificatePassword, enter the values that you entered in step 3.

      Example

       authenticationType: certBased
       certificatePath: CERT_PATH_AUTH
       certificatePassword: CERT_PASS_AUTH 
   3. Save the config YAML file.

5. Edit the workflow YAML file as follows:

   1. Insert the unzip step below to unzip the password-protected client certificate after the repository checkout step:

      Important

      Perform this step only if you are using a password-protected zip file for your client certificate.

      1. Specify your password for the zipped client certificate and the directory path where the unzipped client certificate will reside.
      2. (Optional) Specify the -d unzipPath (for example, -d /opt/secret) so that the client certificate is removed after the workflow is complete . If you do not specify -d unzipPath , the client certificate is saved to the default workspace, but it is not deleted at the end of the workflow run.

       - name: unzip client certificate
      run: |
        unzip -P "${{secrets.zip_cert_pass}}" <zipClientCertName>.zip -d <unzipPath> 

   2. Define the Linux sed command to replace the client certificate variable and secret client certificate password defined in GitHub Actions:

      # sed -i "s|CERT_PATH_AUTH|/opt/secret/<clientCertificateName>.p12|" Test_config.yml
      # sed -i "s/CERT_PASS_AUTH/${{secrets.cert_pass}}/" Test_config.yml
   3. Save the workflow YAML file.

   Variable	Description
   zip_cert_pass	Secret variable defined with the password for the zipped client certificate
   zipClientCertName	Name of the zipped client certificate
   unzipPath	Directory path for the unzipped client certificate
   CERT_PATH_AUTH	Variable for the directory path and client certificate file
   clientCertificateName	PKCS #12 client certificate used to run pipeline or workflow BMC AMI SQL Assurance supports PKCS #12 client certificate with DER encoded in binary format only
   CERT_PASS_AUTH	Secret password for the client certificate

To configure a client certificate in GitLab CI/CD

(BMC.DB2.SPE2501)

There are several methods to add a client certificate to GitLab CI/CD. We suggest the following procedures for using a password-protected zip file for your client certificate with certificate-based authentication:

1. Create a password-protected client certificate zip file in your Linux VM by running the following zip command:

   zip -P <password> <target-file> <source-file>

   Replace the variables with a zip file password, target zip file name, and PKCS #12 client certificate source file name.

   Important

   • The zip and unzip utility must be available in your Linux VM.
   • BMC AMI SQL Assurance for Db2 supports PKCS #12 client certificates with DER encoded in binary format only.
2. Upload the zipped client certificate to your GitLab Project repository:
   1. From the GitLab Project Code menu, select Repository.
   2. Select your branch to upload the zipped client certificate.
   3. Click , and then select Upload file.
   4. On the Upload new file page, drag or click the upload link to select the zipped client certificate.
   5. Keep the default commit message or enter a message of your choice.
   6. Specify the target branch where the zipped client certificate should reside.
   7. Click Upload file.
3. Define your repository variables for the client certificate:
   1. From the GitLab Project Settings menu, select CI/CD.
   2. Expand Variables.
   3. Click Add variable to define the following variables:

      1. Zipped client certificate password:

         Important

         Perform this step only if you are using a password-protected zip file for your client certificate.

         • Type: Variable (default)
         • Environment: All (default)
         • Visibility: Masked & Hidden
         • Flags: None
         • Description: Specify as desired.
         • Key: ZIP_CERT_PASS
         • Value: Enter the variable value for the zipped client certificate password.
         • Click Add variable.
      2. Client certificate password:
         • Type: Variable (default)
         • Environment: All (default)
         • Visibility: Masked & Hidden
         • Flags: Expand variable reference
         • Description: Specify as desired.
         • Key: CERT_PASS_AUTH
         • Value: Enter the value for the client certificate password.
         • Click Add variable.
      3. Client certificate path:
         • Type: Variable (default)
         • Environment: All (default)
         • Visibility: Visible
         • Flags: Expand variable reference
         • Description: Specify as desired.
         • Key: CERT_PATH_AUTH
         • Value: Enter the directory path and client certificate file name where the client certificate will reside.
         • Click Add variable.
4. Edit the config YAML file in the Authentication step:
   1. For authenticationType, enter certBased. 

   2. For certificatePath and certificatePassword, enter the variables that you defined in step 3.

      authenticationType: certBased
      certificatePath: CERT_PATH_AUTH
      certificatePassword: CERT_PASS_AUTH 
   3. Save the config YAML file.
5. Edit the pipeline YAML file as follows:

   1. Insert the following unzip step, to unzip the password-protected client certificate at the start of the job’s script:

      Important

      Perform this step only if you are using a password-protected zip file for your client certificate.

      1. Specify your password for the zipped client certificate and the directory path where the unzipped client certificate will reside.

      2.  (Optional) Specify the -d unzipPath (for example, -d /opt/secret) so that the client certificate is removed after the pipeline is complete. If you do not specify -d unzipPath, the client certificate is saved to the default workspace, but it is not deleted at the end of the pipeline run.

         - echo “Unzip client certificate”
         - unzip -P "$<zip_cert_pass>” <zipClientCertName>.zip -d <unzipPath>

   2. Define the Linux sed command to replace the client certificate and client certificate password variables defined in GitLab CI/CD:

      - sed -i "s|CERT_PATH_AUTH|$CERT_PATH_AUTH|" Test_config.yml
      - sed -i "s/CERT_PASS_AUTH/$CERT_PASS_AUTH/" Test_config.yml
   3. Save the pipeline YAML file.