Using OAuth to authorize Business Central web services (OData and SOAP)
Note
Azure Active Directory is now Microsoft Entra ID. Learn more
Business Central supports the OAuth authorization protocol for SOAP and OData web services. This article describes some basics behind the use and configuration of OAuth authentication in Business Central. It describes the general aspects of the OAuth authorization protocol, including how to set it up for Business Central.
Tip
For some samples about setting up OAuth, see the BCTech repo.
About OAuth
Note
Azure Active Directory is now Microsoft Entra ID. Learn more
OAuth is an open standard for authorizing access to web services and APIs from native clients and websites in Microsoft Entra ID. In Business Central, OAuth is useful when your deployment is configured for Microsoft Entra authentication, either through your own Azure subscription or a Microsoft 365 subscription. OAuth lets users sign in to Business Central web services using their Microsoft 365 or Microsoft Entra credentials. Otherwise, they would have to use their Business Central account credentials (user name and password or web access key).
Concepts in OAuth
Four parties are typically involved in an OAuth 2.0 authentication and authorization exchange, as illustrated in the following diagram from Azure. Such exchanges are often called authentication flows or auth flows.
For more information, see OAuth 2.0 Roles in the Azure documentation.
Authorization server
The Microsoft identity platform itself is the authorization server. Also called an identity provider or IdP, it securely handles the end-user's information, their access, and the trust relationships between the parties in the auth flow. The authorization server issues the security tokens your apps and APIs use for granting, denying, or revoking access to resources (authorization) after the user signs in (authenticated).
Client
The client in an OAuth exchange is the application requesting access to a protected resource. The client could be a web app running on a server, a single-page web app running in a user's web browser, or a web API that calls another web API. You often see the client referred to as client application, application, or app.
Resource owner
The resource owner in an auth flow is typically the application user, or end-user in OAuth terminology. The end-user "owns" the protected resource--their data--your app accesses on their behalf. The resource owner can grant or deny your app (the client) access to the resources they own. For example, your app might call an external system's API to get a user's email address from their profile on that system. Their profile data is a resource the end-user owns on the external system, and the end-user can consent to or deny your app's request to access their data.
Resource server
The resource server hosts or provides access to a resource owner's data. For OAuth authentication in Business Central, the resource server is the Business Central server. The resource server relies on the authorization server to perform authentication and uses information in bearer tokens issued by the authorization server to grant or deny access to resources.
Tokens
The parties in an authentication flow use bearer tokens to assure identification (authentication) and to grant or deny access to protected resources (authorization). Bearer tokens in the Microsoft identity platform are formatted as JSON Web Tokens (JWT).
Three types of bearer tokens are used by the Microsoft identity platform as security tokens:
- Access tokens - Access tokens are issued by the authorization server to the client application. The client passes access tokens to the resource server. Access tokens contain the permissions the client has been granted by the authorization server.
- ID tokens - ID tokens are issued by the authorization server to the client application. Clients use ID tokens when signing in users and to get basic information about them.
- Refresh tokens - The client uses a refresh token, or RT, to request new access and ID tokens from the authorization server. Your code should treat refresh tokens and their string content as opaque because they're intended for use only by authorization server.
For more information, see Security tokens in the Azure documentation.
App registration
Your client app needs a way to trust the security tokens issued to it by the Microsoft identity platform. The first step in establishing that trust is by registering your app with the identity platform in Microsoft Entra ID.
For more information, see App registration in the Azure documentation.
User account (user impersonation) or application account (service-to-service authentication)?
When setting up OAuth, the first decision you need to make is whether to use a user account or an application account.
The following table lists some of the differences between the two approaches.
| Area | User account (user impersonation) | Application account (service-to-service authentication) |
|---|---|---|
| User | Requires an interactive user to sign in | No interactive user sign-in needed |
| License | User must be licensed | Requires an application account in Business Central (no license needed) |
| Refresh token | After initial sign-in, a refresh token can be used to maintain access | No refresh token required |
| Permissions | Request is done with permissions assigned to the user | Request is done with permissions assigned to application account |
Using User Impersonation/Delegation Authentication
For delegation/user impersonation, a Business Central user has to consent to the resources which the client application requests access to.
Using Service-to-Service (S2S) Authentication
Service-to-Service (S2S) authentication is suited for scenarios where integrations are required to run without any user interaction. S2S authentication uses the Client Credentials OAuth 2.0 Flow. This flow enables you to access resources by using the identity of an application.
For more information, please visit Service-to-Service Authentication
Credentials lifetime
With authentication methods other than Microsoft Entra ID, like Windows or NavUserPassword, the credentials that users provide are persisted by application and used for as long as they're valid in Business Central. However, this is different for OAuth, because the security tokens that are used for authentication have a limited lifetime.
An authentication result from Microsoft Entra ID, contains two tokens: an access token and an ID token.
The access token is used when the client application calls the web service. The access token is relatively short-lived (for example, one hour by default, and one day maximum). When it expires, the client application needs a new access token.
To obtain new access token when the current access token expires, one can use token cache. For more information, see Acquire & cache tokens with Microsoft Authentication Library (MSAL).
The lifetime of both these tokens is configurable. For more information about how to configure and manage these tokens for your installation, see Configurable token lifetimes in Microsoft Entra ID.
Related information
Web services authentication
OData web services
Configuring Business Central server
Authentication and credential types