How to: Set Up Basic Authentication for Web Services

In this article

To set up a service tier that supports Web Service Access Key

The support for Windows Authentication in Business Central is marked as OnPrem and cannot be accessed by cloud compliant apps. Therefore, LS Retail is forced to remove Windows Authentication for Web Services, the final step to make LS Central Universal Code Compliant by setting the Target to Cloud in the app.json file.

Web Services must use either Web Service Access Key or OAuth authentications:

  • Web Service Access Key (only available On-premises) is only supported by service tiers where Credential Type is set to NavUserPassword.
  • OAuth2 (available On-premises and in SaaS) is only supported by service tiers where Credential Type is set to AccessControlService.

The most common way to authenticate normal users is to use Windows Authentication. This is still available by setting up a Service Tier where Client Credential Type is set to Windows.

In the following, the POS environment is the web service client and the Head Office is the web service server. It is the web service server that authenticates the web service client call.

Note: The POS environment can always be set up with a Service Tier Client Credential Type=Windows.

To set up a service tier that supports Web Service Access Key

Note: If you are testing or developing and need to run a web service and want to use the Web Service Access Key, you must set up a service tier for the Head Office environment where Client Credential=NavUserPassword.

You have three options to set up the database with a Client Credential that is NavUserPassword:

  1. Use Update Service, and select the LS Central Development Snapshot - NavUserPassword option to install. This NavUserPassword service tier is created automatically.

  2. Use the Self Service set up page to create a Branch to Container. An admin user is created automatically and that admin user is the user for the NavUserPassword setup.

  3. Use Update Service, and create a database in a normal way. After that you can use the script below.

If you are using Update Service for LS Central, then most likely you already have a service tier with Client Credential=Windows.

The easiest way to create a new service tier with Client Credential=NavUserPassword is as follows:

  1. Set up a second service tier by running the below script.
    Before you run the script, replace the parameter for $ExistingInstanceName with the name of your existing service tier.
    This will set up a second service tier where Client Credential=NavUserPassword.
    Note: You might need to change this script based on your current environment/requirements.
    Copy
    $ErrorActionPreference = 'stop'
    $ExistingInstanceName = 'Enter your existing instance name here'
    $BcServer = Get-UscInstalledPackage -PackageId 'bc-server' -InstanceName $ExistingInstanceName
    $Arguments = @{
        "bc-server" = @{
            ConnectionString = $BcServer.Info.ConnectionString
            DeveloperServicesEnabled = 'true'
            AllowForceSync = 'true'
            ClientServicesCredentialType = 'NavUserPassword'
            AllowSessionCallSuspendWhenWriteTransactionStarted = 'true'
            NoDatabaseUpgrades = 'true'
            PortSharing = 'true'
        }
        "bc-web-client" = @{
            ClientServicesCredentialType = 'NavUserPassword'
        }
    }
    $Packages = @(
        @{ Id = 'bc-server'; VersionQuery = $BcServer.Version}
        @{ Id = 'bc-web-client'; VersionQuery = $BcServer.Version}
    )
     $Packages | Install-GocPackage -InstanceName 'Enter the new web service instance name here' -UpdateStrategy 'Manual' -Arguments $Arguments -UpdateInstance 
  2. Login with your Windows user name, and create a User with a Nav user password,
  3. Login as the Nav user, and copy the Web Service Access Key value.
  4. In the Web Service Setup page in Head Office and Store:
    1. In the Server FastTab, set the Service Name to the instance name in the script.
    2. In the Client Credentials FastTab, set Http Authentication Type to Basic.
    3. Set the Username field to the name of the user that you created in step 3.
    4. In the Password field, paste the Web Service Access Key from step 4.
    5. Run Publisher and Subscriber.

  5. In the Distribution Location Card, Web Server FastTab, on the client instance (POS environment) for the Head Office:
    1. Set the Web Service AuthType field to Basic.
    2. In the Web Service User Name field, enter the name of the Nav User that you created in the client instance.
    3. In the Web Service Password field, enter the Web Service Access key that you copied from the User Card in the web service instance.
    4. Keep the Web Service Domain field blank.