Web Services Authentication
Note
Azure Active Directory is now Microsoft Entra ID. Learn more
When users send a request for a web service, they're authenticated according to the credential type that is configured for Business Central Server. To access a web service, users must provide valid credentials for the credential type being used. If Business Central is configured for Windows credential type, then users are automatically authenticated against the Windows account that their computer is running under. In this case, they aren't prompted for their credentials. For other credential types, users are prompted to enter a user name and password.
Important
Starting October, 2022, the use of access keys (Basic Auth) for web service authentication is deprecated and not supported in Business Central online. We recommend that you use OAuth2 instead. For more information, see Using OAuth to Authorize Business Central Web Services.
Difference between Basic Authentication and OAuth
The following table shows the main difference between basic authentication with web service keys and OAuth.
| Area | Basic Authentication (web service access keys) | OAuth |
|---|---|---|
| User | Linked to an interactive user account | Supports both interactive and non-interactive accounts |
| License | Always needs a licensed user | No license required for service-to-service integrations |
| Security server | Business Central manages security | Security managed by Microsoft Entra ID |
| Multi-factor authentication | No multi-factor authentication support | Fully supports multi-factor authentication |
| Secret validity | Password exposed in HTTP request (no expiration date) | HTTP requests contain a short-lived access token |
How to use an Oauth for SOAP and OData Web Service Authentication
Business Central supports the OAuth authorization protocol for SOAP and OData web services. OAuth is the recommended authentication method for all Business Central web service endpoints.
For more information, see Using OAuth to Authorize Business Central Web Services.
About NavUserPassword and AccessControlService credential types
If your solution uses NavUserPassword or AccessControlService as the credential type, users can access data through SOAP and OData web services by specifying a password or access key. You set up the user accounts in the Business Central client, based on how they'll access Business Central data. For example, if you set up a user account that will allow an external application to read Business Central data through a web service, you can generate a web service access key and specify the key for the relevant user accounts. Then, you add the access key to the configuration of the application that consumes the web service. In contrast, when users access Business Central data through a web service in Microsoft Excel, for example, they specify a password instead of a web service access key.
Business Central also supports OAuth authentication on OData and SOAP endpoints. OAuth is an open standard for authorization that provides client applications with secure delegated access to server resources. OAuth enables you to extend single sign-on with Microsoft 365 to Business Central web services. For more information, see Using OAuth to Authorize Business Central Web Services (OData and SOAP).
Important
If the Business Central Server is configured to use NavUserPassword or AccessControlService authentication, then the username, password, and access key can be exposed if the SOAP or OData data traffic is intercepted and the connection string is decoded. To avoid this condition, configure SOAP and OData web services to use Secure Socket Layer (SSL).
About UserName credential type
For OData, UserName credential type is only supported in Business Central version 20 and earlier. In later versions, change to NavUserPassword instead. This implies deprecation of native Digest Authentication from version 21 onwards.
Unicode characters in user name or password
When Business Central data is consumed by a web service, users can't be authenticated if their user name or password contains Unicode characters. This condition is a limitation in the basic authentication mechanism that is defined in the HTTP/1.1 specification.
The same limitation applies to exposing Business Central data in external products such as a browser or a Microsoft .NET Framework assembly.
How to use an Access Key for SOAP and OData Web Service Authentication (deprecated)
If your solution is configured for NavUserPassword or AccessControlService authentication, then you can configure Business Central user accounts to include an access key that can be used instead of a password to authenticate SOAP and OData web service requests. A web service access key is a random 44 character string that is associated with the user account. Because it can only be used for SOAP and OData web services, it doesn't require the same level of protection as a password.
Important
Starting October, 2022, the use of access keys (Basic Auth) for web service authentication is deprecated and not supported in Business Central online. We recommend that you use OAuth2 instead. For more information, see Using OAuth to Authorize Business Central Web Services.
Generate a Web Service Access Key
Follow these instructions to generate a web service access key for a user. You perform these steps from the user setup in Business Central client.
Choose the
icon, enter Users, choose the related link, and then open the user account that you want to edit.In the Web Service Access section, select the Web Service Access Key field.
In the Set the Web Service Access Key window, if you don't want the key to expire, select the Key Never Expires check box. If you want the key to expire, set the Key Expiration Date field to the date.
Choose the OK button.
The access key is automatically generated. If you're signed in as the user that you modified, the key appears in the Web Service Access Key field. Otherwise, the key is masked so only asterisks (*) are shown.
Implement the Web Service Access Key
Typically, you would create a user account strictly for web services. Then use the account's credentials, which include the user name and access key, in a web service application. For example, if you develop your own web service application, then you can design your application to programmatically pass the credentials to the web service. Some applications let you provide the connection credentials through a user interface. The steps for implementing the web service access key are done in Business Central client.
Create a user specifically for web services.
For more information, see Manage Users and Permissions.
Sign in as the new user, and generate a web service access key in the user account.
Use the access key in the web service application.
To See Learn how to use code to pass the user name and web access key to a web service Passing Credentials for Authentication to Web Services
See Also
Web Services Overview
SOAP Web Services
OData Web Services
Authentication and Credential Types
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for