IBM Cloud Docs

Auditing events for IAM

Auditing events for IAM

As a security officer, auditor, or manager, you can use the IBM Cloud Activity Tracker service to track how users and applications interact with the IBM Cloud® Identity and Access Management (IAM) service in IBM Cloud.

IAM enables you to securely authenticate users for both platform services and control access to resources consistently across IBM Cloud. Learn more.

The IBM Cloud Activity Tracker service records user-initiated activities that change the state of a service in IBM Cloud. To get started monitoring your user's actions, see IBM Cloud Activity Tracker. An initiator can be a user, a service, or an application.

Access groups events

Account events

The following table lists the actions that generate an event:

Events that are generated for access groups
Action	Description
`iam-groups.account-settings.read`	An event is generated when an initiator views the account settings for the access groups service.
`iam-groups.account-settings.update`	An event is generated when an initiator updates their account settings for the access groups service.

Access groups events

The following table lists the actions that generate an event:

Events that are generated for access groups
Action	Description
`iam-groups.group.create`	An event is generated when an initiator creates an access group.
`iam-groups.group.read`	An event is generated when an initiator views an access group.
`iam-groups.group.update`	An event is generated when an initiator updates a group name or a description.
`iam-groups.group.delete`	An event is generated when an initiator deletes an access group.
`iam-groups.groups.list`	An event is generated when an initiator views the access groups.

Members events

The following table lists the actions that generate an event:

Events that are generated for access groups
Action	Description
`iam-groups.federated-member.add`	An event is generated when an initiator logs in to the account and gains federated membership to an access group.
`iam-groups.member.add`	An event is generated when an initiator adds a member to an access group.
`iam-groups.member.delete`	An event is generated when an initiator removes a member from an access group.
`iam-groups.member.read`	An event is generated when an initiator views a member's membership.
`iam-groups.members.list`	An event is generated when an initiator views the members for an access group.

Rules events

The following table lists the actions that generate an event:

Events that are generated for access groups
Action	Description
`iam-groups.rule.read`	An event is generated when an initiator views a rule in an access group.
`iam-groups.rule.create`	An event is generated when an initiator adds a rule to an access group.
`iam-groups.rule.update`	An event is generated when an initiator modifies the rule name.
`iam-groups.rule.delete`	An event is generated when an initiator deletes a rule from an access group.
`iam-groups.rules.list`	An event is generated when an initiator views the rules for an access group.

Trusted profiles events

The following table lists the actions that generate an event:

Events that are generated for trusted profiles
Action	Description
`iam-identity.account-profile.create`	An event is generated when an initiator creates a trusted profile.
`iam-identity.account-profile.update`	An event is generated when an initiator updates a trusted profile.
`iam-identity.account-profile.delete`	An event is generated when an initiator deletes a trusted profile.

Policy events

The following table lists the actions that generate an event:

Events that are generated for policy actions
Action	Description
`iam-am.policy.create`	An event is generated when an initiator adds a policy to a user or access group.
`iam-am.policy.update`	An event is generated when an initiator modifies permissions to a policy of a user or access group.
`iam-am.policy.delete`	An event is generated when an initiator deletes a policy that is assigned to a user or access group.

Service ID events

The following table lists the actions that generate an event:

Events that are generated for service IDs actions
Action	Description
`iam-identity.account-serviceid.create`	An event is generated when an initiator creates a service ID.
`iam-identity.account-serviceid.update`	An event is generated when an initiator renames a service ID or modifies its description.
`iam-identity.account-serviceid.delete`	An event is generated when an initiator deletes a service ID.

API key events

The following table lists the actions that generate an event:

Events that are generated for API keys actions
Action	Description
`iam-identity.user-apikey.create`	An event is generated when an initiator creates an API key.
`iam-identity.user-apikey.update`	An event is generated when an initiator renames an API key or modifies its description.
`iam-identity.user-apikey.delete`	An event is generated when an initiator deletes an API key.
`iam-identity.serviceid-apikey.create`	An event is generated when an initiator creates an API key for a service ID.
`iam-identity.serviceid-apikey.delete`	An event is generated when an initiator deletes an API key for a service ID.
`iam-identity.serviceid-apikey.update`	An event is generated when an initiator renames an API key for a service ID or modifies its description.

Login and logout events

The following table lists the actions that generate an event:

Events that are generated for user login and logout actions
Action	Description
`iam-identity.user-apikey.login`	An event is generated when a user logs in to the IBM Cloud by using an API key.
`iam-identity.serviceid-apikey.login`	An event is generated when an initiator logs in to the IBM Cloud by using an API key that is associated with a service ID.
`iam-identity.user-identitycookie.login`	This is an event that is generated when an initiator requests an identity cookie to run an action.
`iam-identity.user-refreshtoken.login`	This is an event that is generated when the initiator logs in to IBM Cloud, or when an initiator that is already logged in requests a new refresh token to run an action.
`iam-identity.user-passcode.login` `iam-identity.trustedprofile-apikey.login`	This is an event that is generated when the initiator logs in to IBM Cloud by applying a trusted profile, or when an initiator that is already logged in by applying a trusted profile requests a new refresh token to run an action.
`iam-identity.user.logout`	This is an event that is generated when the initiator logs out of the IBM Cloud.

Viewing events

Events are available in the Frankfurt (eu-de) region.

To view these events, you must provision an instance of the IBM Cloud Activity Tracker service in the Frankfurt (eu-de) region. Then, you must open the IBM Cloud Activity Tracker UI.

Analyzing events

Login events

In the IBM Cloud, an administrator, or a user that has the correct access in your account, has different options to manage a user's login settings. For example, an administrator can order external authentication options, enable a one-time passcode to be used during login, enable the use of security questions at login, or set a password expiration time period. For more information, see Types of multifactor authentication.

A user can log in by using a user ID and password.
A federated user that uses a corporate or enterprise single sign-on ID can log in to IBM Cloud from the command-line interface (CLI) by using either a one-time passcode or an API key. For more information, see Logging in with a federated ID.
A user can log in by using an API key.
A federated user that uses a corporate or enterprise single sign-on ID can log in to IBM Cloud by applying a trusted profile.

The following fields include additional information:

The initiator.name includes information about the user that logs in to the account.
The X-Global-Transaction-Id includes an ID that you can use when you open a support ticket if you need to get more information.

Log in from the IBM Cloud UI

When a user logs in from the IBM Cloud UI, you get an event in the account with action iam-identity.user-refreshtoken.login.

The following field includes additional information:

In requestData, the client_id field is set to HOP55v1CCT. This value indicates a UI request.

Log in with a federated ID from the IBM Cloud CLI by using a one-time passcode or an API key

When a user logs in from the IBM Cloud CLI by using a one-time passcode, you get an event in the account with action iam-identity.user-refreshtoken.login.

When a user logs in from the IBM Cloud CLI by using an API key, you get an event in the account with action iam-identity.user-apikey.login.

The following field includes additional information:

In requestData, the client_id field is set to bx. This value indicates a CLI request.

Log in with a federated ID by using trusted profiles

When a user logs in with a federated ID by using trusted profiles, you get an event in the account with action iam-identity.trustedprofile-apikey.login.

Failed log in actions

When a user logs in to the IBM Cloud, the user ID (IBMid) and credentiasls are validated first. At this point, the user has not selected an account. Notice that a user can belong to multiple accounts.

After the user ID is authenticated successfully in the IBM Cloud, the user can choose an account. It is at this point in the process that an account is associated to the log in request, and an event with action iam-identity.user-refreshtoken.login, or iam-identity.user-apikey.login is generated in your account.

In Activity Tracker, you can see events that are associated to your account. Failed log in actions do not generate an event that you can monitor in your account.

Logout events

When a user logs out of the IBM Cloud, the iam-identity.user.logout event is generated.

Update an account service ID

A service ID identifies a service or application similar to how a user ID identifies a user. Learn more.

When an action to update a service ID is requested, you get an event in the account with action iam-identity.account-serviceid.update.

The following fields include additional information:

The initiator.name field includes information about who has requested to update the service ID.
The target.name field includes information about the service ID that is changed.
The initiator.host.agent field indicates if the request comes from the UI or the CLI. When the field is set to Not Set, the request originates in the UI. When the field is set to IBM Cloud CLI, the request originates at the command line.

Lock and unlock a service ID

The following field includes additional information:

In requestData, the lock field is set to true when the service ID is locked, and to false when it is unlocked.

Add or modify a description

When a request to change a description generates an event, the following fields include information that can help you determine this action:

In requestData, the lock field is set to false.
In requestData, the prev_instance_name field and the instance_name field are set to the same value.

Change the name of a service ID

The following fields include additional information:

In requestData, the lock field is set to false.
In requestData, the instance_name field includes the new name of the API key.
In requestData, the prev_instance_name field includes the name of the API key before it was changed.

Update a user API key or a service ID API key

When an action to update an API key is requested, you get an event in the account with one of the following actions:

To update a user API key, the action is iam-identity.user-apikey.update.
To update a service ID API key, the action is iam-identity.account-serviceid.update.

The following fields include additional information:

The initiator.name field includes information about who has requested to update the API key.
The target.name field includes information about the API key that is changed.
The initiator.host.agent field indicates if the request comes from the UI or the CLI. When the field is set to Not Set, the request originates in the UI. When the field is set to IBM Cloud CLI, the request originates at the command line.

Lock and unlock a service ID

The following field includes additional information:

In requestData, the lock field is set to true when the API key is locked, and to false when it is unlocked.

Add or modify a description

When a request to change a description generates an event, the following fields include information that can help you determine this action:

In requestData, the lock field is set to false.
In requestData, the prev_instance_name field and the instance_name field are set to the same value.

Change the name of a service ID

The following fields include additional information:

In requestData, the lock field is set to false.
In requestData, the instance_name field includes the new name of the API key.
In requestData, the prev_instance_name field includes the name of the API key before it was changed.

Analyzing events that fail

Initiator not authorized. Request to update an API key or service ID fails

For example, when a user logs into your account using an API key, the user is authenticated to access your account. However, this API key may not have permissions to run actions to modify API keys or service IDs in the account. When this happens, you get one of the following messages:

IAM Identity Service: update user-apikey APIKeyName -failure
IAM Identity Service: update account-serviceid ServiceIDName -failure

To look for information about the user that has requested a change to an API key or to a service ID, look at the initiator fields in the event.

When a user does not have permissions to run this action in your account, you get a failure event:

The initiator.name field is empty. This information is not available at the time the event is generated.
The user ID has been authenticated in your IBM Cloud account.
The action targets your account.
The user ID is not authorized to run this action in your account.

To find out the user who has tried to modify an API key or a service ID, complete the following steps:

Copy the value of the initiator.id. This field includes the ID of the user that is trying to run this action in your account.
Get the email address that is associated with the user. To complete this step, you must have administrator permissions in the account. Run the following command:
```
ibmcloud iam users --output json | grep -A 1 InitiatorID
```
Where InitiatorID is the value of the field initiator.id, and has the format IBMid-XXXXXXXXXX.

The output of this command returns 2 fields. The ibmUniqueId field shows the ID of the user that matched the event initiator.name field. The email field shows the email address associated with that ID.

To get the API key on which the action has been requested and failed, see the field prev_instance_name in requestData.

Resource is locked. Request to update Service ID or API key fails

When a service ID or an API key are locked, you cannot change any of its attributes. The event that is generated has an outcome of failure.

Depending on the resource type, you can get any of the following messages:

Service ID: The message that you get says IAM Identity Service: update account-serviceid ServiceIDName -failure where ServiceIDName is the name of the service ID.
User API key: The message that you get says IAM Identity Service: update user-apikey APIkeyName -failure where APIkeyName is the name of the API key.
Account API key: The message that you get says IAM Identity Service: update account-apikey APIkeyName -failure where APIkeyName is the name of the API key.

In the event, the lock field in requestData is set to true. This is the reason why this action fails. To successfully change an attribute of a service ID, the lock field must be set to false.

Notice that the field severity is set to critical. Someone is trying to modify a service ID that is locked in the account.