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 Base64 encoded. Use a certificate that's intended for client authentication.
With the AddCertificate method you set the certificates that you want to be associated to the request of the HTTP client connection. These certificates are used only to authenticate the client. They don't configure or validate the server certificate that the external endpoint presents.
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 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.
In Business Central online, certificates used with HttpClient, including client certificates added with the AddCertificate method, must be issued by a trusted public certification authority (CA). Self-signed certificates and certificates issued by private or internal CAs aren't trusted by default and can cause HTTP calls to fail. To help ensure successful and secure communication, use certificates that are part of a standard trust chain anchored in a well-known public CA.
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.
Related information
HttpClient Data Type
Get Started with AL
Developing Extensions