Diagnostic logs

# Diagnostic logs

Diagnostic logs in Asgardeo are designed to help developers diagnose and troubleshoot issues that occur when using Asgardeo features such as onboarding applications, and configuring authentication flows. Furthermore, support engineers can also use logs to troubleshoot user issues.

Potential risks of including PII in query parameters

Including Personally Identifiable Information (PII) in query parameters can pose security and privacy risks. These can be in the form of plain text or embedded in jwt tokens. Asgardeo logs these query parameters to uphold security, compliance, and auditing standards, as well as to fulfill other legal obligations.

Therefore, any PII sent as query parameters will be logged in our server access logs. This means that sensitive information, such as names, email addresses, or other personal data, may be recorded and stored as part of routine system operations.

To mitigate the risk of exposing PII, we strongly recommend encrypting such information when sending as query parameters or consider sending such information in the request body.

By using Asgardeo, you acknowledge and understand these potential risks, and you are encouraged to follow the guidance provided here to ensure data security and privacy for your data. If you have any questions or require guidance on handling sensitive information securely within our system, reach out to our support team at [email protected].

For more information on how to analyze diagnostic logs, refer analyze logs.

# Access diagnostic logs

To access audit logs:

On the Asgardeo Console, go to Log
Switch to the Diagnostic tab.

By default, the console displays logs that occurred in the last 15 minutes.

# Search for logs

You can use the search bar to search for logs based on the Trace ID, Action ID, Client ID, Result Message or the Result Status. Learn more about these parameters in the structure of logs section.

For example, the diagram below shows the results for a search based on the Result Message.

# Add custom logs to authentication scripts

In addition to the logs generated by Asgardeo, organization administrators can define their own logs when setting up conditional authentication scripts. This is helpful when you need additional information to troubleshoot an application issue.

Custom logs are marked by the </> icon in the logs portal.

There are three types of custom logs that you can define in conditional authentication as explained below.

# Info logs

Info logs are used to log additional information related to a flow. You can define info logs using the utility function Log.info().

For example, an application developer sets up the following info log in the conditional authentication script to verify which user groups are allowed to log in.

.....
var allowedGroups = ['Supplier'];
Log.info('Allowed groups: ' + allowedGroups.toString());
.....

1
2
3
4

Once a user attempts to log in, this information is logged in the logs portal as shown below.

# Debug logs

Debug logs can be used to check the status of a condition defined in the conditional authentication script. You can define debug logs using the utility function Log.debug().

For example, an application developer sets up a debug log in the conditional authentication script to determine whether the first step of a login attempt succeeded.

...
executeStep(1, {
    onSuccess: function (context) {
        Log.debug('first step successful'); 
    }
})
...

1
2
3
4
5
6
7

Once a user succeeds the first login step, the debug log appears in the logs portal as shown below.

Debug logs in conditional authentication

# Error logs

Conditional authentication scripts can generate two types of error logs in the logs portal.

Application errors that occur due to syntax errors in the conditional authentication script.

For example, your conditional authentication script may have a syntax error that the editor does not flag as shown below.
```
.....
var allowedGroups = ['Supplier'];
Log.info('Allowed groups: ' + alowedGroups.toString());
.....
```
1
2
3
4
Once a user attempts to log in, the error is logged in the logs portal as shown below.

Custom errors that you define using the utility function Log.error().

For example, an application developer sets up an error log in the conditional authentication script to identify when a user outside the allowed user groups tries to log in.

var allowedGroups = ['Supplier'];
...
executeStep(1, {
onSuccess: function (context) {
    var user = context.currentKnownSubject;
    var isMember = isMemberOfAnyOfGroups(user, allowedGroups);
    if(!isMember){
        Log.error(user.username + ' is not a member of the groups: ' + allowedGroups.toString());
    } }
})
...

1
2
3
4
5
6
7
8
9
10
11

Once an unauthorized user attempts to log in, the error is logged in the logs portal as shown.

Error logs in conditional authentication

# Structure of logs

The following table explains some of the common properties found in Asgardeo logs.

Property	Description
id	Unique ID for each log event
recordedAt	Timestamp at which the event occurs
traceId	Unique ID to correlate the log event to a specific request
flowId	Unique ID to correlate the log event to a specific flow
input	Parameters applicable for the action. This can be either request parameters or method parameters or request headers.
resultStatus	Status of the action. Either `Success` or `Failed`
resultMessage	Description of the result status. E.g. reason for the failure.
actionId	A unique ID to identify a specific action performed by the system.
configurations	System configurations relevant to the action (This can be UI / organization / system level configurations).

# Sample scenarios

The following scenarios describe how you can use logs to troubleshoot some common issues that occur when using Asgardeo.

# Application onboarding

Follow the steps below to observe an application error log due to incorrect client credentials.

Onboard an application to Asgardeo but provide incorrect client credentials when configuring the application.
Attempt to log in to the application with a user account. An error will occur in the application.
Go to the logs portal on the Asgardeo Console and observe the following error log.

# Conditional authentication

Follow the steps below to observe an application error log due to not meeting the conditions of an authentication script.

Onboard an application to Asgardeo.
Restrict login to anyone outside the employee group using group-based access control.
Define a custom error log in the authentication script.
Log in to the application with a user account not belonging to the employee group. An error will occur in the application.
Go to the logs portal on the Asgardeo Console and observe the following error log.