"}],"short_description":"Learn how to smoothly migrate your ArcGIS Maps SDK for .NET apps to the simplified, secure, and modernized authentication APIs.","flexible_content":[{"acf_fc_layout":"content","content":"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. Key enhancements include:<\/p>\n
This blog post will guide you through the transition, highlighting new capabilities, outlining clear paths from deprecated APIs, and providing practical code examples to help you implement these changes quickly and confidently.<\/p>\n
Let\u2019s start by exploring the new credential types that form the foundation of the updated authentication system.<\/p>\n
This replaces OAuthTokenCredential<\/strong>s of type OAuthAuthorizationCode<\/strong>.<\/p>\n OAuthUserCredential<\/a> implements user authentication<\/a> using OAuth \u201cauthorization code\u201d flow with PKCE. This is the recommended approach for authenticating end users, providing extra security compared to other methods.<\/p>\n 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 their behalf. The available resources and functionality depend on the user\u2019s ArcGIS account type, roles, and privileges.<\/p>\n To implement this authentication flow, you need to:<\/p>\n Our Access services with OAuth credentials<\/a> tutorial provides a complete implementation example.<\/p>\n This replaces OAuthTokenCredential<\/strong>s of type OAuthClientCredentials<\/strong>.<\/p>\n OAuthApplicationCredential<\/a> implements app authentication<\/a> using OAuth \u201cclient credentials\u201d flow. Use this to create applications that do not require users to sign in, but still need access to token-secured resources and services.<\/p>\n With this approach, requests are made using the credits and privileges associated with your app\u2019s account rather than an individual user\u2019s account. An app credential is created from a client ID and client secret that have been pre-registered with the portal.<\/p>\n 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.<\/p>\n This replaces ArcGISTokenCredential<\/strong>s created by GenerateCredentialAsync<\/strong>.<\/p>\n AccessTokenCredential<\/a> provides an access token for secured ArcGIS content and services. You can obtain this token in several ways:<\/p>\n Our ArcGIS token challenge sample<\/a> shows how to create this credential in response to an authentication challenge. You can also create and add a credential to the AuthenticationManager<\/a> before accessing secured services.<\/p>\n This replaces ArcGISTokenCredential<\/strong>s created by the token-string constructor.<\/p>\n PregeneratedTokenCredential<\/a> 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:<\/p>\n Beyond the credential types themselves, several supporting APIs have been added to enhance flexibility and control.<\/p>\n When working with HTTPS services, you can now customize how SSL\/TLS certificates are validated. Specify a custom callback when configuring HTTP settings<\/a> to examine all SSL connections made by the Maps SDK.<\/p>\n 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:<\/p>\n The callback uses the standard .NET RemoteCertificateValidationCallback<\/a> signature. For more information including code examples, see Microsoft\u2019s guide to custom X509Certificate validation<\/a>.<\/p>\n The new IHttpMessageInterceptor<\/a> interface allows you to monitor, modify, or even mock HTTP requests and responses. This powerful capability can be configured globally when configuring HTTP settings<\/a> on startup. Common use cases include:<\/p>\n Logging and Diagnostics<\/strong>: Log request and response details for monitoring and debugging:<\/p>\n Custom Headers<\/strong>: Modify headers in requests or responses to improve compatibility with specific services:<\/p>\n Mock Responses for Testing<\/strong>: Intercept requests and send mock responses instead of using live services:<\/p>\n Persisting credentials reduces the need for users to repeatedly authenticate, creating a smoother experience across application sessions. For most platforms we provide a ready-to-use implementation via CredentialPersistence.CreateDefaultAsync<\/a> that securely stores credentials using platform-specific mechanisms. But for those who handle persistence themselves, we\u2019ve added Credential.ToJson<\/a> and Credential.FromJson(string)<\/a> methods to make this easier. These JSON-based methods have several advantages over the previous ISerializable-based approach:<\/p>\n Now that you understand the new authentication components, let\u2019s look at practical steps for migrating existing code.<\/p>\n If your app uses TokenCredential<\/strong> to access token-secured ArcGIS resources, you should replace it with one of the ArcGISCredential<\/a> implementations described above.<\/p>\n Instead of generating credentials using AuthenticationManager.GenerateCredentialAsync<\/strong> with GenerateTokenOptions<\/strong>, use one of these factory methods:<\/p>\n If you were handling token generation yourself and constructing an ArcGISTokenCredential<\/strong> with a token string, construct a PregeneratedTokenCredential<\/a> instead.<\/p>\n If your app relied on OAuth Implicit flow ( If your app registered a ServerInfo<\/strong> to configure authentication, migrate to the new APIs as follows:<\/p>\n For OAuth user<\/em> authentication, create an OAuthUserConfiguration<\/a> instead of ServerInfo:<\/p>\n After creating the configuration, you have three options:<\/p>\n For OAuth app<\/em> authentication, pass client ID and client secret directly to OAuthApplicationCredential.CreateAsync<\/a>.<\/p>\n If you currently use ArcGISHttpClientHandler.DefaultReferer<\/strong> or GenerateTokenOptions.Referer<\/strong> to specify a referrer, use UseDefaultReferer<\/a> in the fluent configuration API instead.<\/p>\n Starting with version 200.7.0, Credential\u2019s ServiceUri<\/strong> property will be deprecated in favor of ServerContext<\/strong>, which provides a more reliable URL for matching credentials with network requests.<\/p>\n ServiceUri preserves the original URL from the time of creation, often including unnecessary details from the ChallengeHandler like item IDs or query parameters. In contrast, ServerContext provides a normalized base URL that reflects how credentials are actually matched to requests:<\/p>\n This change doesn\u2019t affect how credentials are matched internally, but if your code specifically checks the ServiceUri property, consider using ServerContext instead.<\/p>\n To make requests using Maps SDK\u2019s network stack, taking advantage of its authentication and caching features, use ArcGISHttpMessageHandler<\/a> instead of the deprecated ArcGISHttpClientHandler<\/strong>. This provides the same functionality with better performance and improved challenge detection.<\/p>\n If you were using ArcGISHttpClientHandler\u2019s global HttpRequestBegin<\/strong> and HttpRequestEnd<\/strong> events, replace them with the IHttpMessageInterceptor<\/a> interface described earlier.<\/p>\n The ISerializable support for Credentials is being deprecated in line with Microsoft\u2019s effort to phase out legacy serialization<\/a> in .NET.<\/p>\n We\u2019ve already updated the default CredentialPersistence<\/a> implementations to use FromJson\/ToJson instead of DataContractSerializer. If your app implements custom credential storage, we recommend that you do the same.<\/p>\n If your app needs to know the token value or expiration, cast it to a specific subclass of ArcGISCredential and use either the async GetTokenInfoAsync method or the TokenInfo property. Calling GetTokenInfoAsync refreshes the token as needed, so the new credentials do not include a RefreshAsync() method.<\/p>\n Migrating to the new authentication system in the Native Maps SDK for .NET is essential to ensure your applications remain secure and up-to-date. By following the guidance provided in this post, you can take advantage of the new capabilities, streamline your authentication processes, and prepare for future updates. While deprecated APIs will continue working in 200.x releases of ArcGIS Maps SDK for .NET, they will be removed in the next major release (300.x)<\/strong>.<\/p>\n To ensure a smooth transition, enable deprecation warnings in your build process to identify usage of outdated APIs early, and implement changes incrementally with thorough testing. Our documentation<\/a> provides additional examples and tutorials to guide you through specific scenarios. If you encounter challenges during migration, reach out through Esri Community<\/a> or through technical support<\/a>.<\/p>\n Lastly, we\u2019ve provided a quick reference guide below for authentication flow replacements. Happy migrating!<\/p>\n Authentication Flow Replacements<\/strong><\/p>\n Configuration Replacements<\/strong><\/p>\n\n
OAuthAppCredential (200.5+)<\/h3>\n
AccessTokenCredential (200.6+)<\/h3>\n
\n
PregeneratedTokenCredential (200.5+)<\/h3>\n
\n
New Supporting APIs<\/h2>\n
Server Certificate Validation (200.6+)<\/h3>\n
\n
IHttpMessageInterceptor (200.5+)<\/h3>\n
public<\/span> class<\/span> LoggingHttpInterceptor<\/span> : IHttpMessageInterceptor<\/span>\r\n{\r\n public<\/span> async<\/span> Task SendAsync<\/span>(HttpMessageInvoker invoker, HttpRequestMessage message, CancellationToken cancellationToken<\/span>)<\/span>\r\n {\r\n \/\/ Log the outgoing request details.<\/span>\r\n Console.WriteLine($\"Request: {message.Method}<\/span> {message.RequestUri}<\/span>\"<\/span>);\r\n\r\n \/\/ Execute the request, with a timer<\/span>\r\n Stopwatch stopwatch = Stopwatch.StartNew();\r\n HttpResponseMessage response = await<\/span> invoker.SendAsync(message, cancellationToken);\r\n stopwatch.Stop();\r\n\r\n \/\/ Log the response details along with the elapsed time.<\/span>\r\n Console.WriteLine($\"Response: {(int<\/span>)response.StatusCode}<\/span> {response.ReasonPhrase}<\/span>, Elapsed Time: {stopwatch.ElapsedMilliseconds}<\/span> ms\"<\/span>);\r\n return<\/span> response;\r\n }\r\n}<\/pre>\npublic<\/span> class<\/span> CustomHeaderInterceptor<\/span> : IHttpMessageInterceptor<\/span>\r\n{\r\n public<\/span> Task SendAsync<\/span>(HttpMessageInvoker invoker, HttpRequestMessage message, CancellationToken cancellationToken<\/span>)<\/span>\r\n {\r\n if<\/span> (message.RequestUri?.Host == \"mydomain.com\"<\/span>)\r\n {\r\n \/\/ Add an extra request header for this domain only<\/span>\r\n message.Headers.Add(\"X-CustomHeader\"<\/span>, \"myHeaderValue\"<\/span>);\r\n }\r\n return<\/span> invoker.SendAsync(message, cancellationToken);\r\n }\r\n}<\/pre>\npublic<\/span> class<\/span> DictionaryMockHttpInterceptor<\/span> : IHttpMessageInterceptor<\/span>\r\n{\r\n \/\/ Map known URLs to string responses.<\/span>\r\n private<\/span> readonly<\/span> Dictionary<string<\/span>, string<\/span>> _mockResponses = new<\/span> Dictionary<string<\/span>, string<\/span>>\r\n {\r\n { \"http:\/\/example.com\/api\/test\"<\/span>, \"{\\\"result\\\":\\\"Test successful\\\"}\"<\/span> },\r\n { \"http:\/\/example.com\/api\/error\"<\/span>, \"{\\\"error\\\":\\\"Something went wrong\\\"}\"<\/span> }\r\n };\r\n\r\n public<\/span> Task SendAsync<\/span>(HttpMessageInvoker invoker, HttpRequestMessage message, CancellationToken cancellationToken<\/span>)<\/span>\r\n {\r\n if<\/span> (message.RequestUri != null<\/span> && _mockResponses.TryGetValue(message.RequestUri.AbsoluteUri, out<\/span> var<\/span> responseContent))\r\n {\r\n var<\/span> response = new<\/span> HttpResponseMessage(HttpStatusCode.OK)\r\n {\r\n Content = new<\/span> StringContent(responseContent, System.Text.Encoding.UTF8, \"application\/json\"<\/span>)\r\n };\r\n return<\/span> Task.FromResult(response);\r\n }\r\n\r\n \/\/ If no mock response is found, proceed with the actual HTTP call.<\/span>\r\n return<\/span> invoker.SendAsync(message, cancellationToken);\r\n }\r\n}<\/pre>\nCredential.ToJson\/FromJson (200.5+)<\/h3>\n
\n
Migration Guidance<\/h2>\n
Token Authentication<\/h3>\n
\n
TokenAuthenticationType.OAuthImplicit<\/code>), you should switch to a different flow. The \u201cimplicit\u201d flow has been deprecated across the ArcGIS Platform<\/a>, and support will be removed in the next major release of the Maps SDK.<\/p>\nConfiguring OAuth<\/h3>\n
\/\/ Old deprecated way:<\/span>\r\nAuthenticationManager.Current.RegisterServer(new<\/span> ServerInfo(\"http:\/\/myserver.com\/portal\/sharing\/\"<\/span>)\r\n{\r\n TokenAuthenticationType = TokenAuthenticationType.OAuthAuthorizationCode,\r\n OAuthClientInfo = new<\/span> OAuthClientInfo(\"MyClientID\"<\/span>, null<\/span>),\r\n});\r\n\r\n\/\/ New recommended way:<\/span>\r\nvar<\/span> myOAuthConfig = new<\/span> OAuthUserConfiguration(\"http:\/\/myserver.com\/portal\"<\/span>, \"MyClientID\"<\/span>, myRedirectUrl);<\/pre>\n\n
var<\/span> credential = await<\/span> OAuthUserCredential.CreateAsync(myOAuthConfig);\r\nAuthenticationManager.Current.AddCredential(credential);<\/pre>\n<\/li>\nArcGISRuntimeEnvironment.Initialize(config =>\r\n{\r\n config.ConfigureAuthentication(authConfig =>\r\n {\r\n authConfig.AddOAuthUserConfiguration(myOAuthConfig);\r\n });\r\n});<\/pre>\n<\/li>\nAuthenticationManager.Current.OAuthUserConfigurations.Add(myOAuthConfig);\r\nAuthenticationManager.Current.OAuthAuthorizeHandler = myAuthorizeHandler;<\/pre>\n<\/li>\n<\/ul>\n
Credential URLs<\/h3>\n
\n
\/rest<\/code>.<\/li>\n<\/ul>\nUsing Maps SDK\u2019s Network Stack for Your Own Requests<\/h3>\n
Request Logging and Interception<\/h3>\n
Persisting Credentials<\/h3>\n
Obtaining and Refreshing Tokens<\/h3>\n
Summary<\/h2>\n
Quick Reference Guide<\/h3>\n
\n\n
\n \nUse case<\/th>\n Legacy APIs<\/th>\n New Replacement<\/th>\n<\/tr>\n<\/thead>\n \n OAuth user authentication<\/td>\n OAuthTokenCredential<\/code><\/td>\nOAuthUserCredential<\/code><\/td>\n<\/tr>\n\n OAuth app authentication<\/td>\n OAuthTokenCredential<\/code><\/td>\nOAuthAppCredential<\/code><\/td>\n<\/tr>\n\n Username + password login<\/td>\n GenerateCredentialAsync<\/code><\/td>\nAccessTokenCredential<\/code><\/td>\n<\/tr>\n\n Manually generated tokens<\/td>\n ArcGISTokenCredential<\/code><\/td>\nPregeneratedTokenCredential<\/code><\/td>\n<\/tr>\n\n OAuth implicit flow<\/td>\n GenerateCredentialAsync<\/code> + TokenAuthenticationType.OAuthImplicit<\/code><\/td>\nSwitch to authorization code flow<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n \n\n
\n \nUse case<\/th>\n Legacy API<\/th>\n New Replacement<\/th>\n<\/tr>\n<\/thead>\n \n Set up user authentication<\/td>\n ServerInfo<\/code> + OAuthClientInfo<\/code><\/td>\nOAuthUserConfiguration<\/code><\/td>\n<\/tr>\n\n Pick token type<\/td>\n TokenAuthenticationType<\/code><\/td>\nUse a specific subclass of ArcGISCredential<\/td>\n<\/tr>\n \n Specify a referrer<\/td>\n ArcGISHttpClientHandler.DefaultReferer<\/code> or GenerateTokenOptions.Referer<\/code><\/td>\nIArcGISHttpConfiguration.UseDefaultReferer<\/code><\/td>\n<\/tr>\n\n Check credential’s URL<\/td>\n Credential.ServiceUri<\/code><\/td>\n