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. For more information, see 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 Failed (Pre Open Company): User is disabled.
  • Authorization Failed (Pre Open Company): User has no entitlements.
  • User has no access
  • 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_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:

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 Failed (Open Company): Invalid company name.
  • Authorization Failed (Open Company): User has no permission to company.
  • Authorization Failed (Open Company): The tenant is locked.
  • Authorization Failed (Open Company): The license has expired or the trial period has ended.
  • Authorization Failed (Open Company): The user's license is not valid for use on production companies.
  • Authorization Failed (Open Company): Error in OnOpenCompany trigger
Before version 16.1:
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:

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