Authentication with Kiota API clients

Most REST APIs are protected through some kind of authentication and authorization scheme. The default HTTP core services provided by Kiota require an authentication provider to be passed to handle authentication concerns.

Authentication provider interface

Authentication providers are required to implement the following contract/interface defined in the abstraction library.

public interface IAuthenticationProvider
{
    Task AuthenticateRequestAsync(
        RequestInformation request,
        Dictionary<string, object>? additionalAuthenticationContext = null,
        CancellationToken cancellationToken = default);
}

The request parameter is the abstract request to be executed. The return value must be a Task that completes whenever the authentication sequence completes and the request object is updated with the authentication/authorization information.

Access token provider interface

Implementations of this interface can be used in combination with the BaseBearerTokenAuthentication provider class to provide the access token to the request before it executes. They can also be used to retrieve an access token to build and execute arbitrary requests with a native HTTP client.

public interface IAccessTokenProvider
{
    AllowedHostsValidator AllowedHostsValidator { get; }

    Task<string> GetAuthorizationTokenAsync(
        Uri uri,
        Dictionary<string, object>? additionalAuthenticationContext = null,
        CancellationToken cancellationToken = default));
}

In GetAuthorizationTokenAsync, the uri parameter is the URI of the abstract request to be executed. The return value is a Task that holds the access token, or null if the request could/should not be authenticated.

Allowed hosts validator

This utility class is in charge of validating the host of any request is present on an allowlist. The validator is used by the base access token provider to check whether it should return a token to the request.

Base bearer token authentication provider

A common practice in the industry for APIs is to implement authentication and authorization via the Authorization request header with a bearer token value.

If you want to add support for more authentication providers for that scheme, Kiota abstractions offer a class to use in combination with your own implementation of an access token provider. You only need to implement the access token acquisition sequence and not the header composition and addition.

public class BaseBearerTokenAuthenticationProvider
{
    public BaseBearerTokenAuthenticationProvider(IAccessTokenProvider tokenProvider) {

    }
}

Note

Please leverage the same approach if you want to add support for new authentication schemes where the authentication scheme composition logic is implemented in a base class so it can be reused across multiple providers.

Microsoft Entra Identity authentication provider

The Azure authentication package contains an authentication provider that relies on Microsoft Entra Identity to get access tokens and implements bearer authentication. It can effectively be used for any client making requests to APIs secured by the Microsoft Entra Identity Platform.

Anonymous authentication provider

Some APIs don't require any authentication and can be queried anonymously. For this scenario, the abstractions packages provide an AnonymousAuthenticationProvider, which serves as a placeholder and performs no operation.

API key authentication provider

Some APIs simply rely on an API key for authentication in the request query parameters or in the request headers. For this scenario, the abstractions packages provide an ApiKeyAuthenticationProvider.

This provider allows you to:

  • Set the name of the request header/query parameter. (for example Authorization)
  • Set the value of the request header/query parameter. (for example Basic base64encodedValue)
  • Choose whether the provided name and value are used for a request header or for a query parameter.

Note

This authentication provider does not perform any encoding of the key or the value, if the authentication scheme requires any encoding, it needs to be performed before the values are passed to the provider. For example with basic authentication, you'll need to base64 encode the "userId:password" pair before passing it to the provider.

Choose your authentication provider

  • Does the target API require no authentication? Use the anonymous authentication provider.
  • Is the API protected by Microsoft Identity Platform? Use the Azure Identity authentication provider.
  • Is the authentication implemented via an API key in the query parameters or headers? Use the API key authentication provider.
  • Is the authentication implemented via a bearer token in the Authorization header? Use a custom access token provider with the Base bearer token authentication provider.
  • Anything else, use a custom authentication provider.

Design considerations

The default request adapters used by generated clients to make an HTTP request require an authentication provider as a constructor parameter, and call the authenticate request method themselves. An alternative could be to use HTTP client middleware handlers instead. This approach was a deliberate design decision to:

  • Lead application developer to make a conscious choice about authenticating with the API.
  • Enable reusability through interfaces defined to work with Request Information, limiting interdependencies.
  • Enable dependency injection scenarios.