Add docs for moesif #6181
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| # Insights | ||
|
|
||
| Asgardeo provides built-in identity **Insights** that let administrators and organization owners analyze the identity activity of their organization, such as logins, registrations, token issuance, and more. | ||
|
|
||
| Insights are available **out of the box**. When your Asgardeo organization is created, Asgardeo automatically provisions a dedicated analytics workspace for your organization and begins publishing your identity events to it. The resulting dashboards are then embedded directly in the **Insights** section of the Asgardeo Console — there is nothing to install, configure, or enable. | ||
|
|
||
| ## View your insights | ||
|
|
||
| To view the insights of your organization: | ||
|
|
||
| 1. On the Asgardeo Console, go to **Insights**. | ||
|
|
||
| 2. Explore the available dashboards to analyze activities such as logins, registrations, and token issuance for your organization. | ||
|
|
||
| 3. Use the duration selector to adjust the time period shown in the dashboards. | ||
|
|
||
| {: width="700" style="display: block; margin: 0; border: 0.3px solid lightgrey;"} | ||
|
Contributor
There was a problem hiding this comment. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
# Verify the referenced image asset exists
fd -i 'insights-dashboard.png'Repository: wso2/docs-is Length of output: 38 🏁 Script executed: #!/bin/bash
set -euo pipefail
# 1) Search for the referenced file name anywhere in the repo
echo "== Matches for insights-dashboard.png =="
fd -i 'insights-dashboard.png' || true
# 2) Check the expected relative path (from the repo root)
echo "== Expected path existence check =="
EXPECTED="assets/img/guides/insights/insights-dashboard.png"
if [ -f "$EXPECTED" ]; then
echo "FOUND: $EXPECTED"
else
echo "NOT FOUND: $EXPECTED"
fi
# 3) Find all references to the asset in markdown
echo "== References in markdown =="
rg -n --hidden --glob '*.md' "insights-dashboard\.png" . || trueRepository: wso2/docs-is Length of output: 441 🏁 Script executed: #!/bin/bash
set -euo pipefail
# List possible similarly-named images
echo "== Matches for *insights*dashboard* (case-insensitive) =="
fd -i '*insights*dashboard*' || true
echo "== Matches for insights-dashboard.* (case-insensitive) =="
fd -i 'insights-dashboard.*' || true
# Inspect the likely directory (if present)
echo "== Directory listing for assets/img/guides/insights =="
ls -la assets/img/guides/insights || true
# Check for any references under the same guides/insights path
echo "== References to assets/img/guides/insights =="
rg -n --hidden --glob '*.md' 'assets/img/guides/insights' . || trueRepository: wso2/docs-is Length of output: 884 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== Find any PNGs with insights-dashboard in name (case-insensitive) =="
find . -type f \( -iname "*insights-dashboard*.png" -o -iname "*insights*dashboard*.png" \) | head -n 50
echo "== Find any PNGs with insights in name (case-insensitive) =="
find . -type f \( -iname "*insights*.png" \) | head -n 50
echo "== Find any directories named 'guides/insights' under assets =="
find . -type d -path "*assets*img*guides*insights*" -print | head -n 50
echo "== Check if repo contains 'assets/img/guides/insights' exactly anywhere =="
find . -type f -path "*assets/img/guides/insights/*" -print | head -n 50
echo "== Literal references to assets/img/guides/insights in markdown =="
rg -n --hidden --glob '*.md' 'assets/img/guides/insights' . || trueRepository: wso2/docs-is Length of output: 2220 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== Any files with insights-dashboard in name (case-insensitive), any extension =="
find . -type f -iname "*insights-dashboard*" | head -n 50
echo "== Any files with insights dashboard in name (case-insensitive) =="
find . -type f \( -iname "*insights*dashboard*" -o -iname "*dashboard*insights*" \) | head -n 50
echo "== Any directories named 'insights' under assets =="
find . -type d -path "*assets*img*guides*insights*" | head -n 50
echo "== Any references to insights-dashboard.* in markdown =="
rg -n --hidden --glob '*.md' "insights-dashboard" . || true
echo "== Check if any 'assets/img/guides/insights' directories exist under en/asgardeo/docs =="
find ./en/asgardeo/docs -type d -path "*assets/img/guides/insights*" | head -n 50
echo "== Check if a likely asset path exists under en/asgardeo/docs =="
EXPECTED="en/asgardeo/docs/assets/img/guides/insights/insights-dashboard.png"
if [ -f "$EXPECTED" ]; then
echo "FOUND: $EXPECTED"
else
echo "NOT FOUND: $EXPECTED"
fiRepository: wso2/docs-is Length of output: 1182 Fix broken Insights dashboard image reference.
🤖 Prompt for AI AgentsSource: Coding guidelines |
||
|
|
||
| ## Data retention | ||
|
|
||
| By default, your identity analytics data is retained for **3 months**. Insights dashboards reflect activity within this retention window. | ||
|
|
||
| If you require **longer data retention** or **additional, customizable dashboards**, you can move to a dedicated [Moesif](https://www.moesif.com/price){:target="_blank"} subscription. With your own Moesif subscription you gain extended retention and the ability to build and customize your own dashboards on top of your identity data. | ||
|
|
||
| ## Insights and your subscription tier | ||
|
|
||
| The depth of the built-in insights available to you depends on your **Asgardeo subscription tier**. Higher tiers unlock more advanced, built-in analytics and dashboards. As you move to a higher Asgardeo tier, additional insights become available automatically in the **Insights** section. | ||
|
|
||
| ## Data published for insights | ||
|
|
||
| During your Asgardeo organization creation, Asgardeo provisions an analytics workspace for your organization and begins publishing identity events to it. These events are used to build the dashboards shown in the **Insights** section. | ||
|
|
||
| The following identity events are published. Each event includes contextual attributes about the activity, which may include personal data such as the end user's email, login identifiers (for example, mobile number or NIC where used as login attributes), IP address, and user agent. | ||
|
|
||
| <table> | ||
| <thead> | ||
| <tr> | ||
| <th>Event</th> | ||
| <th>Description</th> | ||
| <th>Key attributes published</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| <tr> | ||
| <td><b>Authentication</b></td> | ||
| <td>Captures user login attempts and the outcome of each authentication step.</td> | ||
| <td>Timestamp, username, user ID, user store domain, organization, application, connection (identity provider), authentication step and authenticator, step result (success/failure), session ID, inbound protocol, IP address, and user agent.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><b>Session</b></td> | ||
| <td>Captures the lifecycle of user sessions (creation, update, and termination).</td> | ||
| <td>Timestamp, session ID, session duration, termination reason, user ID, username, organization, application, connection, session action, and active session count.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><b>Token issuance</b></td> | ||
| <td>Captures OAuth2/OpenID Connect token issuance, including machine-to-machine (M2M) tokens.</td> | ||
| <td>Timestamp, application (client ID), grant type, user type, user ID and username, user store, issuing and accessing organization, authorized and unauthorized scopes, access/refresh token validity, token ID, whether an existing token was reused, sub-organization request indicator, IP address, and error details (on failure).</td> | ||
|
Contributor
There was a problem hiding this comment. Align organization terminology with the repository style rule. The text uses “sub-organization.” Vale flags this repo style as “organization” terminology. Please normalize this wording consistently in this page (including section heading and table row attribute text) to avoid repeated style warnings. Also applies to: 80-82 🧰 Tools🪛 GitHub Check: Vale style check[warning] 57-57: Raw Output: 🤖 Prompt for AI AgentsSources: Coding guidelines, Linters/SAST tools |
||
| </tr> | ||
| <tr> | ||
| <td><b>Registration</b></td> | ||
| <td>Captures user account creation.</td> | ||
| <td>User created timestamp, user store domain, organization, onboarding method (administrator-initiated, self sign-up, or invitation), user ID, and user agent.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><b>Flow</b></td> | ||
| <td>Captures step-by-step execution of self-registration, password recovery, and invited-user registration flows, enabling funnel analysis. Steps that occur before the user account exists are tracked under an anonymous identifier, which is linked to the resulting user once the flow completes.</td> | ||
| <td>Flow type, step type, node ID and type, context ID, organization, node response status and type, application ID, executor name, cross-organization indicator, timestamp, and error code.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><b>Organization switch</b></td> | ||
| <td>Captures when a user switches into (accesses) an organization in a B2B setup.</td> | ||
| <td>User's resident (home) organization, accessing organization, application, application tenant, tenant, error code, and timestamp.</td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| !!! note | ||
| More event types may be added over time as additional insights become available. | ||
|
|
||
| ## Insights for sub-organizations | ||
|
|
||
| Sub-organization-level insights are published against the **root organization**. This means activity that occurs within your sub-organizations is captured under your root organization's analytics workspace, and you can use this data to analyze and build insights for your sub-organizations as well. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,2 +1,6 @@ | ||
| {% set product_name = "Asgardeo" %} | ||
|
|
||
| !!! note | ||
| Looking for the analytics dashboards in the **Insights** section of the Console? See [Insights]({{base_path}}/guides/insights/) for the identity insights that Asgardeo provides out of the box. | ||
|
|
||
| {% include "../../../includes/guides/organization-insights.md" %} | ||
|
Contributor
There was a problem hiding this comment. Fix the markdownlint blocker: file must end with exactly one newline. CI reports 🧰 Tools🪛 GitHub Actions: Markdown Lint / 0_lint.txt[error] 6-6: markdownlint-cli2 (markdownlint v0.38.0) reported MD047/single-trailing-newline: Files should end with a single newline character. 🪛 GitHub Actions: Markdown Lint / lint[error] 6-6: markdownlint (MD047/single-trailing-newline): Files should end with a single newline character. 🪛 GitHub Check: lint[failure] 6-6: Files should end with a single newline character 🤖 Prompt for AI AgentsSources: Coding guidelines, Pipeline failures |
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,159 @@ | ||
| # Moesif Analytics | ||
|
Contributor
There was a problem hiding this comment. Use sentence case in the page title. Change As per coding guidelines, headings and document titles must use sentence case. 🧰 Tools🪛 GitHub Check: Vale style check[warning] 1-1: Raw Output: [warning] 1-1: Raw Output: 🤖 Prompt for AI AgentsSources: Coding guidelines, Linters/SAST tools |
||
|
|
||
| WSO2 Identity Server can publish identity events to [Moesif](https://www.moesif.com/price){:target="_blank"}, a SaaS analytics platform, so that you can build dashboards and analyze the identity activity of your deployment — such as logins, registrations, token issuance, and more. | ||
|
|
||
| You manage your own Moesif subscription. You connect your WSO2 Identity Server tenants to your Moesif account, choose which data to publish, and build your own dashboards in Moesif on top of the published data. | ||
|
|
||
| ## How it works | ||
|
|
||
| 1. You enable the Moesif integration in WSO2 Identity Server by adding a set of configurations to the `deployment.toml` file. Once these are added, an **Insights** tab becomes visible in the WSO2 Identity Server Console. | ||
| 2. From the **Insights** settings page in the Console, each tenant configures their Moesif **collector key** and enables the data publishers they need. This is a **per-tenant (tenanted) configuration** — each tenant publishes to its own Moesif workspace. | ||
| 3. WSO2 Identity Server publishes the selected identity events to Moesif. | ||
| 4. You build and view your own dashboards in Moesif based on the published data. | ||
|
|
||
| !!! note | ||
| Sample / pre-built dashboards are planned for a future release but are **not yet available**. For now, you create your own dashboards in Moesif based on the published data. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - A Moesif account and subscription. You are responsible for managing your own Moesif subscription, data retention, and access. | ||
| - Access to your WSO2 Identity Server `deployment.toml` file to enable the integration. | ||
|
|
||
| ## Step 1: Enable the Moesif integration | ||
|
|
||
| To make the **Insights** tab visible in the Console and enable Moesif publishing, add the following configurations to the `deployment.toml` file of your WSO2 Identity Server and restart the server. | ||
|
|
||
| ```toml | ||
| [analytics.moesif] | ||
| enabled = true | ||
| provider_url = "https://api.moesif.net/v1" | ||
| auth_type = "API_KEY" | ||
| api_key_header = "X-Moesif-Application-Id" | ||
| stream_version = "1.0.0" | ||
| ``` | ||
|
|
||
| !!! note | ||
| `provider_url` is the base URL events are published to. The integration appends the | ||
| Moesif API path (for example `/actions` or `/users`) per event, so configure the base | ||
| URL without a trailing API path. If you publish through an intermediary (for example, | ||
| an event gateway), point `provider_url` at it instead. | ||
|
|
||
| The following data publishers are available. You can enable the publishers you need (these can also be enabled per tenant from the **Insights** settings page in the Console): | ||
|
|
||
| ```toml | ||
| [identity_mgt.events.schemes.moesifUserAuthenticationPublisher.properties] | ||
| enable = true | ||
|
|
||
| [identity_mgt.events.schemes.moesifUserRegistrationPublisher.properties] | ||
| enable = true | ||
|
|
||
| [identity_mgt.events.schemes.moesifFlowPublisher.properties] | ||
| enable = true | ||
|
|
||
| [identity_mgt.events.schemes.moesifOrgSwitchPublisher.properties] | ||
| enable = true | ||
|
|
||
| [identity_mgt.events.schemes.moesifUserSessionPublisher.properties] | ||
| enable = true | ||
|
|
||
| [identity_mgt.events.schemes.moesifOAuthTokenIssuancePublisher.properties] | ||
| enable = true | ||
| ``` | ||
|
|
||
| Once these configurations are added and the server is restarted, the **Insights** tab appears in the WSO2 Identity Server Console. | ||
|
|
||
| ## Step 2: Obtain your Moesif collector key | ||
|
|
||
| The **collector key** (also called the Application Id) is the write-only key that WSO2 Identity Server uses to publish events to your Moesif workspace. To obtain it: | ||
|
|
||
| 1. Log in to the [Moesif portal](https://www.moesif.com/){:target="_blank"}. | ||
|
|
||
| 2. Go to your workspace settings and open the **Collector Application Ids** (API keys) section. | ||
|
|
||
| 3. Copy the **Collector Application Id** for the workspace you want WSO2 Identity Server to publish to. | ||
|
|
||
| {: width="700" style="display: block; margin: 0; border: 0.3px solid lightgrey;"} | ||
|
Contributor
There was a problem hiding this comment. Confirm screenshot availability or remove image dependencies. This guide introduces new screenshots, but the current review context does not confirm that these image assets exist and are accessible in the repository build path. Please verify asset presence and rendering, or remove image dependencies from the task flow. As per coding guidelines, do not reference images unless their existence and accessibility are explicitly confirmed. Also applies to: 86-86 🤖 Prompt for AI AgentsSource: Coding guidelines |
||
|
|
||
| !!! note | ||
| The collector key is a **write-only** key used only to send events to Moesif. Keep a separate collector key per tenant if you want to keep each tenant's analytics data in its own Moesif workspace. | ||
|
|
||
| ## Step 3: Configure Moesif for a tenant | ||
|
|
||
| After the integration is enabled, each tenant configures its own connection to Moesif from the Console: | ||
|
|
||
| 1. On the WSO2 Identity Server Console, go to **Insights**. | ||
|
|
||
| 2. On the Insights settings page, enter the Moesif **collector key** you obtained in Step 2 for this tenant. | ||
|
|
||
| 3. Enable the data publishers you want for this tenant (authentication, session, token issuance, registration, flow, and organization switch). | ||
|
|
||
| 4. Save the configuration. | ||
|
|
||
| {: width="700" style="display: block; margin: 0; border: 0.3px solid lightgrey;"} | ||
|
|
||
| !!! note | ||
| Configuration is **per tenant**. Each tenant publishes data to its own Moesif workspace using its own collector key, so you can keep each tenant's analytics data separate. | ||
|
|
||
| ## Step 4: Build dashboards in Moesif | ||
|
|
||
| Once data starts flowing into Moesif, you can create your own dashboards in the Moesif console based on the published data. Use the attributes published with each event (described below) to build the visualizations and reports you need. | ||
|
|
||
| ## Data published to Moesif | ||
|
|
||
| The following identity events can be published to Moesif. Each event includes contextual attributes about the activity, which may include personal data such as the end user's email, login identifiers (for example, mobile number or NIC where used as login attributes), IP address, and user agent. | ||
|
|
||
| <table> | ||
| <thead> | ||
| <tr> | ||
| <th>Event</th> | ||
| <th>Publisher</th> | ||
| <th>Description</th> | ||
| <th>Key attributes published</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| <tr> | ||
| <td><b>Authentication</b></td> | ||
| <td><code>moesifUserAuthenticationPublisher</code></td> | ||
| <td>Captures user login attempts and the outcome of each authentication step.</td> | ||
| <td>Timestamp, username, user ID, user store domain, tenant/organization, application (service provider), connection (identity provider), authentication step and authenticator, step result (success/failure), session ID, inbound protocol, IP address, and user agent.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><b>Session</b></td> | ||
| <td><code>moesifSessionPublisher</code></td> | ||
| <td>Captures the lifecycle of user sessions (creation, update, and termination).</td> | ||
| <td>Timestamp, session ID, session duration, termination reason, user ID, username, tenant/organization, service provider, identity provider, session action, and active session count.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><b>Token issuance</b></td> | ||
| <td><code>moesifTokenPublisher</code></td> | ||
| <td>Captures OAuth2/OpenID Connect token issuance, including machine-to-machine (M2M) tokens.</td> | ||
| <td>Timestamp, application (client ID), grant type, user type, user ID and username, user store, issuing and accessing organization, authorized and unauthorized scopes, access/refresh token validity, token ID, whether an existing token was reused, sub-organization request indicator, IP address, and error details (on failure).</td> | ||
| </tr> | ||
| <tr> | ||
| <td><b>Registration</b></td> | ||
| <td><code>moesifUserRegistrationPublisher</code></td> | ||
| <td>Captures user account creation.</td> | ||
| <td>User created timestamp, user store domain, tenant/organization, onboarding method (administrator-initiated, self sign-up, or invitation), user ID, and user agent.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><b>Flow</b></td> | ||
| <td><code>moesifFlowPublisher</code></td> | ||
| <td>Captures step-by-step execution of self-registration, password recovery, and invited-user registration flows, enabling funnel analysis.</td> | ||
| <td>Flow type, step type, node ID and type, context ID, tenant/organization, node response status and type, application ID, executor name, cross-organization indicator, timestamp, and error code.</td> | ||
| </tr> | ||
| <tr> | ||
| <td><b>Organization switch</b></td> | ||
| <td><code>moesifOrgSwitchPublisher</code></td> | ||
| <td>Captures when a user switches into (accesses) an organization in a B2B setup.</td> | ||
| <td>User's resident (home) organization, accessing organization, application, application tenant, tenant, error code, and timestamp.</td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| !!! note | ||
| More event types may be added over time. | ||
|
|
||
| ## Insights for sub-organizations | ||
|
|
||
| Sub-organization-level events are published against the **root organization**. Activity that occurs within sub-organizations is captured under the root organization's Moesif workspace, so you can use this data to build dashboards for your sub-organizations as well. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Use a shorter phrase than “time period.”
Replace “time period” with “time range” or “duration” to satisfy the wording rule and keep the step concise.
As per coding guidelines: use plain language and short sentences, and avoid wordy phrasing in documentation.
🧰 Tools
🪛 GitHub Check: Vale style check
[warning] 15-15:
[vale] reported by reviewdog 🐶
[WSO2-IAM.TooWordy] 'time period' is too wordy.
Raw Output:
{"message": "[WSO2-IAM.TooWordy] 'time period' is too wordy.", "location": {"path": "en/asgardeo/docs/guides/insights.md", "range": {"start": {"line": 15, "column": 44}}}, "severity": "WARNING"}
🤖 Prompt for AI Agents
Sources: Coding guidelines, Linters/SAST tools