HttpClient.AddCertificate(Text [, Text]) Method

Version: Available or changed with runtime version 1.0.

Adds a certificate to the HttpClient class.

Syntax

 HttpClient.AddCertificate(Certificate: Text [, Password: Text])

Parameters

HttpClient
 Type: HttpClient
An instance of the HttpClient data type.

Certificate
 Type: Text
The Base64 encoded certificate.

[Optional] Password
 Type: Text
The certificate password.

Example

The following example shows how to add a certificate to the HttpClient data type.

// This code shows how to use certificates with HttpClient
procedure AddCertificateToHttpClient(var HttpClient: HttpClient; CertificateCode: Text[6])
var
    IsolatedCertificate: Record "Isolated Certificate";
    CertificateManagement: Codeunit "Certificate Management";
begin
    if not IsolatedCertificate.Get(CertificateCode) then
        exit;
    HttpClient.AddCertificate(
        CertificateManagement.GetCertAsBase64String(IsolatedCertificate),
        CertificateManagement.GetPassword(IsolatedCertificate));
end;

Remarks

The certificate must be in base 64 format.

With the AddCertificate method you set the certificates that you want to be associated to the request of the http client connection. These have the only purpose of authenticating the client.

The system caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, it uses the first certificate that was added or tries to reuse an anonymous session if no certificates have been specified.

Important

The certificate must be use one of the supported cipher suites; otherwise, outgoing web service calls will fail with a security exception. For more information, see Supported cipher suites.

Important

In Business Central versions 22 (2023 release wave 1) and later, certificates must include the following information:

  • If KeyUsage is defined, specify DigitalSignature.
  • If ExtendedKeyUsage is defined, specify ClientAuthentication.

This is due to different behavior between .NET Core and .NET Framework.

When making an outbound http call to an external endpoint, if you receive a 403 response (external endpoint required a certificate), and your code does have a HttpClient.AddCertificate, check the version of the Business Central platform and the requirements for KeyUsage and ExtendedKeyUsage.

HttpClient Data Type
Get Started with AL
Developing Extensions