Migrating Your ArcGIS Maps SDK for .NET Applications to the New Authentication System

In 2024, the ArcGIS Maps SDK for .NET team introduced significant changes to authentication APIs as part of a long-term effort to simplify

In 2024, the ArcGIS Maps SDK for .NET team introduced significant changes to authentication APIs as part of a long-term effort to simplify and align the .NET Maps SDK with other Native Maps SDKs. This transition also involved deprecating older APIs to streamline development and maintain compatibility with the broader ArcGIS Platform.

This blog post will guide you through this transition, highlighting new capabilities, outlining clear paths from deprecated APIs, and providing practical code examples to help you implement these changes quickly and confidently.

New Credential Types

Let’s start by exploring the new credential types that form the foundation of the updated authentication system.

OAuthUserCredential (200.6+)

This replaces OAuthTokenCredentials of type OAuthAuthorizationCode.

OAuthUserCredential implements user authentication using OAuth “authorization code” flow with PKCE. This is the recommended approach for authenticating end users, providing extra security compared to other methods.

When a user signs in to your application with their ArcGIS account, a token is generated that authorizes your app to access services and content on behalf of the user. The available resources and functionality depend on the user’s ArcGIS account type, roles, and privileges.

To implement this authentication flow, you need to:

Our Access services with OAuth credentials tutorial provides a complete implementation example.

OAuthAppCredential (200.5+)

This replaces OAuthTokenCredentials of type OAuthClientCredentials.

OAuthApplicationCredential implements app authentication using OAuth “client credentials” flow. Use this to create applications that do not require users to sign in, but still need access to token-secured resources and services.

With this approach, requests are made using the credits and privileges associated with your app’s account rather than an individual user’s account. An app credential is created from a client ID and client secret that have been pre-registered with the portal.

The client secret should be treated as confidential information since it allows direct billing to your developer account. This authentication method is intended for secure environments where credentials cannot be easily exposed to end users. Never include your client secret in publicly distributed applications.

AccessTokenCredential (200.6+)

This replaces ArcGISTokenCredentials created by GenerateCredentialAsync.

AccessTokenCredential provides an access token for secured ArcGIS content and services. You can obtain this token in several ways:

Our ArcGIS token challenge sample shows how to create this credential in response to an authentication challenge. You can also create and add a credential to the AuthenticationManager before accessing secured services.

PregeneratedTokenCredential (200.5+)

This replaces ArcGISTokenCredentials created by the token-string constructor.

PregeneratedTokenCredential accesses token-secured ArcGIS content and services using an independently generated token. This credential type gives you flexibility when integrating with custom authentication systems. Use it when you:

New Supporting APIs

Beyond the credential types themselves, several supporting APIs have been added to enhance flexibility and control.

Server Certificate Validation (200.6+)

When working with HTTPS services, you can now customize how SSL/TLS certificates are validated. Specify a custom callback when configuring HTTP settings to examine all SSL connections made by the Maps SDK.

Server certificates are usually validated by the operating system using default policies and known Certificate Authorities, but your own validator can accept or reject connections based on custom criteria. For example:

The callback uses the standard .NET RemoteCertificateValidationCallback signature. For more information including code examples, see Microsoft’s guide to custom X509Certificate validation.

IHttpMessageInterceptor (200.5+)

The new IHttpMessageInterceptor interface allows you to monitor, modify, or even mock HTTP requests and responses. This powerful capability can be configured globally when configuring HTTP settings on startup. Common use cases include:

Logging and Diagnostics: Log request and response details for monitoring and debugging:

import logging

logger = logging.getLogger(__name__)

class MessageInterceptor(IHttpMessageInterceptor):

"""Logs request and response details to the console."""

def OnRequest(self, request, cancellationToken):

"""Called before a request is sent."""

logger.info(f"Request: {request.Method} {request.RequestUri}")

for header in request.Headers:

logger.info(f" Header: {header}")

async def main():

"""Main function to configure and run the message interceptor."""

message_interceptor = MessageInterceptor()

http_settings = HttpSettings.Builder().AddMessageInterceptor(message_interceptor).Build()

async with AuthenticationManager.CreateInstanceAsync(credentials, http_settings) as auth_manager:

user = await ArcGISUser.CurrentUserAsync(auth_manager)

logger.info(f"Logged in as: {user.Username}")

if __name__ == "__main__":

logging.basicConfig(level=logging.INFO, format='%(asctime