API Key Management

Introduction

The Quality Clouds API layer provides a number of read-only and read-write functionalities, which are available for registered third party applications. This includes the Quality Clouds ServiceNow application, installed from the ServiceNow app store.

Authentication and authorisation for API requests are implemented via the use of API Keys, which are assigned to individual users.

Before version 9.6 of the Quality Clouds ServiceNow application, a shared OAuth token was used to authenticate the application against the Quality Clouds API Layer. However, for security reasons, all logins into Quality Clouds must support Multi-factor Authentication (MFA). The standard OAuth token request process is not compatible with Multi-Factor authentication, as it only supports sending a username / password pair when requesting the OAuth token.

For this reason, as of version 9.6 of the Quality Clouds ServiceNow application, each ServiceNow user must be assigned an individual Api Key in order to interact with the Quality Clouds API layer. This includes running LiveCheck on individual configuration elements and Update Sets.

This page describes the processes by which the generation and assignment of API keys can be automated in order to introduce as little friction as possible in the transition from the OAuth-based authentication system to individual API keys.

Upgrading from version 9.5 with existing API Keys:

If you are upgrading the Quality Clouds ServiceNow application from version 9.5 or below, some of your users may already have existing API keys, especially if you are using the workflow setting to approve write-off requests and update set peer review requests. In that case, you will have some users assigned to the "Quality Clouds Peer Reviewers" group, and these users will have valid API keys. 

In this case, the existing API keys can be used, but they will need to be encrypted to be compatible with version 9.6. To encrypt existing API keys, follow these steps in the ServiceNow instance where you are upgrading to version 9.6:

• • Locate the "QC - Encrypt values for existing API Keys" Scheduled Job, in the Quality Clouds scope.
  • Open the Job definition
  • Click the "Execute Now" UI Action

         

Once existing API Keys have been encrypted, the users to which those API keys are assigned will be able to keep using the application functionality as usual.

Note: Even after encrypting existing API keys, it is necessary to set up all your developers who have not been assigned an API key following the steps below. Only the step to create the "seed" keys may be omitted if the a  

Installing version 9.6 or upgrading from version 9.5 without existing API Keys:

If there are no existing API Keys in your instance, then it is necessary to create one or more "seed" keys. These are keys which are created in the Quality Clouds portal, and then pasted into the ServiceNow instance. This will then allow the user(s) who have created the seed keys for themselves to create new keys for other users directly from the ServiceNow application.

Note: In order to create a "seed" key, you need to have a valid user in the Quality Clouds portal with the required permissions to create API keys. These are granted by the "Customer Admin" profile.

To create the seed key(s), follow the below steps:

In the Quality Clouds Admin portal

• • Log into the QC Admin portal using Customer Admin
  • Navigate to Account - Api keys and click on Add

• • Click on Cloud and select ServiceNow
  • Click on Channel and select ServiceNow App
  • Click on Developer field and introduce your ServiceNow userId 
  • Click on Add new API Key. A new API Key will be generated, and you will have the option to copy it to the clipboard. You should do this, as you will not be able to retrieve the value of the key after it has been generated

In the ServiceNow instance

• • Log into the ServiceNow instance where you want to use the Quality Clouds app, select the menu "Quality Clouds → Configuration → API Keys" 
  • Click on  the UI Action "Enter my key" 
  • Paste the Api Key generated in the Admin Portal
    
    

• • Click Save 
    

Once the seed key has been inserted into the application, the user  who entered the key will be able to create additional API keys from the ServiceNow application, using the processes described below.

Managing API keys for a group of developers

In order to automatically generate and revoke API Keys as developers are onboarded and off boarded, it is possible to specify a group to hold all ServiceNow developers who need to use the application functionality (especially LiveCheck). As users are added and removed to this group, API keys will be automatically generated and revoked. For this to work, the user who is adding / removing the developers from this group must already have a valid API key. 

To specify this group, follow these steps:

• In ServiceNow, navigate to "Quality Clouds → Configuration → App configuration"
• In the "API Key Generation Group", search for and select the group whose members you want to generate API Keys for 

• In order to generate API Keys for the existing members of the group, click the "Generate API Keys" link UI Action at the bottom of the form
  
  
• This will generate API Keys for all existing members of the group (and any sub-groups, see Note below), without having to go through the process of removing and adding them to trigger the action on the insert event

Managing API keys for a individual developers

If you choose to not use a group in which to include all the ServiceNow users who need access to the Quality Clouds API, you can still manage the assignment of API keys for individual users on a case by case basis.

Note that for all of the below actions to work, the user performing them must already have a valid API key.

    1- To create a new API Key for a ServiceNow user: 

• In ServiceNow, navigate to "Quality Clouds → Configuration → API Keys" 
• Click on New to bring up the New API key form

•          In the form, look for and select the userid for which you want to generate the API key. 

• Click on "Get API Key". This will obtain an API key from the Quality Clouds server and store it in the ServiceNow instance.
• Click on "Save"

      2- To revoke an existing API Key:

• In ServiceNow, navigate to "Quality Clouds → Configuration → API Keys" 
• Open the record for the API key you want to revoke

• Click on the "Revoke API Key" UI action. The API Key will be revoked both in the Quality Clouds server and in the application.

Help! I lost all my API keys and now none of my developers can use LiveCheck or complete Update Sets!

If for any reason (an unintentional delete of the API keys table, or a clone from a Prod instance without the necessary exclusions), all the API keys have been deleted from your instance, none of your developers will be able to run LiveCheck, and it will not be possible to close udpate sets (if you have enabled Quality Gates). In this case, you can generate new keys for all the developers who previously had valid keys in your instance, by following these steps:

• Generate a first "seed" API key as described in the section "Installing 9.6 or upgrading from version 9.5 without existing API Keys:"
• In ServiceNow, navigate to "Quality Clouds → Configuration"
• Click on the UI Action link "Re-Setting API Keys"

This will query the Quality Clouds backend for existing active API keys for developers on this instance. These API keys can not be re-used, as the value of an API key is never exposed through the Quality Clouds API. Instead, all these keys will be revoked, and a brand new key will be assigned to each user who previously had a valid API key. This will restore the ability of the development team to use the application as before.

Note that the user who runs this process must have a valid API key, generated through the "seed" API key creation process.