Testing APIs: using basic authentication

[lvanvugt]

In chapter 13 is shown how to test your own APIs making use of the trick MS is using with respect to authentication as "Including the authentication in tests would be quite cumbersome" as I state in the following section (taken from chapter 13):

Authenticating the client

The next challenge is the authentication of the client as the service being called upon will require the client’s credentials. Including the authentication in tests would be quite cumbersome, and therefore the Microsoft Business Central team has chosen the practical approach, focusing on testing the API business logic and not validating the authentication. As such API tests are run in a database with no user and user-related data. In order to achieve this, the following needs to be done:

1. Set up your Business Central environment to use Windows authentication.
2. Remove all user and user-related data from the database.
3. Deploy your extension(s) with your application and test code.
4. Run the tests with standard test runner Test Runner - Isol. Disabled (130451).

Note that with this approach, we ignore testing the authorization to the server.

Trade-off

The trade-off of using Windows authentication is that it is not (easily) possible to get your API tests run in a pipeline as most probably the various parts of the pipeline are not run/triggered in your domain.

Alternative trick

Triggered by my Dutch Dynamics Community presentation, and later my Areopa webinar, Automated testing of your Business Central API Arend-Jan Kauffmann - who else - suggested to use the following trick allowing the usage of basic authentication. In this we are assuming we're using a docker container.

1. When building the docker container for testing the APIs the user and password are known
2. Adjust the script in such a way that it:
   a. adds an extension which introduces a table in BC - let's call it Test Setup - with a field in which the password can be stored
   b. populates that field with the password
3. Design your API tests to make use of this password (combined with the user)

[Arthurvdv]

Our development and our Azure DevOps pipelines environments are all setup-ed with Username/Password.

The idea is to create a small extension to have a eventsubscriber on the OnBeforeGetResponse and add BasicAuthentication to the API-call. With this maybe the standard tests of Microsoft would also be able to execute?

For now waiting for the event request here: microsoft/ALAppExtensions#15756

[Arthurvdv]

@lvanvugt: Good news, I have testing APIs working using basic authentication!

Adding this GraphMgtEventHandler.Codeunit.al file, that will add the credentials to the default Codeunit "Library - Graph Mgt" when executing a call.

• This event is available since Business Central 2022 release wave 1 (v20) (link)
• The requirement here is that the user has created a Web Services Access Key.

codeunit 50000 "PTE Graph Mgt Event Handler"
{
    SingleInstance = true;

    var
        IdentityManagement: Codeunit "Identity Management";
        WebServicesKey: Text[80];

    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Library - Graph Mgt", 'OnAfterInitializeWebRequestWithURL', '', false, false)]
    local procedure OnAfterInitializeWebRequestWithURL(var HttpWebRequestMgt: Codeunit "Http Web Request Mgt.")
    begin
        if WebServicesKey = '' then
            WebServicesKey := IdentityManagement.GetWebServicesKey(UserSecurityId());

        HttpWebRequestMgt.AddBasicAuthentication(UserId(), WebServicesKey);
    end;
}

HOW-TO handle the Web Services Access Key?
We use Docker in our CI/CD strategy, and always create a separate App for the tests. In the app.json of the Test-App we can add this parameter:

"target": "OnPrem",

This makes it possible to create a Install.Codeunit.al in the Test-App that assigns every user with a Web Services Access Key

codeunit 50000 "PTE Install"
{
    Subtype = Install;

    trigger OnInstallAppPerCompany()
    begin
        VerifyWebServicesKeyPerUser();
    end;

    local procedure VerifyWebServicesKeyPerUser()
    var
        User: Record User;
        IdentityManagement: Codeunit "Identity Management";
    begin
        User.SetLoadFields("User Security ID");
        if User.FindSet() then
            repeat
                if IdentityManagement.GetWebServicesKey(User."User Security ID") = '' then
                    IdentityManagement.CreateWebServicesKeyNoExpiry(User."User Security ID");
            until User.Next() = 0;
    end;
}

I'm afraid this will not work when using a Sandbox provided by Microsoft in the Cloud. Upgraded tenants could have the possibility to manual create a Web Services Access Key, but this is already deprecated for Cloud and wil surely be removed in the future. For On-Prem the Web Services Access Key wil continue to work.

[lvanvugt]

Wow, @Arthurvdv , that's great. Didn't find time myself to get to work on it. Will go and try it asap.

[lvanvugt]

Works like a charm. Tested it just now.

@Arthurvdv do you mind me, with reference to you, to write a blog post on it, or would you rather want to be the one?

[Arthurvdv]

The more people are aware of this solution, the more our BC community can grow. I would find it awesome if you would write a blog about is (and be honored with a reference :-))