Analyzing Authorization Trace Telemetry
APPLIES TO: Business Central 2019 release wave 2 and later
Note
Azure Active Directory is now Microsoft Entra ID. Learn more
Authorization telemetry provides information about the authorization of users (or services) when trying to sign in to Business Central. This telemetry data can help you identify problems a user (or a service) might experience when signing in.
Authorization signals are emitted in two stages of sign-in. The first stage is the initial authorization, before the CompanyOpen trigger is run. In this stage, the system verifies that the user account is enabled in the tenant and has the correct entitlements. The telemetry data includes:
- Success or failure of the sign-in attempt
- Reason for failure
- Type of user (such as normal, administrator, or delegated user)
- Whether the user belongs to the tenant or is an invited user
The next stage occurs after a successful authorization attempt, when trying to open the company (that is, when the CompanyOpen trigger run). The telemetry data indicates whether the company opened successfully or failed (for some reason).
Note
Business Central 2020 release wave 1, version 16.1, introduces changes to some operation_Name and message dimension values. The differences from earlier versions are indicated in the following sections.
Authorization Succeeded (Pre Open Company)
Occurs when a user has been successfully authorized. This data is not emitted for on-premises environments.
General dimensions
| Dimension | Description or value |
|---|---|
| message | Version 16.1 and later: Authorization Succeeded (Pre Open Company) Before Version 16.1: Authorization steps prior to the open company trigger succeeded. |
| operation_Name | Authorization Succeeded (Pre Open Company) Note: The use of the operation_Name column was deprecated in version 16.1. In future versions, data won't be stored in this column. So in version 16.1 and later, use the custom dimension column eventID column custom in Kusto queries instead of operation_Name. |
| severityLevel | 1 |
| user_Id | The user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. Learn more in Assign a telemetry ID to users. |
Custom dimensions
| Dimension | Description or value |
|---|---|
| authorizationStatus | Succeeded |
| aadTenantId | Specifies the Microsoft Entra tenant ID used for Microsoft Entra authentication. For on-premises, if you aren't using Microsoft Entra authentication, this value is common. |
| component | Dynamics 365 Business Central Server. |
| componentVersion | Specifies the version number of the component that emits telemetry (see the component dimension.) |
| environmentName | Specifies the name of the tenant environment. See Managing Environments. |
| environmentType | Specifies the environment type for the tenant, such as Production, Sandbox, Trial. See Environment Types |
| entitlementSetIds | Specifies the entitlements that the user has in Business Central. |
| eventId | RT0003 |
| guestUser | true indicates that the user is a guest user on the tenant. false indicates the user belongs to the tenant. |
| telemetrySchemaVersion | Specifies the version of the Business Central telemetry schema. |
| userType | Specifies whether the user is a Delegated_admin, Internal_Admin, or Normal user. See UserType. |
UserType
| Value | Description | See more |
|---|---|---|
| Delegated_admin | Indicates that the user is a delegated administrator on the tenant. Delegated administrators are typically reserved for partners. Delegated administrator privileges are granted to users by the customer. You grant these privileges by setting up a Partner Relationship in the Microsoft Partner Center. | Delegated Administrator Access to Business Central Online Customers delegate administration privileges to partners |
| Internal_Admin | Indicates that the user is an internal administrator on the tenant. As an internal administrator, the user is typically assigned the Dynamics 365 Administrator or Dynamics 365 Business Central Administrator role in the Microsoft 365 admin center. | Administration as an internal administrator in Business Central Assign admin roles in Microsoft 365 admin center |
| Normal user | Indicates that the user is a normal user in the tenant, based on the license. | Create Users According to Licenses |
Note
The client type is not known when the server emits the pre-open company events (RT0001 and RT0003). You need to join to data for the events RT0002/RT0004 if you need both userType and clientType.
Authorization Failed (Pre Open Company)
Occurs when a user sign-in has failed authorization. This data is not emitted for on-premises environments.
General dimensions
| Dimension | Description or value |
|---|---|
| message | Version 16.1 and later (depending on the cause):
Authorization steps prior to the open company trigger failed, see failureReason column for details. |
| operation_Name | Authorization Failed (Pre Open Company) Note: The use of the operation_Name column was deprecated in version 16.1. In future versions, data won't be stored in this column. So in version 16.1 and later, use the custom dimension column eventID column custom in Kusto queries instead of operation_Name. |
| severityLevel | 3 |
Custom dimensions
| Dimension | Description or value |
|---|---|
| authorizationStatus | Failed |
| failureReason | Specifies why the sign-in failed. See Troubleshooting failures section for details. |
| guestUser | true indicates that the user is a guest user on the tenant. false indicates the user belongs to the tenant. |
| eventId | RT0001 |
| userType | Specifies whether the user is a Delegated_admin, Internal_Admin, or Normal user. See UserType. |
Troubleshooting (Pre Open Company) authorization failures
The user was successfully authenticated in Microsoft Entra ID but the user account is disabled in Business Central.
This message occurs when the user's account is valid, but the account is disabled. If you open the user account in Business Central, you'll see the State field is set to Disabled.
Resolution
Enable the user account by setting the State field to Enabled. For more information, see Create Users According to Licenses.
A user successfully authenticated in Microsoft Entra ID but the user does not have any entitlements in Business Central.
This message occurs if the user has an account, but the account hasn't been assigned any entitlements.
Entitlements are part of the license. Entitlements are permissions that describe which objects in Business Central a user can use, according to their Microsoft Entra role or license. For an explanation of entitlements, see Business Central entitlements explained
Resolution
Entitlements are assigned to the user account in the Microsoft 365 admin center or Microsoft Partner Center. They aren't assigned in Business Central. To assign entitlements to a user, see one of the following articles:
From Microsoft 365 admin center, see Add users individually or in bulk to Microsoft 365.
From the Microsoft Partner Center, see User management tasks for customer accounts.
The user is not a direct/indirect member of the security group associated with the environment, or the group does not exist, hence restricting the user access to the environment
In Microsoft Entra ID, you can create security that include users that you want to give access to your environments. Then, from the Business Central Admin center, you can associate the groups with your environments. This error occurs if the user who tries to sign in isn't a member of the security group, or the security group assigned to the environment doesn't exist in Microsoft Entra ID. For more information, see Managing Production and Sandbox Environments in the Admin Center.
Authorization Succeeded (Open Company)
Occurs when the company has opened successfully. This data is emitted both for online and on-premises environments.
General dimensions
| Dimension | Description or value |
|---|---|
| message | Version 16.1 and later: Authorization Succeeded (Open Company) Before version 16.1: Authorization steps in the open company trigger succeeded. |
| operation_Name | Authorization Succeeded (Open Company) Note: The use of the operation_Name column was deprecated in version 16.1. In future versions, data won't be stored in this column. So in version 16.1 and later, use the custom dimension column eventID column custom in Kusto queries instead of operation_Name. |
| severityLevel | 1 |
Custom dimensions
| Dimension | Description or value |
|---|---|
| authorizationStatus | Success |
| aadTenantId | Specifies the Microsoft Entra tenant ID used for Microsoft Entra authentication. For on-premises, if you aren't using Microsoft Entra authentication, this value is common. |
| clientType | Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type. |
| companyName | Specifies the display name of the Business Central company for which the session was created. |
| companyId | Specifies the ID of the Business Central company for which the session was created. This dimension is available from version 25 (and was backported to versions 22, 23, and 24, where it is available in the latest CU.) |
| component | Dynamics 365 Business Central Server. |
| componentVersion | Specifies the version number of the component that emits telemetry (see the component dimension.) |
| environmentName | Specifies the name of the tenant environment. See Managing Environments. |
| environmentType | Specifies the environment type for the tenant, such as Production, Sandbox, Trial. See Environment Types |
| eventId | RT0004 |
| result | Success |
| serverExecutionTime | Specifies the amount of time it took the server to open the company. The time has the format hh:mm:ss.sssssss. |
| sqlExecutes | Specifies the number of SQL statements that the report executed. |
| sqlRowsRead | Specifies the number of table rows that were read by the SQL statements**. |
| telemetrySchemaVersion | Specifies the version of the Business Central telemetry schema. |
| totalTime | Specifies the amount of time it took to open the company**. The time has the format hh:mm:ss.sssssss. |
** From telemetrySchemaVersion 0.6 and onwards, this value also includes the CompanyOpen operation.
Authorization Failed (Open Company)
Occurs when a company has failed to open. This data is emitted both for online and on-premises environments.
General dimensions
| Dimension | Description or value |
|---|---|
| message | Version 16.1 and later (depending on the cause):
Authorization steps in the open company trigger failed, see failureReason column for details. |
| operation_Name | Authorization Failed (Open Company) Note: The use of the operation_Name column was deprecated in version 16.1. In future versions, data won't be stored in this column. So in version 16.1 and later, use the custom dimension column eventID column custom in Kusto queries instead of operation_Name. |
| severityLevel | 3 |
Custom dimensions
| Dimension | Description or value |
|---|---|
| authorizationStatus | Failed |
| companyName | Specifies the name of the company that the user tried to open. |
| companyId | Specifies the ID of the company that the user tried to open. This dimension is available from version 25 (and was backported to versions 22, 23, and 24, where it is available in the latest CU.) |
| failureReason | Specifies why the sign-in failed. See Troubleshooting failures section for details. |
| eventId | RT0002 |
Troubleshooting (Open Company) authorization failures
The company name is not valid, because the name is either empty or exceeds the maximum allowed length.
This message occurs when a user tries to sign in to a company whose name exceeds the maximum allowed length.
Resolution
This message typically occurs when a user tries to access a specific company in Business Center by entering a URL in the browser address, for example, https://businesscentral.dynamics.com/?company=CRONUS%20International%20Ltd.. If the name exceeds 30 characters, then this message occurs. Make sure that the user has the proper name of the company.
The user does not have permission to access the company.
This message occurs when a user account in Business Central doesn't have the proper permissions to the company.
Resolution
In Business Central, open the user account and modify the permissions the user to give them access to the company. For more information, see Assign Permissions to Users and Groups.
Tip
A good starting point is to look at the Effective Permissions that the user has on the company. You can do this from the user card by selecting Effective Permissions and setting the Company to the company in question.
The company doesn't exist.
This message occurs when a user tries to sign in to a company, but the company isn't found in Business Central.
Resolution
This message typically occurs when a user tries to access a specific company in Business Center by entering a URL in the browser address, for example, https://businesscentral.dynamics.com/?company=CRONUS%20International%20Ltd.. Make sure that the user has the proper name of the company.
User cannot open the company because the tenant is locked.
This message indicates that the tenant has been locked by Microsoft, typically for security reasons like preventing repeated malicious sign-in attempts. The tenant isn't accessible by any user.
Resolution
For help with resolving this issue, read the following articles or contact Microsoft Support:
Troubleshoot account lockout problems with a Microsoft Entra ID Domain Services managed domain
"It looks like your account has been blocked" error when signing in to Microsoft 365
The user can't sign in to the company because the assigned license has expired or the trial period has ended.
This message occurs for one the following reasons:
- The license being used has expired.
- The license was trial license and the trial period has ended. Trial licenses are typically assigned when customers subscribe for an evaluation version by using self-service sign-up (also known as IW or viral sign-up). This license has a time limit.
Resolution
Renew the existing license or obtain a new license. Licenses are purchased through the Cloud Solution Provider (CSP) program. For more information, see the Cloud Service Provider site and the Microsoft Dynamics 365 Business Central Licensing Guide.
You can't open the company, because it is a production company. Your license isn't valid for use on production companies.
This message occurs because the license doesn't allow the user to open production companies. For example, the user may be using a trial license that is only valid on the evaluation version.
Resolution
Obtain a license that can be used on production companies. Licenses are purchased through the Cloud Solution Provider (CSP) program. For more information, see the Cloud Service Provider site and the Microsoft Dynamics 365 Business Central Licensing Guide.
Error in OnOpenCompany trigger
This message occurs when AL code causes an error during the OnOpenCompany trigger or event.
Resolution
Because AL code can trigger any type of error, the resolution will depend on the executed AL code. See the failureReason dimension for a callstack to determine where the error occurred.
Troubleshooting (Open Company) login performance
The events OnCompanyOpen and OnCompanyOpenCompleted are raised every time a session is created. Only when the code for all event subscribers on these events has completed can the session start running AL code. Until code has completed, the session creation process will wait. For interactive sessions, the user will see a spinner. Web service calls (SOAP, OData, or API) or background sessions (job queue, scheduled tasks, page background tasks) will not start running.This behavior means that you must design such code in a way that is minimally intrusive, for example, set low timeouts for outgoing web service calls.One or more of these operations typically are involved in a performance issue on logins:
1. Calls to external services
2. Long running SQL calls to the databaseIf you have enabled telemetry for your environment or app, you can use this KQL query to analyze how session creation time is delayed by calls to external services.Kusto traces | where timestamp > ago(1d) // adjust as needed | where customDimensions.eventId == 'RT0019' | where isnotempty( customDimensions.alStackTrace ) // RT0019 only has stacktrace from 20.1 | extend StackTrace = tostring( customDimensions.alStackTrace ) , executionTimeInMs = toreal(totimespan(customDimensions.serverExecutionTime))/10000 //the datatype for executionTime is timespan | where StackTrace has 'OnCompanyOpen' or StackTrace has 'OnCompanyOpenCompleted' | summarize count() // how many calls , sum(executionTimeInMs) // sum of delays for session creations (all session types are affected: UI, web service, background, ...) , avg(executionTimeInMs) // average session creation time delay by this app , max(executionTimeInMs) // average session creation time delay by this app by // which app is calling out from OnCompanyOpen/OnCompanyOpenCompleted? extensionId = tostring( customDimensions.extensionId ) , extensionName = tostring( customDimensions.extensionName ) , extensionVersion = tostring( customDimensions.extensionVersion ) // session type: UI, web service, background, ... , clientType = tostring( customDimensions.clientType ) Use this KQL query to analyze how session creation time is delayed by calls to the database:Kusto traces | where timestamp > ago(1d) // adjust as needed | where customDimensions.eventId == 'RT0005' | where isnotempty( customDimensions.alStackTrace ) // RT0019 only has stacktrace from 20.1 | extend StackTrace = tostring( customDimensions.alStackTrace ) , executionTimeInMs = toreal(totimespan(customDimensions.executionTime))/10000 //the datatype for executionTime is timespan | where StackTrace has 'OnCompanyOpen' or StackTrace has 'OnCompanyOpenCompleted' | summarize count() // how many calls , sum(executionTimeInMs) // sum of delays for session creations (all session types are affected: UI, web service, background, ...) , avg(executionTimeInMs) // average session creation time delay by this app , max(executionTimeInMs) // average session creation time delay by this app by // which app is querying the database extensionId = tostring( customDimensions.extensionId ) , extensionName = tostring( customDimensions.extensionName ) , extensionVersion = tostring( customDimensions.extensionVersion ) // session type: UI, web service, background, ... , clientType = tostring( customDimensions.clientType ) )
See also
Monitoring and Analyzing Telemetry
Enable Sending Telemetry to Application Insights