IBM Security Verify API で イベントログをダウンロードする

# はじめに
IBM Security Verify上には、認証操作などのログは、90日間保管されてます。
90日を超えるとログが削除されるため、ログをダウンロードする方法についてご紹介いたします。

# APIのリファレンス
APIのリファレンスは、以下のURLから確認できます。
https://<自分のテナント名＞.verify.ibm.com/developer/explorer/#

- ユーザーの取得に利用するAPIは、以下の項目になります。
    - Events 

|![event1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/8ac8e6d2-c788-0fcb-5851-aad39099b6b2.png)
|:--|

# 1.IBM Security VerifyへのAPIクライアントの登録
OAuth アクセストークンを取得するために使用するクライアント ID とクライアント秘密鍵を準備します。
ブラウザで、IBM Security Verifyの管理画面にアクセスします。
https://<自分のテナント名＞.verify.ibm.com/ui/admin

「構成」-「API クライアント」タブを開き、APIクライアントの追加を行います。
![OTP-000002.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/9799fa7c-cb28-7726-df1d-ccdece0060e8.png)

資格は以下を選択します。

- レポートの管理　または　レポートの読み取り


|![event2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/4f1762eb-a7b9-44f4-78bc-f99eafa5a6e6.png)
|:--|

# 2.イベントログの種類とダウンロードに際する考慮事項

管理画面のレポート（認証アクティビティなど）と同様に、イベントには種類があります。
イベントの種類を指定してダウンロードすることができます。
ダウンロードには1回のリクエストに対する数に制約があるのでご注意ください。

- イベントの種類を指定しない場合(デフォルト)は、**SSO、Authentication、Management**のログが出力されます。
    - The default setting includes management, sso and authentication event types.
- 他のイベント種類もあります。
    - Other events that can be included are: service, fulfillment, adaptive_risk, cert_campaign, access_request, account_sync, token or privacy_consent events.
- 1回のリクエストのイベント数はデフォルト**50イベント**。最大**10000イベント**まで取得可能
    - The number of events to return. The default setting is 50. The maximum is 10,000.
- デフォルトでは**過去24時間以内**のログが出力される。**From/To**を**Unix Epoch timestamp (milliseconds単位)**で指定できる。
    - The lower bound Unix Epoch timestamp of events to return. The default setting is the last 24 hours
    - The upper bound Unix Epoch timestamp of events to return. The default setting is the current time. 

# 3.イベントログの取得方法について

イベントログは、get /v1.0/events を用いてダウンロードできます。ログのフォーマットは、JSON形式です。

```
curl -i -X GET https://<テナント名＞.verify.ibm.com/v1.0/events --header "Authorization: Bearer <アクセストークン>"

```

レスポンスコードは200になります。
![event3.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/64833976-d60d-85ee-3ab7-574717186935.png)


イベントログはJSON形式で出力されます。

![event4.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/678692/95157f93-4b9a-1c06-d76e-0de0d8f13b65.png)


# 4.各イベントログのサンプルについて

イベントログの種類ごとにサンプルをみていきます。

①SSO
アプリケーションとのシングルサインインに関するログが出力されます。
以下は、カスタムアプリケーションを登録し、SAML連携したときのログになります。

```
{
                    "geoip": {
                        "continent_name": "Asia",
                        "city_name": "Tokyo",
                        "country_iso_code": "JP",
                        "country_name": "Japan",
                        "region_name": "Tokyo",
                        "location": {
                            "lon": "xx.xx",
                            "lat": "xx.xx"
                        }
                    },
                    "data": {
                        "result": "success",
                        "subtype": "saml",
                        "providerid": "verify-app",
                        "origin": "xx.xx.xx.xx",
                        "realm": "cloudIdentityRealm",
                        "samlassertion": "<saml:Assertion ~~~</saml:Assertion>",
                        "applicationid": "xx",
                        "userid": "xxxxxxxxxx",
                        "applicationtype": "Custom Application",
                        "devicetype": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36",
                        "username": "xxxxxxxx",
                        "applicationname": "SAML application service provider(Bluemix)"
                    },
                    "year": 2021,
                    "event_type": "sso",
                    "month": 5,
                    "indexed_at": 1621910104424,
                    "@processing_time": 155,
                    "tenantid": "xx-xx-xx-xx-xx",
                    "tenantname": "xx.verify.ibm.com",
                    "correlationid": "Cxx",
                    "servicename": "saml_runtime",
                    "id": "xx",
                    "time": 1621910104269,
                    "application_info": {
                        "name": "SAML application service provider(Bluemix)",
                        "type": "Custom Application"
                    },
                    "day": 25
                }
```


②Authentication
認証に関するログが出力されます。
以下は、Cloud Directoryに、ユーザーID/パスワードでログインし、成功したときのログになります。

```
{
                    "geoip": {
                        "continent_name": "Asia",
                        "city_name": "Tokyo",
                        "country_iso_code": "JP",
                        "country_name": "Japan",
                        "region_name": "Tokyo",
                        "location": {
                            "lon": "xx.xx",
                            "lat": "xx.xx"
                        }
                    },
                    "data": {
                        "result": "success",
                        "subtype": "user_password",
                        "subject": "xx",
                        "origin": "xx.xx.xx.xx",
                        "cause": "Authentication Successful",
                        "action": "login",
                        "sourcetype": "clouddirectory",
                        "realm": "cloudIdentityRealm",
                        "devicetype": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:88.0) Gecko/20100101 Firefox/88.0",
                        "target": "https://xx.verify.ibm.com/oidc/endpoint/default/authorize?qsId=x&client_id=xx_browser-user",
                        "username": "xxx"
                    },
                    "year": 2021,
                    "event_type": "authentication",
                    "month": 5,
                    "indexed_at": 1622494417954,
                    "@processing_time": 13,
                    "tenantid": "xx-xx-xx-xx-xx",
                    "tenantname": "xx.verify.ibm.com",
                    "correlationid": "xx",
                    "servicename": "authsvc",
                    "id": "xx",
                    "time": 1622494417941,
                    "day": 31
                }
```

次は、SMS OTPで二要素認証を行い、成功したときのログになります。

```
{
                    "geoip": {
                        "continent_name": "Asia",
                        "city_name": "Tokyo",
                        "country_iso_code": "JP",
                        "country_name": "Japan",
                        "region_name": "Tokyo",
                        "location": {
                            "lon": "xx.xx",
                            "lat": "xx.xx"
                        }
                    },
                    "data": {
                        "result": "success",
                        "mfamethod": "SMS OTP",
                        "subtype": "mfa",
                        "subject": "xx",
                        "origin": "xx.xx.xx.xx",
                        "realm": "cloudIdentityRealm",
                        "mfadevice": "81-80-xxxx-xxxx",
                        "devicetype": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36",
                        "username": "testuser03",
                        "target": "https://xx.verify.ibm.com/saml/sps/auth?themeId=xx&stateid=xx"
                    },
                    "year": 2021,
                    "event_type": "authentication",
                    "month": 5,
                    "indexed_at": 1621910102564,
                    "@processing_time": 36,
                    "tenantid": "xx",
                    "tenantname": "xx.verify.ibm.com",
                    "correlationid": "xx",
                    "servicename": "authsvc",
                    "id": "xx",
                    "time": 1621910102528,
                    "day": 25
                }
```


③Management

管理系操作に関するログが出力されます。
以下は、Cloud Directoryに、ユーザー（testuser03）を新規登録したときのログになります。

```
{
                    "geoip": {
                        "continent_name": "Asia",
                        "city_name": "Tokyo",
                        "country_iso_code": "JP",
                        "country_name": "Japan",
                        "region_name": "Tokyo",
                        "location": {
                            "lon": "xx.xx",
                            "lat": "xx.xx"
                        }
                    },
                    "data": {
                        "targetid_realm": "cloudIdentityRealm",
                        "api_grant_type": "authorization_code",
                        "targetid_username": "testuser03",
                        "performedby_type": "user",
                        "targetid": "xx",
                        "userinfo_lookup": "performedby;targetid",
                        "resource": "user",
                        "origin": "xx.xx.xx.xx",
                        "performedby_username": "xx",
                        "cause": "\"testuser03\" を作成しました。",
                        "messageid": "システムはユーザー",
                        "devicetype": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:88.0) Gecko/20100101 Firefox/88.0",
                        "performedby_realm": "cloudIdentityRealm",
                        "target": "testuser03",
                        "result": "success",
                        "performedby": "xx",
                        "json": "{\"emails\":[{\"type\":\"work\",\"value\":\"xx@xx.com\"}],\"password\":\"********\",\"addresses\":[{\"type\":\"work\",\"primary\":false}],\"urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification\":{\"notifyType\":\"EMAIL\",\"notifyManager\":false,\"notifyPassword\":true},\"schemas\":[\"urn:ietf:params:scim:schemas:core:2.0:User\",\"urn:ietf:params:scim:schemas:extension:ibm:2.0:User\",\"urn:ietf:params:scim:schemas:extension:ibm:2.0:Notification\"],\"name\":{\"familyName\":\"user03\",\"givenName\":\"test\"},\"urn:ietf:params:scim:schemas:extension:ibm:2.0:User\":{\"userCategory\":\"regular\",\"twoFactorAuthentication\":false,\"realm\":\"cloudIdentityRealm\",\"customAttributes\":[]},\"active\":true,\"userName\":\"testuser03\"}",
                        "self": "false",
                        "action": "created",
                        "location": "https://xx.verify.ibm.com/v2.0/Users",
                        "realm": "cloudIdentityRealm"
                    },
                    "year": 2021,
                    "event_type": "management",
                    "month": 5,
                    "indexed_at": 1622496563088,
                    "@processing_time": 30,
                    "tenantid": "xx",
                    "tenantname": "xx.verify.ibm.com",
                    "correlationid": "xx",
                    "servicename": "profilemgmt",
                    "id": "xx",
                    "time": 1622496563058,
                    "day": 31
                }

```

# 最後に

今回はイベントログのダウンロード方法とログのサンプルについてご紹介しました。

IBMのSIEM 製品である IBM QRadar へログを保管することも可能です。
Global Communityの記事は英語ですが、画面ショット付きで解説されてありますのでわかりやすいです。
ご参照ください。

- (参考)IBM Security Verifyのマニュアル
    - https://www.ibm.com/docs/ja/security-verify?topic=integrations-security-qradar
    
- (参考)Recipe for Integrating QRadar and IBM Security Verify
    - https://community.ibm.com/community/user/security/blogs/vandana-verma-sehgal1/2021/01/27/recipe-for-integrating-qradar-and-ibm-security-ve