Skip to content

Latest commit

 

History

History
638 lines (565 loc) · 23.7 KB

at-events.md

File metadata and controls

638 lines (565 loc) · 23.7 KB
copyright lastupdated keywords subcollection
years
2017, 2020
2020-01-09
user events, track activity, manage events, analyze, administrative, runtime, sign in, settings, app security
appid

{:external: target="_blank" .external} {:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:codeblock: .codeblock} {:tip: .tip} {:note: .note} {:important: .important} {:deprecated: .deprecated} {:download: .download} {:preview: .preview}

Activity Tracker events

{: #at-events}

You can view, manage, and analyze user-initiated activities made in your {{site.data.keyword.appid_full}} service instance by using the {{site.data.keyword.at_short}} service. {: shortdesc}

By integrating {{site.data.keyword.at_short}} with {{site.data.keyword.appid_short_notm}} you can track two different types of events, administrative and runtime. Administrative events are those that are specific to your instance of the service. Administrative events cover configuration changes such as updating your identity providers or changing the theme of your login widget. Runtime events are those activities that occur at runtime by the app user. A password reset request, authentication failures, or a user log out would all fall into the runtime category.

For more information about how the service works, see the {{site.data.keyword.at_short}} docs.

Viewing administrative events

{: #at-monitor-admin}

You can view, manage, and analyze configuration activity that is made in your {{site.data.keyword.appid_short_notm}} instance by using the {{site.data.keyword.at_short}} service. {: shortdesc}

Monitoring administrative activity

{: #at-monitor-admin-activity}

  1. Log in to your {{site.data.keyword.cloud_notm}} account.
  2. From the catalog, provision an instance of the {{site.data.keyword.at_short}} service in the same account as your {{site.data.keyword.appid_short_notm}} instance.
  3. From the Observability > Activity Tracker tab, verify the information for the instance that you created.
  4. Click View LogDNA and make sure you're on the Everything dashboard. Any events that meet the qualifications for your {{site.data.keyword.at_short}} payment plan are visible. You can filter your results by tags, sources, apps or levels. You can also search for specific events or jump to a specific timeframe.

List of administrative events

{: #at-events-admin}

Check out the following table for a list of the events that are sent to {{site.data.keyword.at_short}}.

Table 1. Actions that you can take that are tracked by {{site.data.keyword.at_short}}
Action Description GUI action
appid.recentActivity.read View recent activity. Can be found in the Activity Log box on the Overview tab.
appid.idpConfig.read View the identity provider configuration. Can be found in the Manage authentication > Identity Providers tab.
appid.idpConfig.update Update the identity provider configuration. Can be updated in the Manage authentication > Identity Providers tab.
appid.tokensConfig.read View the token expiration configuration. Can be found in the Manage authentication > Authentication Settings tab.
appid.isProfilesActive.read View the user profile storage configuration. Can be found in the User Profiles tab.
appid.isProfilesActive.update Update your user profile storage configuration. Can be found in the User Profiles tab.
appid.themeColor.read View the theme color of the login widget header. Can be found in the Login Customization tab.
appid.themeColor.update Update the theme color of the login widget header. Can be Updated in the Login Customization tab.
appid.media.read View the image that is shown in the login widget. Can be found in the Login Customization tab.
appid.media.update Update the image that is shown in the login widget. Can be updated in the Login Customization tab.
appid.uiConfiguration.read View the login widget UI configuration which includes header color and image. Can be found in the Login Customization tab.
appid.uiLanguages.read View a list of supported languages. Must be viewed from the API.
appid.uiLanguages.update Update your supported languages. Must be updated through the API.
appid.samlMetadata.read View the {{site.data.keyword.appid_short_notm}} SAML metadata. Can be found in the Identity Providers > SAML 2.0 Federation tab.
appid.cloudDirectoryUser.read View a Cloud Directory user. Can be found in the Cloud Directory > Users > View user details tab.
appid.cloudDirectoryUser.update Update a Cloud Directory User. Can be updated in the Users tab.
appid.cloudDirectoryUser.delete Delete a Cloud Directory user. Must be deleted through the API.
appid.user.remove Delete a Cloud Directory user and profile. Must be deleted through the API.
appid.cloudDirectoryUsers.read View a list of your Cloud Directory users. Can be found in the Users tab.
appid.cloudDirectoryUsers.update Update your list of Cloud Directory users. Can be updated in the Users tab.
appid.cloudDirectoryUsers.delete Delete a list of Cloud Directory users. Must be deleted through the API.
appid.users.remove Delete a list of Cloud Directory users and profiles. Must be deleted through the API.
appid.emailTemplate.read View an email template. Can be found in the Identity Providers > Cloud Directory > Templates tab.
appid.emailTemplate.update Update an email template. Can be found in the Identity Providers > Cloud Directory > Templates tab.
appid.emailTemplate.delete Delete an email template to reset to the default. Can be found in the Identity Providers > Cloud Directory > Templates tab.
appid.senderDetails.read View the sender details. Can be found in the Identity Providers > Cloud Directory > Settings tab.
appid.senderDetails.update Update the sender details Can be found in the Identity Providers > Cloud Directory > Settings tab.
appid.resendNotification.update Resend user notifications. Can be found in the Identity Providers > Cloud Directory > Settings tab.
appid.selfForgotPassword.update Update the forgot password process. Can be found in the Identity Providers > Cloud Directory > Settings tab.
appid.forgotPasswordResult.update View the forgot password confirmation result. Must be done through the API.
appid.selfSignUp.update Update the sign-up process. Can be found in the Identity Providers > Cloud Directory > Settings tab.
appid.signUpResult.update View the sign-up result confirmation. Must be done through the API.
appid.action_url.read View the custom URL that is called when an action is performed. Can be found in the Identity Providers > Cloud Directory > Custom Landing Pages tab.
appid.action_url.update Update the custom URL that is called when an action is performed. Can be found in the Identity Providers > Cloud Directory > Settings tab.
appid.changePassword.update Change the Cloud Directory user password. Can be found in the Identity Providers > Cloud Directory > Settings tab.
appid.loginWidgetConfig.read View your login widget configuration. Can be found in the Login Customization tab.
appid.loginWidgetConfig.update Update your login widget configuration. Can be updated in the Login Customization tab.
appid.captureRuntimeActivity.read View runtime activity toggle. Can be viewed in the Identity Providers > Manage > Authentication Settings tab.
appid.captureRuntimeActivity.update Toggle runtime activity monitoring. Can be updated in the Identity Providers > Manage > Authentication Settings tab.
read.mfaExtension.premfa View your premfa extension configuration. Must be done through the API.
update.mfaExtension.premfa Update your premfa extension configuration. Must be done through the API.

Viewing runtime events

{: #at-monitor-runtime}

With {{site.data.keyword.at_short}}, you can review runtime activity made by an app user, such as logins, password resets, and authentications. {: shortdesc}

The reported events are per account, but there are limitations on the data rate and retention period of the collected runtime events. Increasing the limits might require an upgrade of the {{site.data.keyword.at_short}} service. For more information about the service limits, see the {{site.data.keyword.at_short}} docs.

This feature is available only for instances on graduated tier payment plan that were created after March 15, 2018. Using this feature incurs an extra charge. For more information on graduated tier pricing, see the {{site.data.keyword.cloud_notm}} pricing docs. {: note}

Monitoring runtime activity

{: #at-monitor-runtime-activity}

  1. Log in to your {{site.data.keyword.cloud_notm}} account.
  2. From the catalog, provision an instance of the {{site.data.keyword.at_short}} service in the same account as your {{site.data.keyword.appid_short_notm}} instance.
  3. In the {{site.data.keyword.appid_short_notm}} dashboard, click Manage authentication > Authentication settings.
  4. Scroll to the Runtime Activity panel and toggle the switch to enable tracking of runtime authentication activity. A message displays that notifies you that the feature is enabled and that you are charged differently. For more information, see How does App ID calculate pricing.
  5. From the Observability > Activity Tracker tab in the console navigation, verify the information for the instance that you created.
  6. Click View LogDNA. When the dashboard loads, you see an overall view of all of the activity in your account. You can use the search operators to filter your results by tags, sources, apps or levels. You can also search for specific events or jump to a specific timeframe.
  7. From the All Apps drop-down, select the instance of {{site.data.keyword.appid_short_notm}} that you want to track events for.

List of runtime events

{: #at-runtime-events}

Check out the following table for a list of the runtime events that are sent to {{site.data.keyword.at_short}}.

Table 2. Actions that can be tracked as authentication events at runtime
Description Action Outcome reason. reasonCode target.id target.name target.typeURI
Cloud Directory authentication success appid.user.authentication success 200 [appid user CRN] cloud_directory:[GUID] appid/user
Cloud Directory authentication failure appid.user.authentication failure 401 crn:unknown cloud_directory:unknown appid/user
Facebook authentication success appid.user.authentication success 200 [appid user CRN] facebook:[GUID] appid/user
Facebook authentication failure appid.user.authentication failure 401 crn:unknown facebook:unknown appid/user
Google authentication success appid.user.authentication success 200 [appid user CRN] google:[GUID] appid/user
Google authentication failure appid.user.authentication failure 401 crn:unknown google:unknown appid/user
SAML authentication success appid.user.authentication success 200 [appid user CRN] SAML:[GUID] appid/user
SAML authentication failure appid.user.authentication failure 401 crn:unknown SAML:unknown appid/user
Cloud Directory sign up appid.cloud_dir.user.create success 200 [appid user CRN] cloud_directory:[GUID] appid/cloud_dir/user
Cloud Directory signup failure appid.cloud_dir.user.create failure 400 crn:unknown cloud_directory:unknown appid/cloud_dir/user
Cloud Directory signup confirmation appid.cloud_dir.user.allow success 200 [appid user CRN] cloud_directory:[GUID] appid/cloud_dir/user
Cloud Directory signup confirmation failure appid.cloud_dir.user.allow failure 400 crn:unknown cloud_directory:unknown appid/cloud_dir/user
Cloud Directory change or reset password appid.cloud_dir.user.credentials.update success 200 [appid user CRN] cloud_directory:[GUID] appid/cloud_dir/user
Cloud Directory change or reset password failure appid.cloud_dir.user.credentials.update failure 400 crn:unknown cloud_directory:unknown appid/cloud_dir/user
Revoke user tokens appid.user.tokens.revoke success 200 appid user CRN idp:[GUID] appid/user
Revoke user tokens failure appid.user.tokens.revoke failure 400 appid user CRN idp:[GUID] appid/user
User logout appid.user.logout success 200 appid user CRN idp:[GUID] appid/user

Additional field names that appear in the {{site.data.keyword.at_short}} console have these values:
Field Value
eventTime The timestamp of the event.
requestData The instance's client ID.
initiator.id The account ID.
initiator.typeURI service/security/account/user

Analyzing runtime events

{: #at-runtime-analyze}

A user that generates a runtime event is identified as a GUID rather than by name or email. As the account owner, you can use the GUID to identify a specific user and then you can search to see all of the events that the user has triggered. {: shortdesc}

The following scenario works only for Cloud Directory users. If the user is defined by an external IdP such as Google or Facebook, only that identity provider can interpret the GUID. {: note}

Extracting user information from the GUID

{: #at-extract-information}

An event in the {{site.data.keyword.at_short}} console contains the following fields.

Table 3. Example fields that can be found in an event from the {{site.data.keyword.at_short}} console
Field Value Description
initiator.id cb967e0d-43c1-454a-968d-0efa24766846 The tenant ID.
target.name cloud_directory:34e1ea6d-cc02-4941-9462-7e9c5a40b360 The user ID.

To find the user information that aligns with the event GUID, use the following steps.

  1. In the Credentials tab of the {{site.data.keyword.appid_short_notm}} dashboard, copy and save the information in the apiKey and tenantID fields. The tenant ID should match the ID of the event. If no credentials exist, create a set.

  2. Obtain an IAM token for the apiKey by inserting the key into the following command:

curl -k -X POST \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --header "Accept: application/json" \
    --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
    --data-urlencode "apikey=THE_API_KEY" \
    "https://iam.cloud.ibm.com/identity/token"

{: codeblock}

  1. Copy the IAM token from the access_token field in the response.

  2. Select a region. Region options include: au-syd, eu-de, eu-gb, jp-tok, and us-south.

  3. Insert the IAM token, the tenant ID, and the user ID, into the following command to obtain the user information.

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer THE_IAM_TOKEN' \
'https://REGION.appid.cloud.ibm.com/TENANT_ID/cloud_directory/Users/THE_USER_ID'

{: codeblock}

You can also run this command by using the management APIs{: external}. Your output would look similar to the following:

  {
  "displayName": "test test",
  "active": true,
  "userName": "test0001",
  "mfaContext": {},
  "emails": [
    {
      "value": "[email protected]",
      "primary": true
    }
  ],
  "meta": {
    "lastLogin": "2018-12-10T16:05:36.665Z",
    "created": "2018-08-21T08:55:50.643Z",
    "location": "/v1/cb967e0d-43c1-454a-968d-0efa24766846/Users/34e1ea6d-cc02-4941-9462-7e9c5a40b360",
    "lastModified": "2018-12-10T16:05:36.675Z",
    "resourceType": "User"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "name": {
    "givenName": "test",
    "familyName": "test",
    "formatted": "test test"
  },
  "id": "34e1ea6d-cc02-4941-9462-7e9c5a40b360"
}

{: screen}

Finding user related events

{: #at-finding-user-events}

You can track the events of specific Cloud Directory users in {{site.data.keyword.at_short}} by using their email. Before you can begin tracking, the email must be mapped to a Cloud Directory GUID.

  1. Obtain an IAM token, a tenant ID and a region as described in the previous section.
  2. Insert the IAM token, the tenant ID, and the email into the following command to obtain the user information.
curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer THE_IAM_TOKEN' 'https://REGION.appid.cloud.ibm.com/TENANT_ID/users?email=EMAIL_ADDRESS'

{: codeblock}

The email address should be escaped. For example myTest%40yahoo.com instead of [email protected]. {: note}

Alternatively, you can use the Management APIs{: external}. Your output would look similar to the following:

{
  "users": [
    {
      "idp": "cloud_directory",
      "id": "1e123399-3499-4a5c-b5a9-93843a91dc80"
    },
    {
      "idp": "cloud_directory",
      "id": "2a7abbe5-0fce-402e-9ddf-265246b415c8"
    }
  ]
}

{: screen}

  1. Search for a cloud_directory:id value in the target.name_str field in the {{site.data.keyword.at_short}} console.