Analyzing authorization trace telemetry

APPLIES TO: Business Central 2019 release wave 2 and later

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.

Tip


Before Business Central online logs authorization attempts to telemetry, a successful authentication (sign-in) must happen against Microsoft Entra ID. With the information in the Microsoft Entra sign-in log, you can figure out what happened if a user sign-in failed. Learn more in Analyze sign-ins with the Microsoft Entra sign-in log.

If you want to track, monitor, or alert on successful and failed sign-in attempts against Microsoft Entra ID, configure integration to Azure Monitor on Microsoft Entra and analyze further with KQL. Learn more in Integrate Microsoft Entra logs with Azure Monitor.

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 and run the OnOpenCompany trigger. The telemetry data indicates whether the company opened successfully or failed.

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

DimensionDescription or value
messageVersion 16.1 and later:
Authorization Succeeded (Pre Open Company)

Before Version 16.1:
Authorization steps prior to the open company trigger succeeded.
operation_NameAuthorization 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. In version 16.1 and later, use customDimensions.eventId in Kusto queries instead of operation_Name.
severityLevel1
user_IdThe 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

DimensionDescription or value
authorizationStatusSucceeded
clientTypeUnknownClient because the client type isn't known at this stage.
aadTenantIdSpecifies 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.
componentDynamics 365 Business Central Server.
componentVersionSpecifies the version number of the component that emits telemetry (see the component dimension.)
environmentNameSpecifies the name of the tenant environment. Learn more in Managing Environments.
environmentTypeSpecifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types.
entitlementSetIdsSpecifies the entitlements that the user has in Business Central.
eventIdRT0003
guestUsertrue indicates that the user is a guest user on the tenant.
false indicates the user belongs to the tenant.
telemetrySchemaVersionSpecifies the version of the Business Central telemetry schema.
userTypeSpecifies whether the user is a Delegated_admin, Internal_Admin, or Normal user. See UserType.

User types

ValueDescriptionSee more
Delegated_adminIndicates 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_AdminIndicates 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 userIndicates that the user is a normal user in the tenant, based on the license.Create Users According to Licenses

Note

The client type isn't known when the server emits RT0003. For RT0001, clientType is populated only if a session is available. You can join to RT0002 or RT0004 to get the client type for the company-opening stage.

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

DimensionDescription or value
messageVersion 16.1 and later: Authorization Failed (Pre Open Company): {reason}. Reasons include User is disabled., User has no entitlements., User has no access, and User is not a member of the environment's security group.

Before version 16.1:
Authorization steps prior to the open company trigger failed, see failureReason column for details.
operation_NameAuthorization 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. In version 16.1 and later, use customDimensions.eventId in Kusto queries instead of operation_Name.
severityLevel2

Custom dimensions

DimensionDescription or value
authorizationStatusFailed
clientTypeThe client type if a session is available; otherwise, an empty string.
entitlementSetIdsSpecifies the entitlements available for the user when authorization failed.
eventIdRT0001
failureReasonSpecifies why the sign-in failed. Learn more in Troubleshooting authorization failures.
guestUsertrue indicates that the user is a guest user on the tenant.
false indicates the user belongs to the tenant.
userTypeSpecifies 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. Learn more in 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. Learn more in 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:

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 groups 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. Learn more in 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

DimensionDescription or value
messageVersion 16.1 and later:
Authorization Succeeded (Open Company)

Before version 16.1:
Authorization steps in the open company trigger succeeded.
operation_NameAuthorization 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. In version 16.1 and later, use customDimensions.eventId in Kusto queries instead of operation_Name.
severityLevel1

Custom dimensions

DimensionDescription or value
authorizationStatusSuccess
aadTenantIdSpecifies 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.
clientTypeSpecifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyNameSpecifies the display name of the Business Central company for which the session was created.
companyIdSpecifies 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.)
componentDynamics 365 Business Central Server.
componentVersionSpecifies the version number of the component that emits telemetry (see the component dimension.)
environmentNameSpecifies the name of the tenant environment. Learn more in Managing Environments.
environmentTypeSpecifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types.
eventIdRT0004
guestUsertrue indicates that the user is a guest user on the tenant.
false indicates the user belongs to the tenant. This dimension was added in version 26.0.
resultSuccess
serverExecutionTimeSpecifies the amount of time it took the server to open the company. The time has the format hh:mm:ss.sssssss.
sqlExecutesSpecifies the number of SQL statements executed while opening the company.
sqlRowsReadSpecifies the number of table rows that were read by the SQL statements**.
telemetrySchemaVersionSpecifies the version of the Business Central telemetry schema.
totalTimeSpecifies the amount of time it took to open the company**. The time has the format hh:mm:ss.sssssss.
userTypeSpecifies whether the user is a Delegated_admin, Internal_Admin, or Normal user. See UserType. This dimension was added in version 26.0.

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

DimensionDescription or value
messageVersion 16.1 and later (depending on the cause):<ul><li>Authorization Failed (Open Company): Invalid company name.</li><li>Authorization Failed (Open Company): User has no permission to company.</li><li>Authorization Failed (Open Company): The tenant is locked.</li><li>Authorization Failed (Open Company): The license has expired or the trial period has ended.</li><li>Authorization Failed (Open Company): The user's license is not valid for use on production companies.</li><li>Authorization Failed (Open Company): Error in OnOpenCompany trigger</li></ul>Before version 16.1:
Authorization steps in the open company trigger failed, see failureReason column for details.
operation_NameAuthorization 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. In version 16.1 and later, use customDimensions.eventId in Kusto queries instead of operation_Name.
severityLevel3

Custom dimensions

DimensionDescription or value
statusFailed
companyNameSpecifies the name of the company that the user tried to open.
companyIdSpecifies 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.)
failureReasonSpecifies why the sign-in failed. Learn more in Troubleshooting company-opening authorization failures.
eventIdRT0002
guestUsertrue indicates that the user is a guest user on the tenant.
false indicates the user belongs to the tenant. This dimension was added in version 26.0.
userTypeSpecifies whether the user is a Delegated_admin, Internal_Admin, or Normal user. See UserType. This dimension was added in version 26.0.

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 user's permissions to give them access to the company. Learn more in 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 Business Central tenant license state is locked. It doesn't refer to an individual user's Microsoft Entra account being locked.

Resolution

Contact Microsoft Support for help resolving the tenant's locked state.

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. Learn more in 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. Learn more in 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 company-opening sign-in 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 database

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

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:

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 )

Monitoring and Analyzing Telemetry
Enable Sending Telemetry to Application Insights