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. 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 Monitoring > Events.
Select the events that you wish to publish to Choreo and click Update.

Info

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, 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.
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.

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 {}

Commit 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 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.

Info

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.
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.

Note

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.

Info

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"
}

Event 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.

These are events related to login flows. The event data objects of login events are defined below.

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
`initiatorType`	String	Initiator of the event. `admin` : Indicates that an administrative action initiated the event `user` : 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
`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"
    }
    ]
}

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"
    }
}

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"
}

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
`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"
}

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"
     }
   ]
}

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"
}

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"
}

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"
   }
}

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"
}

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"
}