GitBook: [#117] Add Audit log page

authgear · Dec 8, 2022 · 6b16a2b · 6b16a2b
1 parent 71110ae
commit 6b16a2b
Show file tree

Hide file tree

Showing 28 changed files with 150 additions and 51 deletions.
diff --git a/.gitbook/assets/image (2).png b/.gitbook/assets/image (2).png
diff --git a/.gitbook/assets/image.png b/.gitbook/assets/image.png
diff --git a/...development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (1) (1).png b/...development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (1) (1).png
diff --git a/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (10).png b/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (10).png
diff --git a/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (11).png b/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (11).png
diff --git a/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (12).png b/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (12).png
diff --git a/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (13).png b/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (13).png
diff --git a/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (14).png b/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (14).png
diff --git a/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (15).png b/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (15).png
diff --git a/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (16).png b/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (16).png
diff --git a/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (17).png b/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (17).png
diff --git a/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (18).png b/...at-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (18).png
diff --git a/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (2).png b/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (2).png
diff --git a/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (3).png b/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (3).png
diff --git a/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (4).png b/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (4).png
diff --git a/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (5).png b/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (5).png
diff --git a/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (6).png b/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (6).png
diff --git a/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (7).png b/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (7).png
diff --git a/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (8).png b/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (8).png
diff --git a/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (9).png b/...hat-development-information (5) (5) (5) (5) (1) (1) (1) (1) (1) (1) (1) (9).png
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -85,6 +85,10 @@
 
 * [Webhooks](webhooks/webhooks.md)
 
+## Monitor
+
+* [Audit Log](monitor/audit-log.md)
+
 ## Client App SDKs
 
 * [Javascript SDK Reference](https://authgear.github.io/authgear-sdk-js/docs/)

diff --git a/get-started/android/README.md b/get-started/android/README.md
@@ -19,26 +19,25 @@ From the Project listing, create a new Project or select an existing Project. Af
 **Step 1: Create an application in the Portal**
 
 1. Go to **Applications** on the left menu bar.
-1. Click **⊕Add Application** in the top tool bar.
-1. Input the name of your application and select **Native App** as the application type. Click "Save".
-1. You will see a list of guides that can help you for setting up, then click "Next".
+2. Click **⊕Add Application** in the top tool bar.
+3. Input the name of your application and select **Native App** as the application type. Click "Save".
+4. You will see a list of guides that can help you for setting up, then click "Next".
 
-![Create an application](<../../.gitbook/assets/create-application-app-1.png>)
+![Create an application](../../.gitbook/assets/create-application-app-1.png)
 
 **Step 2: Configure the application**
 
-1. In your IDE (e.g. Android Studio), define a custom URI scheme that the users will be redirected back to your app after they have authenticated with Authgear, e.g. `com.myapp.example://host/path`.[^1]
-1. Head back to Authgear Portal, fill in the Redirect URI that you have defined in the previous steps.
-1. Click "Save" in the top tool bar and keep the **Client ID**. You can also obtain it again from the Applications list later.
+1. In your IDE (e.g. Android Studio), define a custom URI scheme that the users will be redirected back to your app after they have authenticated with Authgear, e.g. `com.myapp.example://host/path`.\[^1]
+2. Head back to Authgear Portal, fill in the Redirect URI that you have defined in the previous steps.
+3. Click "Save" in the top tool bar and keep the **Client ID**. You can also obtain it again from the Applications list later.
 
-![Edit an application](<../../.gitbook/assets/edit-application-app.png>)
+![Edit an application](../../.gitbook/assets/edit-application-app.png)
 
 {% hint style="info" %}
-If you wish to [validate JSON Web Token (JWT) in your own application server](../backend-integration/jwt), turn on "Issue JWT as access token".[^2] If you wish to [forward authentication requests to Authgear Resolver Endpoint](../backend-integration/nginx), leave this unchecked. See comparisons in [Backend Integration](../backend-integration/).
+If you wish to [validate JSON Web Token (JWT) in your own application server](../backend-integration/jwt/), turn on "Issue JWT as access token".\[^2] If you wish to [forward authentication requests to Authgear Resolver Endpoint](../backend-integration/nginx/), leave this unchecked. See comparisons in [Backend Integration](../backend-integration/).
 {% endhint %}
 
-![](<../../.gitbook/assets/application-jwt.png>)
-
+![](../../.gitbook/assets/application-jwt.png)
 {% endtab %}
 
 {% tab title=" authgear.yaml (self-deployed)" %}
@@ -204,11 +203,11 @@ mAuthgear.fetchUserInfo(new OnFetchUserInfoListener() {
 });
 ```
 
-The value of `SessionState` can be `UNKNOWN`, `NO_SESSION` or `AUTHENTICATED`. Initially, the `sessionState` is `UNKNOWN`. After a call to `authgear.configure`, the session state would become `AUTHENTICATED` if a previous session was found, or `NO_SESSION` if such session was not found. 
+The value of `SessionState` can be `UNKNOWN`, `NO_SESSION` or `AUTHENTICATED`. Initially, the `sessionState` is `UNKNOWN`. After a call to `authgear.configure`, the session state would become `AUTHENTICATED` if a previous session was found, or `NO_SESSION` if such session was not found.
 
 ## Fetching User Info
 
-In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the `fetchUserInfo` function to obtain the user info, see [example](../integrate/user-profile.md#userinfo-endpoint). 
+In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the `fetchUserInfo` function to obtain the user info, see [example](../integrate/user-profile.md#userinfo-endpoint).
 
 ## Using the Access Token in HTTP Requests
 
@@ -278,5 +277,5 @@ To protect your application server from unauthorized access. You will need to **
 For detailed documentation on the Flutter SDK, visit [Android SDK Reference](https://authgear.github.io/authgear-sdk-android/)
 
 ### Footnote
-[^1]: For futher instruction on setting up custom URI scheme in Android, see [https://developer.android.com/training/app-links/deep-linking](https://developer.android.com/training/app-links/deep-linking)
-[^2]: For more explaination on JWT, see [https://en.wikipedia.org/wiki/JSON_Web_Token](https://en.wikipedia.org/wiki/JSON_Web_Token)
+
+\[^1]: For futher instruction on setting up custom URI scheme in Android, see [https://developer.android.com/training/app-links/deep-linking](https://developer.android.com/training/app-links/deep-linking) \[^2]: For more explaination on JWT, see [https://en.wikipedia.org/wiki/JSON\_Web\_Token](https://en.wikipedia.org/wiki/JSON\_Web\_Token)
diff --git a/get-started/flutter.md b/get-started/flutter.md
@@ -23,7 +23,7 @@ From the Project listing, create a new Project or select an existing Project. Af
 3. Input the name of your application and select **Native App** as the application type. Click "Save".
 4. You will see a list of guides that can help you for setting up, then click "Next".
 
-<figure><img src="../.gitbook/assets/image.png" alt=""><figcaption><p>Create Application</p></figcaption></figure>
+<figure><img src="../.gitbook/assets/image (2).png" alt=""><figcaption><p>Create Application</p></figcaption></figure>
 
 **Step 2: Configure the application**
 

diff --git a/get-started/ios.md b/get-started/ios.md
@@ -19,26 +19,25 @@ From the Project listing, create a new Project or select an existing Project. Af
 **Step 1: Create an application in the Portal**
 
 1. Go to **Applications** on the left menu bar.
-1. Click **⊕Add Application** in the top tool bar.
-1. Input the name of your application and select **Native App** as the application type. Click "Save".
-1. You will see a list of guides that can help you for setting up, then click "Next".
+2. Click **⊕Add Application** in the top tool bar.
+3. Input the name of your application and select **Native App** as the application type. Click "Save".
+4. You will see a list of guides that can help you for setting up, then click "Next".
 
-![Create an application](<../.gitbook/assets/create-application-app-1.png>)
+![Create an application](../.gitbook/assets/create-application-app-1.png)
 
 **Step 2: Configure the application**
 
-1. In your IDE (e.g. XCode), define a custom URI scheme that the users will be redirected back to your app after they have authenticated with Authgear, e.g. `com.myapp.example://host/path`.[^1]
-1. Head back to Authgear Portal, fill in the Redirect URI that you have defined in the previous steps.
-1. Click "Save" in the top tool bar and keep the **Client ID**. You can also obtain it again from the Applications list later.
+1. In your IDE (e.g. XCode), define a custom URI scheme that the users will be redirected back to your app after they have authenticated with Authgear, e.g. `com.myapp.example://host/path`.\[^1]
+2. Head back to Authgear Portal, fill in the Redirect URI that you have defined in the previous steps.
+3. Click "Save" in the top tool bar and keep the **Client ID**. You can also obtain it again from the Applications list later.
 
-![Edit an application](<../.gitbook/assets/edit-application-app.png>)
+![Edit an application](../.gitbook/assets/edit-application-app.png)
 
 {% hint style="info" %}
-If you wish to [validate JSON Web Token (JWT) in your own application server](../backend-integration/jwt), turn on "Issue JWT as access token".[^2] If you wish to [forward authentication requests to Authgear Resolver Endpoint](../backend-integration/nginx), leave this unchecked. See comparisons in [Backend Integration](../backend-integration/).
+If you wish to [validate JSON Web Token (JWT) in your own application server](../backend-integration/jwt/), turn on "Issue JWT as access token".\[^2] If you wish to [forward authentication requests to Authgear Resolver Endpoint](../backend-integration/nginx/), leave this unchecked. See comparisons in [Backend Integration](../backend-integration/).
 {% endhint %}
 
-![](<../.gitbook/assets/application-jwt.png>)
-
+![](../.gitbook/assets/application-jwt.png)
 {% endtab %}
 
 {% tab title="authgear.yaml (self-deployed)" %}
@@ -160,12 +159,11 @@ authgear.fetchUserInfo { userInfoResult in
 }
 ```
 
-
-The value of `sessionState` can be `.unknown`, `.noSession` or `.authenticated`. Initially, the `sessionState` is `.unknown`. After a call to `authgear.configure`, the session state would become `.authenticated` if a previous session was found, or `.noSession` if such session was not found. 
+The value of `sessionState` can be `.unknown`, `.noSession` or `.authenticated`. Initially, the `sessionState` is `.unknown`. After a call to `authgear.configure`, the session state would become `.authenticated` if a previous session was found, or `.noSession` if such session was not found.
 
 ## Fetching User Info
 
-In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the `fetchUserInfo` function to obtain the user info, see [example](../integrate/user-profile.md#userinfo-endpoint). 
+In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the `fetchUserInfo` function to obtain the user info, see [example](../integrate/user-profile.md#userinfo-endpoint).
 
 ## Using the Access Token in HTTP Requests
 
@@ -222,5 +220,5 @@ To protect your application server from unauthorized access. You will need to **
 For detailed documentation on the iOS SDK, visit [iOS SDK Reference](https://authgear.github.io/authgear-sdk-ios/).
 
 ### Footnote
-[^1]: For futher instruction on setting up custom URI scheme in iOS, see [https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app)
-[^2]: For more explaination on JWT, see [https://en.wikipedia.org/wiki/JSON_Web_Token](https://en.wikipedia.org/wiki/JSON_Web_Token)
+
+\[^1]: For futher instruction on setting up custom URI scheme in iOS, see [https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) \[^2]: For more explaination on JWT, see [https://en.wikipedia.org/wiki/JSON\_Web\_Token](https://en.wikipedia.org/wiki/JSON\_Web\_Token)
diff --git a/get-started/xamarin.md b/get-started/xamarin.md
@@ -20,26 +20,25 @@ From the Project listing, create a new Project or select an existing Project. Af
 **Step 1: Create an application in the Portal**
 
 1. Go to **Applications** on the left menu bar.
-1. Click **⊕Add Application** in the top tool bar.
-1. Input the name of your application and select **Native App** as the application type. Click "Save".
-1. You will see a list of guides that can help you for setting up, then click "Next".
+2. Click **⊕Add Application** in the top tool bar.
+3. Input the name of your application and select **Native App** as the application type. Click "Save".
+4. You will see a list of guides that can help you for setting up, then click "Next".
 
-![Create an application](<../.gitbook/assets/create-application-app-1.png>)
+![Create an application](../.gitbook/assets/create-application-app-1.png)
 
 **Step 2: Configure the application**
 
-1. In your IDE (e.g. Visual Studio), define a custom URI scheme that the users will be redirected back to your app after they have authenticated with Authgear, e.g. `com.myapp.example://host/path`.[^1]
-1. Head back to Authgear Portal, fill in the Redirect URI that you have defined in the previous steps.
-1. Click "Save" in the top tool bar and keep the **Client ID**. You can also obtain it again from the Applications list later.
+1. In your IDE (e.g. Visual Studio), define a custom URI scheme that the users will be redirected back to your app after they have authenticated with Authgear, e.g. `com.myapp.example://host/path`.\[^1]
+2. Head back to Authgear Portal, fill in the Redirect URI that you have defined in the previous steps.
+3. Click "Save" in the top tool bar and keep the **Client ID**. You can also obtain it again from the Applications list later.
 
-![Edit an application](<../.gitbook/assets/edit-application-app.png>)
+![Edit an application](../.gitbook/assets/edit-application-app.png)
 
 {% hint style="info" %}
-If you wish to [validate JSON Web Token (JWT) in your own application server](../backend-integration/jwt), turn on "Issue JWT as access token".[^2] If you wish to [forward authentication requests to Authgear Resolver Endpoint](../backend-integration/nginx), leave this unchecked. See comparisons in [Backend Integration](../backend-integration/).
+If you wish to [validate JSON Web Token (JWT) in your own application server](../backend-integration/jwt/), turn on "Issue JWT as access token".\[^2] If you wish to [forward authentication requests to Authgear Resolver Endpoint](../backend-integration/nginx/), leave this unchecked. See comparisons in [Backend Integration](../backend-integration/).
 {% endhint %}
 
-![](<../.gitbook/assets/application-jwt.png>)
-
+![](../.gitbook/assets/application-jwt.png)
 {% endtab %}
 
 {% tab title="authgear.yaml (self-deployed)" %}
@@ -302,11 +301,11 @@ if (sessionState == SessionState.Authenticated)
 }
 ```
 
-The value of `SessionState` can be `Unknown`, `NoSession` or `Authenticated`. Initially, the `SessionState` is `Unknown`. After a call to `authgear.configure`, the session state would become `Authenticated` if a previous session was found, or `NoSession` if such session was not found. 
+The value of `SessionState` can be `Unknown`, `NoSession` or `Authenticated`. Initially, the `SessionState` is `Unknown`. After a call to `authgear.configure`, the session state would become `Authenticated` if a previous session was found, or `NoSession` if such session was not found.
 
 ## Fetching User Info
 
-In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the `FetchUserInfoAsync` function to obtain the user info, see [example](../integrate/user-profile.md#userinfo-endpoint). 
+In some cases, you may need to obtain current user info through the SDK. (e.g. Display email address in the UI). Use the `FetchUserInfoAsync` function to obtain the user info, see [example](../integrate/user-profile.md#userinfo-endpoint).
 
 ## Logout
 
@@ -348,5 +347,5 @@ To protect your application server from unauthorized access. You will need to **
 For detailed documentation on the Xamarin SDK, visit [Xamarin SDK Reference](https://authgear.github.io/authgear-sdk-xamarin/)
 
 ### Footnote
-[^1]: For futher instruction on setting up custom URI scheme in Xamarin, see [https://www.xamarinhelp.com/uri-scheme/](https://www.xamarinhelp.com/uri-scheme/)
-[^2]: For more explaination on JWT, see [https://en.wikipedia.org/wiki/JSON_Web_Token](https://en.wikipedia.org/wiki/JSON_Web_Token)
+
+\[^1]: For futher instruction on setting up custom URI scheme in Xamarin, see [https://www.xamarinhelp.com/uri-scheme/](https://www.xamarinhelp.com/uri-scheme/) \[^2]: For more explaination on JWT, see [https://en.wikipedia.org/wiki/JSON\_Web\_Token](https://en.wikipedia.org/wiki/JSON\_Web\_Token)
diff --git a/monitor/audit-log.md b/monitor/audit-log.md
@@ -0,0 +1,98 @@
+# Audit Log
+
+Authgear provides the event logs for you to analyze security issues and monitor the business.
+
+## View and retrieve logs
+
+You can view the audit log in the Portal, or retrieve logs using the [Admin API](../apis/admin-api/).
+
+### View in Portal
+
+The portal provides an interface for you to look up the log by event and date range.
+
+<figure><img src="../.gitbook/assets/image.png" alt=""><figcaption><p>View audit logs in the Portal</p></figcaption></figure>
+
+### Retrieve with Admin API
+
+The API schema can be found in the [Admin API QraphiQL Explorer](../apis/admin-api/#api-explorer). For example:
+
+```graphql
+query {
+  auditLogs(first:5){
+    edges{
+      node{
+        activityType
+        clientID
+        createdAt
+        data
+      }
+    }
+  }
+}
+```
+
+## Log events
+
+Here are the list of activity types that are logged:
+
+#### Authentication failed
+
+* AUTHENTICATION\_IDENTITY\_ANONYMOUS\_FAILED
+* AUTHENTICATION\_IDENTITY\_BIOMETRIC\_FAILED
+* AUTHENTICATION\_IDENTITY\_LOGIN\_ID\_FAILED
+* AUTHENTICATION\_PRIMARY\_OOB\_OTP\_EMAIL\_FAILED
+* AUTHENTICATION\_PRIMARY\_OOB\_OTP\_SMS\_FAILED
+* AUTHENTICATION\_PRIMARY\_PASSWORD\_FAILED
+* AUTHENTICATION\_SECONDARY\_OOB\_OTP\_EMAIL\_FAILED
+* AUTHENTICATION\_SECONDARY\_OOB\_OTP\_SMS\_FAILED
+* AUTHENTICATION\_SECONDARY\_PASSWORD\_FAILED
+* AUTHENTICATION\_SECONDARY\_RECOVERY\_CODE\_FAILED
+* AUTHENTICATION\_SECONDARY\_TOTP\_FAILED
+
+#### Identity changes
+
+* IDENTITY\_BIOMETRIC\_DISABLED
+* IDENTITY\_BIOMETRIC\_ENABLED
+* IDENTITY\_EMAIL\_ADDED
+* IDENTITY\_EMAIL\_REMOVED
+* IDENTITY\_EMAIL\_UPDATED
+* IDENTITY\_OAUTH\_CONNECTED
+* IDENTITY\_OAUTH\_DISCONNECTED
+* IDENTITY\_PHONE\_ADDED
+* IDENTITY\_PHONE\_REMOVED
+* IDENTITY\_PHONE\_UPDATED
+* IDENTITY\_USERNAME\_ADDED
+* IDENTITY\_USERNAME\_REMOVED
+* IDENTITY\_USERNAME\_UPDATED
+
+#### User actions
+
+* USER\_ANONYMOUS\_PROMOTED
+* USER\_AUTHENTICATED
+* USER\_CREATED
+* USER\_DELETED
+* USER\_DELETION\_SCHEDULED
+* USER\_DELETION\_UNSCHEDULED
+* USER\_DISABLED
+* USER\_PROFILE\_UPDATED
+* USER\_REENABLED
+* USER\_SESSION\_TERMINATED
+* USER\_SIGNED\_OUT
+
+#### Others
+
+* WHATSAPP\_OTP\_VERIFIED
+* SMS\_SENT
+* EMAIL\_SENT
+
+## Log data
+
+Each audit log event contains the following attributes in their data
+
+| Attribute | Description                                                                                                                                                                                                                                                            |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`      | Unique identifier of the event                                                                                                                                                                                                                                         |
+| `seq`     | Sequence number of the event                                                                                                                                                                                                                                           |
+| `type`    | Activity type                                                                                                                                                                                                                                                          |
+| `context` | The who, when and where of the event triggered. e.g. IP address, user agent, user ID, timestamp                                                                                                                                                                        |
+| `payload` | <p>Relevant data according to the event type:</p><p><strong>Messaging (SMS, Email OTP):</strong> the phone number/email address of the receiver</p><p><strong>Authentication/Identity/User actions:</strong> a snapshot of the related session and user attributes</p> |