Docs

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.

# Configure Asgardeo to publish events

Follow the steps below to configure event publishing for Asgardeo.

  1. On the Asgardeo Console, go to Develop -> Event Publishing
  2. Click Configure under Event Configuration.
  3. Select the events that you want to publish to Choreo and click Update
Asgardeo console UI for events

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 via Choreo

Follow the steps below to define a business logic that will trigger when an Asgardeo event occurs.

# Prerequisite

Choreo requires you to have a github repository to host the webhook logic. You can create the webhook from scratch or connect to an existing Ballerina repository. Visit Choreo docs (opens new window) to learn more.

# Create a webhook

  1. Navigate to Choreo (opens new window) and create an organization with the same name as your Asgardeo organization, if you don't have it already.

    Organizations in Asgardeo and Choreo will synchronize based on the organization name.

  2. Select the Default Project under All Projects. Alternatively, you can create a new project or use an existing project.

  3. Start creating a webhook in Choreo from the list of components. Learn more about webhooks in the Choreo documentation (opens new window).

    If you already have some components in the project, click on +Create button in the component list view.

    Create a Webhook in Choreo

  4. Enter a name and a description for your webhook, select External as the Access Mode and click Next.

    Enter general details for the Choreo webhook

  5. Authorize and connect the github repository and the branch. Since the webhook code needs to be placed in the root of the repository, leave the Path parameter as shown.

    Connect Github repository to Choreo

  6. Check the Start with a sample checkbox to create a pull request with the starter code required for the webhook and click Next.

  7. Select Asgardeo as the Trigger Type and click Next.

    Select Asgardeo trigger type

  8. Select one of the Asgardeo event types as the Trigger Channel and click Create. The available options are as follows:

    RegistrationService Listens to all user registration events in Asgardeo.
    UserOperationService Listens to all user operation events in Asgardeo.
    LoginService Listens to all user login events in Asgardeo.
    NotificationService Listens to all notification events of the organization from Asgardeo.

    Select Asgardeo trigger type

  9. After the webhook is created, Choreo will create a pull request in your connected Github repository with the sample starter code. Go to your repository and merge this code to complete the setup.

# Define the business logic

Let's set up a sample business use case in which Choreo prints a log whenever a registration event is generated in Asgardeo.

  1. Create a webhook with RegistrationService as the Trigger Channel.

  2. Navigate to your Github repository and open the webhook.bal file. Your boilerplate code may look as below.

    import ballerinax/trigger.asgardeo;
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? {
    //Not Implemented
    }
    remote function onConfirmSelfSignup(asgardeo:GenericEvent event ) returns error? {
    //Not Implemented
    }
    remote function onAcceptUserInvite(asgardeo:GenericEvent event ) returns error? {
    //Not Implemented
    }
}

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

  3. Define your business logic in the webhook.bal file.

    The following is a sample code that prints a log 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
    29

  4. Deploy your webhook (opens new window) with the business logic that you defined above.

  5. Perform an action in Asgardeo that will generate a registration event, such as onboarding a user (opens new window).

  6. Proceed to observe logs (opens new window) in your integrated console in Choreo.

# 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
    6

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

# 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"
   }
}
1
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"
}
1
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"
}
1
2
3
4
5
6
7
8

# 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"
}
1
2
3
4
5
6
7
8

# 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 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"
}
1
2
3
4
5
6
7
8

# User credential update event

When a user's credentials are updated, 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"
}
1
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"
}
1
2
3
4
5
6
7
8

# 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"
     }
   ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 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

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"
}
1
2
3
4
5
6
7
8
9
© 2023 WSO2 LLC.