Setting up Oauth2 for OnPrem services

Prerequisites

• SSL enabled on the BC Instance

• Service with Credential Type NavUserPassword or AAD

Create the App Registration

Create new App Registration, in the wizard do this:

• Name: Indifferent

• Supported Account Types: Usually Single Tenant

• Redirect URI:

o Type: Wen

o Url: https:// <domain or computer name >/ <webserver-instance >/SignIn

Then click Create

Note
If you need to setup Multiple environments (like prod and test) you can use the same app registration. After the creation of the app, you can go to the Authentication page and also add the other environment URL like descripted in the Redirect URL

Go to Expose an API, in the upper part click on “set” near “Application ID Uri”. Here you can leave the default value or you can customize it as you want e.g.: “api://contoso.bc”

Setting up BC Service

Edit the following configurations as follow:

Parameter	Value
ClientServicesCredentialType	Choose Between NavUserPassword or AccessControlService. NavUserPassword allows using both database username / password and AAD login. This can be convenient if you want to keep a web client with database user authentication or to publish apps from VS Code with the standard username & password authentication. AccessControlService only supports AAD authentication. The web client must be configured for AAD login. This also applies to publishing apps from VS Code.
WSFederationLoginEndpoint	The URL to the Azure login page. The base URL has the format https://login.microsoftonline.com/[AAD Tenant Id]/wsfed This URL can also be found under "WS-Federation sign-on endpoint" at the Endpoints page that can be opened from the Overview page of the Azure app registration. ALWAYS use the Aad Tenant Id in the form of a guid. This can also be found on the overview page of the Azure app registration under Direction (tenant) ID. The URL must also include these parameters: wa=wsignin1.0 wtrealm=Application ID URI wreply=Redirect URL The parameters must be URL-encoded. Combined the full URL looks like: https://login.microsoftonline.com/[AAD Tenant Id]/wsfed? wa=wsignin1.0%26wtrealm=[Application ID URI] %26wreply=[Redirect URL] The redirect URL may contain a parameter {HOSTNAME} instead of the full hostname, like: https://{HOSTNAME}/BC/SignIn
ClientServicesFederationMetadataLocation	The federation metadata contains information that is used to create trusts or identify token-signing certificates. The format of the URL is https://login.microsoftonline.com/[Azure Tenant ID]/federationmetadata/2007-06/federationmetadata.xml The URL can be obtained from the Endpoints page that can be opened from the Overview page of the Azure app registration.
DisableTokenSigningCertificateValidation	Disable token signing certificate validation when configuring Azure Active Directory authentication with single sign-on.
ExtendedSecurityTokenLifetime	Specifies the number of hours that are added to the lifetime of Azure AD security tokens, which are used to authenticate client users. When the lifetime expires, the client is disconnected from the server instance. An event with a message such as "The SAML2 token is invalid because its validity period ended." is recorded in the event log for the server instance. In general, the lifetime of security tokens is 1 hour. Valid range: 0 to 24 hours Recommended value: 8 hours or higher

Note
If you want to use AAD for the WebClient you must execute this powershell command: Set-NAVWebServerInstanceConfiguration -WebServerInstance [Server Instance] -KeyName ClientServicesCredentialType -KeyValue "AccessControlService"

Note

If you want to use AAD for the WebClient you must execute this powershell command:

Set-NAVWebServerInstanceConfiguration -WebServerInstance [Server Instance] -KeyName

ClientServicesCredentialType -KeyValue "AccessControlService"

Configure the Scopes (delegated and application)

We have now to setup the scopes for our App Registration. This Is needed for allowing the authentication for the BC Web Services.

Go to the App Registration and click on “Expose an API” (where you have defined the Application ID Uri) and add a scope:

• Scope Name: user_impersonation

• Who can Consent: admins and users

• Admin Consent Display Name: full access to web services API

• Admin Consent Description: grants full access to the Business Central web services APIs. These APIs provide the capability to call web services APIs and modify Business Central data.

• User Consent Display Nme: full access to web services API

• User Consent description: grants full access to the Business Central web services APIs. These APIs provide the capability to call web services APIs and modify Business Central data.

Set this to enabled and Add scope

Note
Allowed Scopes here are user_impersonation and Financials.ReadWrite.All

Now your bc instance can authenticate all delegated flows

If you want to enable also the Application flows you have to setup this.

Go to “App Roles” and create a new role:

• Display Name: full access to web services API

• Allowed Member types: applications

• Value: (this is case sensitive) API.ReadWrite.All

• Description: grants full access to the Business Central web services APIs. These APIs provide the capability to call web services APIs and modify Business Central data.

Then click Apply

Note
Allowed values here are API.ReadWrite.All and Automation.ReadWrite.All

Now your bc instance can authenticate all application flows

Now to use Oauth on OnPrem, you have to create a normal App registration (like the one for MDI) and when you need to add the API Permission use the ones under “My APIs” (you should see your app registration name, the one used to configure the bc service)

Example (test from postman):

create a new App Registration, add the redirect uri as Mobile and desktop applications and https://login.microsoftonline.com/common/oauth2/nativeclient as redirect URI

Go to API Permissions, add new permission. On the page that opens, click on the group My APIs, look for your app registration and then choose between “Delegated” or “Application” based on what you want to do!