Asgardeo events
# Asgardeo events
Asgardeo triggers events corresponding to the various user interactions in your Asgardeo organization. You can configure Asgardeo to publish these events to WSO2's integration platform, Choreo (opens new window). From there, you can define custom business logic that can be executed when an event occurs.
Asgardeo publishes the following events under three main categories.
Important
All events published by Asgardeo are end-to-end encrypted until Choreo processes and decrypts them.
Login events - Events related to login flows.
- Login success event: Published when a user successfully logs in to an application.
- Login failed event: Published when a user fails to log in to an application.
User operation events - Events related to user operations, profile updates, and account deletes.
- User account lock event: Published when a user account is locked.
- User credential update event: Published when a user's credentials are updated.
- User group update event: Published when users are added or removed from a group.
- User account unlock event: Published when a user account is unlocked.
- User delete event: Published when a user's account is deleted.
Registration events - Events that occur during user registration flows.
- Add user event: Published when a user is added to the organization.
- Accept user invite event: Published when a user accepts an invitation to an organization.
- Confirm self-signup event: Published when a user completes account verification during self-sign-up.
# Configure Asgardeo to publish events
Follow the steps below to configure event publishing for Asgardeo.
On the Asgardeo Console, go to Events.
Select the events that you wish to publish to Choreo and click Update.
Alternatively, you can invoke the Event Configuration Management API to configure event publishing. See the API Documentation to learn more.
# Implement business use cases for Asgardeo events
Follow the steps below to define a business logic that will trigger when an Asgardeo event occurs.
# Prerequisite
You need to have a Github repository to host the business logic.
Download Ballerina (opens new window), the programming language used to define business logic for Asgardeo events.
# Define the business logic
Let's set up a sample business use case such that whenever a registration event is generated in Asgardeo, it gets logged in the Choreo console.
Follow the steps below to programmatically define the business logic.
Create a new Ballerina package. Learn how to do so in the Ballerina documentation (opens new window).
Navigate to the Ballerina.toml file and rename the organization name to that of your Asgardeo organization.
Navigate to your main.bal file and define the business logic.
New to Ballerina?
Learn more about the Asgardeo trigger module and how to program business logic for different types of events in the Ballerina documentation (opens new window).
The following is a sample code that logs the event in the Choreo console, when a registration event is generated in Asgardeo.
import ballerinax/trigger.asgardeo; import ballerina/log; import ballerina/http; configurable asgardeo:ListenerConfig config = ?; listener http:Listener httpListener = new(8090); listener asgardeo:Listener webhookListener = new(config,httpListener); service asgardeo:RegistrationService on webhookListener { remote function onAddUser(asgardeo:AddUserEvent event ) returns error? { log:printInfo(event.toJsonString()); } remote function onConfirmSelfSignup(asgardeo:GenericEvent event ) returns error? { log:printInfo(event.toJsonString()); } remote function onAcceptUserInvite(asgardeo:GenericEvent event ) returns error? { log:printInfo(event.toJsonString()); } } service /ignore on httpListener {}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29Commit your changes and push the code to your remote Github repository.
# Create a webhook in Choreo
Follow the steps below to create and deploy a webhook in Choreo.
Navigate to Choreo (opens new window) and if you don't have one already, create an organization with the same name and email address you used to create your Asgardeo organization.
Organizations in Asgardeo and Choreo synchronize based on their names.
Select a project from the Project dropdown.
Go to Components, and click Create.
Under the Select a Type tab, select Webhook. Learn more about webhooks in the Choreo documentation (opens new window).
Enter a name and a description for your webhook.
Click Authorize with Github and connect the relevant organization, repository and the branch of the Github repository you created in the above section.
Select Ballerina to be the Buildpack and select the Ballerina Project Directory from your Github repository.
Select the Access Mode as External and click Create.
Follow the Choreo documentation and deploy your webhook (opens new window).
If the callback URL fails to populate, it is advised to manually copy the invoke URL and paste it into the designated field. This step ensures seamless continuity in the process.
# Try it out
Once the webhook is deployed in Choreo, follow the steps below to try it out.
Login to the Asgardeo Console and go to User Management > Users.
Click Add User and create a new user.
Creating a new user triggers an add user event.
Go to the Choreo Console, and click Observability on the left navigation menu.
Find the Logs tab and filter for the logged add user event.
# Payload of an Asgardeo event
The payload of an Asgardeo event that is sent to Choreo consists of the following data objects:
Security Data object - The security data object is common to all Asgardeo events. This contains the following security metadata about the event.
Property Name Type Description iss
String Issuer of the event iat
String Event published timestamp. jti
String Unique identifier for the event. aud
String Audience of the event. Example security data object:
{ "iss": "Asgardeo", "jti": "3b69b103-fa6c-424a-bbf4-a974d0c2d2a3", "iat": 1659732032884, "aud": "https://websubhub/topics/myorg/REGISTRATIONS" }
1
2
3
4
5
6Event Data object - The event data object contains the details of the event (or the user action). Learn more about event data in the Event data of Asgardeo events section.
# Event data of Asgardeo events
This section describes all the Asgardeo events that can be published to Choreo and their respective event payloads.
# Login events
These are events related to login flows. The event data objects of login events are defined below.
# Login success event
When a user successfully logs in to an application, an event with the following data is created.
Property Name | Type | Description |
---|---|---|
ref | String | Group reference (SCIM location) |
organizationId | int | Organization Id |
organizationName | String | Organization name |
userId | String | User id |
userName | String | username |
userStoreName | String | User Store name |
serviceProvider | String | Application name |
authSteps | List | List of authentication steps used for log in. Each authentication step object contains the step number, identity provider and the name of the authenticator |
Example login success event payload:
{
"ref": "https://asgardeo.io/t/myorg/scim2/Users/72774617-8dff-472e-90b5-67069d94d299",
"organizationId": 3,
"organizationName": "myorg",
"userId": "72774617-8dff-472e-90b5-67069d94d299",
"userName": "[email protected]",
"userStoreName": "DEFAULT",
"serviceProvider": "My Account",
"authSteps": [
{
"step": 1,
"idp": "Google",
"authenticator": "GoogleOIDCAuthenticator"
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Login failed event
When a user fails to log in to an application, an event with the following data is created.
Property Name | Type | Description |
---|---|---|
ref | String | Group reference (SCIM location) |
organizationId | int | Organization Id |
organizationName | String | Organization name |
userId | String | User id |
authenticatingUser | String | username |
serviceProvider | String | Application name |
failedStep | Object | The step at which the fail event occurred. Contains the step number, identity provider and the name of the authenticator |
Example login failed event payload:
{
"ref": "https://asgardeo.io/t/myorg/scim2/Users/72774617-8dff-472e-90b5-67069d94d299",
"organizationId": 3,
"organizationName": "myorg",
"userId": "72774617-8dff-472e-90b5-67069d94d299",
"authenticatingUser": "[email protected]",
"serviceProvider": "My Account",
"failedStep": {
"step": 1,
"idp": "Google",
"authenticator": "GoogleOIDCAuthenticator"
}
}
2
3
4
5
6
7
8
9
10
11
12
13
# User operation events
These are events related to user operations, profile updates and deletes. The event data objects of user operation events are defined below.
# User account lock event
When a user account is locked, an event with the following data is created.
Property Name | Type | Description |
---|---|---|
ref | String | User reference (SCIM location) |
organizationId | int | Organization Id |
organizationName | String | Organization name |
userId | String | User id |
userName | String | username |
userStoreName | String | User Store name |
Example user account lock event payload:
{
"ref": "https://asgardeo.io/t/myorg/scim2/Users/72774617-8dff-472e-90b5-67069d94d299",
"organizationId": 3,
"organizationName": "myorg",
"userId": "72774617-8dff-472e-90b5-67069d94d299",
"userName": "[email protected]",
"userStoreName": "DEFAULT"
}
2
3
4
5
6
7
8
# User credential update event
A user's credential (password) update event with the following data is generated when a user credential is updated by one of the methods below.
- an administrator resets them through the Console.
- an administrator forces a reset.
- the user changes them from the My Account self-service portal.
- the user initiates a forgot password sequence and updates them.
Property Name Type Description ref
String User reference (SCIM location) organizationId
int Organization Id organizationName
String Organization name userId
String User id userName
String username initiatorType
String Initiator of the event. admin
: Indicates that an administrative action initiated the eventuser
: Indicates that an end-user action initiated the event
action
String Action taken by the initiator. update
: Indicates a credential update.reset
: Indicates a credential reset; either initiated by the admin as a forced credential update request or by the user initiating a forgot password flow.
userStoreName
String User Store name
Example User credential update event payload: Consider a scenario where an administrator resets the user credential through the Console.
{
"ref": "https://asgardeo.io/t/myorg/scim2/Users/72774617-8dff-472e-90b5-67069d94d299",
"organizationId": 3,
"organizationName": "myorg",
"userId": "72774617-8dff-472e-90b5-67069d94d299",
"userName": "[email protected]",
"initiatorType":"admin",
"action":"update",
"userStoreName": "DEFAULT"
}
2
3
4
5
6
7
8
9
10
# User group update event
When users are added or removed from a group, an event with the following data is created.
Property Name | Type | Description |
---|---|---|
ref | String | Group reference (SCIM location) |
organizationId | int | Organization Id |
organizationName | String | Organization name |
groupId | String | Group id |
groupName | String | Group name |
userStoreName | String | User Store name |
addedUsers | List | List of added user objects. User object contains userId & userName |
removedUsers | List | List of removed user objects. User object contains userId & userName |
Example user group update event payload:
{
"ref": "https://api.asg.io/t/myorg/scim2/Groups/3b47e4f0-97d0-4b11-86b5-8150105ff32f",
"organizationId": 3,
"organizationName": "myorg",
"groupId": "3b47e4f0-97d0-4b11-86b5-8150105ff32f",
"groupName": "Grouphr",
"userStoreName": "DEFAULT",
"addedUsers": [
{
"userName": "[email protected]",
"userId": "05c86c29-6e06-4743-8014-0523abd5b6d8"
},
{
"userName": "[email protected]",
"userId": "06405538-49be-46da-8d04-b38da91f56d0"
}
],
"removedUsers": [
{
"userName": "[email protected]",
"userId": "22e46698-7fa7-4497-90fc-e12864e30b77"
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# User account unlock event
When a user account is unlocked, an event with the following data is created.
Property Name | Type | Description |
---|---|---|
ref | String | User reference (SCIM location) |
organizationId | int | Organization Id |
organizationName | String | Organization name |
userId | String | User id |
userName | String | username |
userStoreName | String | User Store name |
Example User account unlock event payload:
{
"ref": "https://asgardeo.io/t/myorg/scim2/Users/72774617-8dff-472e-90b5-67069d94d299",
"organizationId": 3,
"organizationName": "myorg",
"userId": "72774617-8dff-472e-90b5-67069d94d299",
"userName": "[email protected]",
"userStoreName": "DEFAULT"
}
2
3
4
5
6
7
8
# User delete event
When a user's account is deleted, an event with the following data is created.
Property Name | Type | Description |
---|---|---|
ref | String | User reference (SCIM location) |
organizationId | int | Organization Id |
organizationName | String | Organization name |
userId | String | User id |
userName | String | username |
userStoreName | String | User Store name |
Example User account lock event payload:
{
"ref": "https://asgardeo.io/t/myorg/scim2/Users/72774617-8dff-472e-90b5-67069d94d299",
"organizationId": 3,
"organizationName": "myorg",
"userId": "72774617-8dff-472e-90b5-67069d94d299",
"userName": "[email protected]",
"userStoreName": "DEFAULT"
}
2
3
4
5
6
7
8
# Registration events
These are events related to user registration flows. The event data object of registration events are defined below.
# Add user event
When a user is added to the organization, an event with the following data is created.
Property Name | Type | Description |
---|---|---|
ref | String | User reference (SCIM location) |
organizationId | int | Organization Id |
organizationName | String | Organization name |
userId | String | User id |
userName | String | username |
userStoreName | String | User Store name |
userOnboardMethod | String | User onboarded method (Admin Initiated, User Invite, Self Sign Up) |
roleList | List | User’s Assigned Roles |
claims | Map | User Claims |
Example add user event payload:
{
"ref": "https://asgardeo.io/t/myorg/scim2/Users/72774617-8dff-472e-90b5-67069d94d299",
"organizationId": 3,
"organizationName": "myorg",
"userId": "72774617-8dff-472e-90b5-67069d94d299",
"userName": "[email protected]",
"userStoreName": "DEFAULT",
"userOnboardMethod": "SELF_SIGNUP",
"roleList": ["Internal/selfsignup"],
"claims": {
"http://wso2.org/claims/created":"2022-09-19T05:20:26.346Z",
"http://wso2.org/claims/dob":"1996-12-08",
"http://wso2.org/claims/country":"United Arab Emirates",
"http://wso2.org/claims/emailaddress":"[email protected]",
"http://wso2.org/claims/lastname":"Doe",
"http://wso2.org/claims/givenname":"John"
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Accept user invite event
When a user accepts an invitation to an organization by setting a password for the account, an event with the following data object is created.
Property Name | Type | Description |
---|---|---|
ref | String | User reference (SCIM location) |
organizationId | int | Organization Id |
organizationName | String | Organization name |
userId | String | User id |
userName | String | username |
userStoreName | String | User Store name |
Example accept user invite event payload:
{
"ref": "https://asgardeo.io/t/myorg/scim2/Users/72774617-8dff-472e-90b5-67069d94d299",
"organizationId": 3,
"organizationName": "myorg",
"userId": "72774617-8dff-472e-90b5-67069d94d299",
"userName": "[email protected]",
"userStoreName": "DEFAULT"
}
2
3
4
5
6
7
8
# Confirm self-signup event
When a user completes account verification during self sign-up, an event with the following data is created.
Property Name | Type | Description |
---|---|---|
ref | String | User reference (SCIM location) |
organizationId | int | Organization Id |
organizationName | String | Organization name |
userId | String | User id |
userName | String | username |
userStoreName | String | User Store name |
Example confirm self-signup event payload:
{
"ref": "https://asgardeo.io/t/myorg/scim2/Users/72774617-8dff-472e-90b5-67069d94d299",
"organizationId": 3,
"organizationName": "myorg",
"userId": "72774617-8dff-472e-90b5-67069d94d299",
"userName": "[email protected]",
"userStoreName": "DEFAULT"
}
2
3
4
5
6
7
8