Authentication Message Handler in C#

To access protected resources in C#, create a custom CredentialHandler, pass NetworkCredential to the web request, insert the handler into INetworkService.MessageHandlers, and open the HTML document with the configured pipeline.

Authentication is the process of determining whether a client has the right to access a protected resource. The HTTP protocol supports authentication by checking credentials such as a username and password before a server returns the requested content. This article shows how to add a credential handler to the Aspose.HTML for .NET message handler pipeline and briefly reviews Basic, Digest, NTLM, and Kerberos authentication schemes.

Creating a Message Handler for HTTP Basic Authentication

Basic Authentication is a method for an HTTP user agent to provide a username and password when making a request. In Aspose.HTML for .NET, you can add credentials through a custom message handler.

Take the following steps:

1. Use the necessary Namespace, which is the Aspose.Html.Net.
2. Define your own CredentialHandler class that will be derived from the MessageHandler class.
3. Override Invoke() to implement the custom message handler behavior.
4. Pass NetworkCredential to the web request used by the handler.

The following code snippet shows how to create a CredentialHandler to access a remote source that requires HTTP Basic Authentication:

// Use CredentialHandler for basic authentication

// This message handler used basic autentifications request
public class CredentialHandler : MessageHandler
{
    // Override the Invoke() method
    public override void Invoke(INetworkOperationContext context)
    {
        context.Request.Credentials = new NetworkCredential("username", "securelystoredpassword");
        context.Request.PreAuthenticate = true;

        Next(context);
    }
}

The handler passes NetworkCredential to a web request object, which uses it to authenticate requests to an Internet server.

Adding the CredentialHandler to the Pipeline

The key concept of message handlers is chaining them together. After creating CredentialHandler, add it to the pipeline used by the document configuration:

1. Create a Configuration object.
2. Get INetworkService from the configuration.
3. Use MessageHandlers.Insert() to add CredentialHandler at the beginning of the handler collection.
4. Open the protected URL with HTMLDocument(url, configuration).

The following C# example adds the handler to the pipeline:

// Authenticate and load protected HTML with custom configuration using C#

// Create an instance of the Configuration class
using Configuration configuration = new Configuration();

// Add the CredentialHandler to the chain of existing message handlers
INetworkService service = configuration.GetService<INetworkService>();
MessageHandlerCollection handlers = service.MessageHandlers;
handlers.Insert(0, new CredentialHandler());

// Initialize an HTML document with specified configuration
using HTMLDocument document = new HTMLDocument("https://httpbin.org/basic-auth/username/securelystoredpassword", configuration);

The Configuration() constructor initializes an instance of the Configuration class. After the configuration is created, GetService<INetworkService>() and MessageHandlers.Insert() are invoked. The Insert() method adds CredentialHandler at the first position in the message handler collection, so credentials are available before the request continues through the pipeline.

Authentication Schemes

Basic Authentication

Basic Authentication is a standard authentication method supported by HTTP servers and almost every web browser, making it an excellent access control method.

However, a severe drawback of Basic Authentication is that the username and password are transferred as Base64-encoded plain text. Base64 is not encryption and should be treated as cleartext. For protected resources, prefer stronger authentication schemes or use Basic Authentication only over a secure transport.

Digest

Digest authentication is an authentication method that a web server can use to negotiate credentials, such as a username or password, with a client. It was intended to replace Basic Authentication. Digest applies a hash function to the username and password before sending them over the network, making credentials harder to steal and reuse than with Basic Authentication.

NTLM

NTLM (New Technology LAN Manager) authentication is a challenge-response scheme that is a more secure version of Digest authentication. NTLM uses Windows credentials to convert the request data instead of an unencoded username and password. NTLM authentication requires several exchanges between client and server. The server and any intermediate proxies must maintain persistent connections for authentication to complete successfully.

Kerberos

Kerberos is a network authentication protocol designed to provide strong authentication for client-server requests using secret-key cryptography. In enterprise environments, Kerberos commonly relies on a trusted Key Distribution Center to authenticate clients and services.

You can download the complete examples and data files from GitHub.

FAQ

Which authentication schemes are covered?

The article covers Basic Authentication, Digest, NTLM, and Kerberos as HTTP authentication schemes relevant to protected resources.

Why insert CredentialHandler first?

Placing CredentialHandler first makes credentials available before later handlers or default network processing continue the request.

Is Basic Authentication secure?

Basic Authentication sends Base64-encoded credentials, which are not encrypted. Use it only with appropriate transport security or choose a stronger scheme.

Related Articles

• Check Network Requests – inspect requests and block unwanted protocols.
• Network Timeouts – set timeouts for slow protected resources.
• Message Handler Use Cases in C# – compare authentication with other message handler workflows.