How to utilize the IBM Cloud IAM Identity Services API to clean up inactive API keys and service IDs for improved account security.

If you have a good overview of all the service IDs and API keys in your IBM Cloud account, you can skip reading this blog post. If not, you are probably like us — sometimes wondering what resources, identities and API keys were created while working on a project. Creating is easy, but keeping tabs on resources and cleaning up is a chore, with no fun involved. So it was great to learn about some API functions that help to clean up an account and, thereby, enhance security.

In this blog post, we take a look at the IBM Cloud IAM (Identity and Access Management) Identity Services API. It provides functions to manage API keys and tokens, service IDs and trusted profiles, and it provides activity reports to identify inactive identities. We show how you can either create your own reports to identify unused API keys and identities or utilize the reporting feature (including the one integrated into the IBM Cloud console, as shown in the following screenshot):

IAM Identity Services API

IBM Cloud Identity and Access Management (IAM) authenticates (identifies) users who can access IBM Cloud and controls access to the resources. The IAM Identity Services API can be used to manage API keys and create access tokens. It also provides functions to manage service IDs and trusted profiles. Another function, which was added earlier this year, is the ability to trigger and retrieve activity reports for the account. The latter allows security administrators to identify inactive identities. Interestingly, you can build the same type of report yourself by utilizing other functions offered by the IAM Identity Services API:

• Get API keys: This function allows you to retrieve all API keys for a given service ID, user ID or for the entire account. To operate on the account level, you need administrator privileges. The function returns all the API keys in scope (including API keys for service IDs) but not the activity details.
• Get details of an API key: By requesting the activity data be included, the details show how many times the API key was used and when it was used last. This allows you to determine if the API key is actively used or can be deleted (see screenshot below).
• List service IDs: This function allows you to retrieve a list of all (accessible) service IDs. Similar to the API keys function, no activity data is included, but it can be requested for individual service IDs using the following function.
• Get details of a service ID: The details for a service ID include information on its API keys. With the optional parameter to request activity data, the usage count and (if available) the last authentication timestamp are included. Note that service IDs do not authenticate, but their API keys do.
• List trusted profiles: This function will give you a list of all trusted profiles in the account.
• Get a trusted profile: This allows you to get a trusted profile with the additional parameter to include activity data to check if it was recently used. Trusted profiles do not have any associated API keys, but compute identities or federated identities.
• It’s not part of the IAM Identity Services, but the User Management APIs are functions to list users in the account and to access individual user profile data. Again, it is possible to request activity data.

You can use the above functions to build your own report or reporting tool to investigate inactive or infrequently used identities. However, the IAM Identity Services API offers functions to trigger and retrieve an official report. You’ll need special privileges to work with them:

• Trigger a report: This kicks off the report generation. You can specify how many hours back the duration should be. By default, the report considers a duration of 720 hours. The request comes back with a report ID to be used with the retrieval function.
• Get activity report: When calling this function, either a unique report ID or just “latest” can be specified. The report includes activity details for users, API keys, service IDs and trusted profiles. If the requested report is not available yet, it returns a status of 204.

Note that all operations related to retrieving activity data are expensive and take longer. Hence, they should only be exercised when necessary:

Exercise the APIs

Now that we have a good overview of available API functions and how to retrieve activity data, we want to put that knowledge into practice. Assuming that only required users have access to your account, the focus should be on API keys to enhance account security. They are used both by users and service IDs. Moreover, API keys are generated for many purposes and could leak. Note that, by default, everyone in your account can create API keys. Our recommendation is to restrict it to those explicitly granted.

To check the authentication count and the timestamp of the last authentication for an API key, you’ll need the key’s ID and the right privilege. The key IDs can be obtained by getting all API keys, either all in the account or just for your own. Then, you’ll need to request the details, including the activity data and (optionally) the history. 

Instead of invoking the API functions individually and retrieving the results manually, we wrote a Python script: IAMkeys. It is available in the GitHub repository ibmcloud-iam-keys-identities. Typically, we try to obtain all JSON output and store it in a file, then use the tool jq for post-processing. See the README in the mentioned repository for sample commands and how to produce output in CSV (comma-separated values) format.

The following screenshot shows one of the retrieved API keys with history and activity data included. The API key was indirectly created by the account owner in April 2020 as part of a new Cloud Functions namespace. Because there is no authentication count and not a recorded timestamp for the last authentication, this API key should be investigated for deletion. If the Cloud Functions namespace no longer exists, the API key could be removed:

Report on inactive identities

Instead of generating your own report from the discussed APIs, you can use a recently introduced feature to identify inactive identities and simply create a report in the IBM Cloud console. It includes information about the users, service IDs, trusted profiles and API keys in the account. Each category is presented in its own browser tab. See the first screenshot at the top for parts of a report on API keys. For each listed identity, you have the option to manage or to remove it, but API keys can only be removed. The timestamp of when the report was generated is shown on top of the tabs. You can update the report by pressing the button:

Note that in the console, the report generation is always for 30 days (720 hours). Currently, you cannot modify the duration from there. In addition, only the latest available report is shown. The APIs to generate and retrieve the report offer more options as discussed earlier.

You can find a second Python script, IAMia, in the referenced GitHub repository. That script allows you to easily exercise the reporting functions. Moreover, it allows you to combine the new Activity Operations functions with the API functions from the previous section. As a result, it provides a more complete picture. Similar to the other script, it allows for output in either JSON or CSV format. See the repository for instructions.

Using the (CSV) data generated by the scripts, you can import the information into a spreadsheet or other data exploration tooling. Then, you can do the following:

1. Filter using the last_authn column and identify all API keys, users or trusted profiles that have never authenticated.
2. Identify a user with multiple API keys in your account; some of them are used and others are not. 
3. Identify users, trusted profiles or service IDs that have a high authentication count and investigate if that should be of concern. 

Conclusions

Having a good overview of all the service IDs and API keys in your IBM Cloud account adds to your security posture. In this blog post, we showed how the API functions of the IAM Identity Services can be utilized to generate insights on users, service IDs, trusted profiles and API keys in your account. They provide details about authentication activity and let you investigate if they are still active or could be removed for enhanced security.

We also discussed two Python scripts based on these API functions. The scripts allow you to produce the security-related data. The results can be post-processed with tools like jq (JSON format) or loaded into spreadsheets or databases (CSV format) for a deeper analysis. Check out the repository on GitHub for details on the scripts and to get started.

If you have feedback, suggestions, or questions about this post, please reach out to Henrik on Twitter (@data_henrik) or Dimitri and Henrik on LinkedIn.