Implement authentication

ArcGIS services and resources are secured using token-based authentication. There are several types of authentication you can implement in your application in order to obtain an access token to make secure requests. This topic describes some of the details for implementing different types of authentication for your ArcGIS Maps SDK for .NET app. See the Security and authentication introduction for an overview of the supported types of authentication, help Choosing a type of authentication for your app, and Tutorials and samples.

Authentication manager

This API contains an AuthenticationManager, available from the ArcGISRuntimeEnvironment, that manages all user authentication when your application connects to secured resources. It provides a central place to configure the authentication challenge handlers and credential stores.

The AuthenticationManager is a singleton class that, when enabled, will manage the user credentials for the following resources:

• Secured ArcGIS Online resources (web maps, for example).
• Secured ArcGIS Enterprise resources.
• ArcGIS Server resources secured using token-based authentication or using HTTP authentication. Note that only ArcGIS Server versions 10 SP 1 and greater are supported.

A credential for accessing to an ArcGIS resource can be preset by using AuthenticationManager.AddCredential. In this case the credential is used for any requests to the specified resources.

If a request to an ArcGIS resource returns an authorization error, the AuthenticationManager.ChallengeHandler, if not null, is called. This challenge handler can return the credential for accessing to the resource.

If the challenge handler is null or if it doesn't return any credential, the authorization error is returned to the caller as if the request was executed out of the AuthenticationManager.

Use API keys in your app

An API key can be used to authorize access to specific ArcGIS Online services and resources from your app, as well as to monitor access to those services. An API key is created and managed in the ArcGIS developer dashboard and is tied to your ArcGIS account.

You can set an API key on the ArcGISRuntimeEnvironment, which will apply the key to all requests your app makes for ArcGIS Online services and resources.

1
2
3
4
5
6
7
8
9
10
    public partial class App : Application
    {
        protected override void OnStartup(StartupEventArgs e)
        {
            base.OnStartup(e);
            // Note: it is not best practice to store API keys in source code.
            Esri.ArcGISRuntime.ArcGISRuntimeEnvironment.ApiKey = "YOUR_API_KEY";
        }
    }
}

You can also set an API key on any class that implements APIKeyResourceInterface. When you set an API key for a specific class, it will override any key you may have set on ArcGISRuntimeEnvironment, enabling more granular usage telemetry and management for ArcGIS Online resources used by your app.

1
2
3
4
5
6
// Create a new ArcGIS basemap and apply an API key.
var basemap = new Basemap(BasemapStyle.ArcGISTopographic);
basemap.ApiKey = "YOUR_API_KEY";

// Create a new map with the basemap.
var map = new Map(basemap);

Classes that implement APIKeyResourceInterface include:

• Basemap
• ArcGISSceneLayer
• ArcGISTiledLayer
• ArcGISVectorTiledLayer
• ServiceFeatureTable
• ExportVectorTilesTask
• LocatorTask
• GeodatabaseSyncTask
• ClosestFacilityTask
• RouteTask
• ServiceAreaTask
• ExportTileCacheTask

Implement user authentication

User authentication is a set of authentication workflows that allow users with an ArcGIS account to sign into an application and access ArcGIS content, services, and resources. With user authentication, your app accesses content and services on behalf of the logged-in user and all usage is charged to their ArcGIS account.

Some common user authentication workflows include:

• OAuth 2.0
• Integrated Windows authentication (IWA)
• Public Key Infrastructure (PKI) authentication

OAuth 2.0

OAuth (short for Open Authorization) is an open standard for token-based authentication. Using OAuth 2.0, your application can request permission from the user to act through the user's account without having to directly handle the user's credentials. Rather than getting credentials from the user, your app directs the user to sign in with the authorization server. When successfully authenticated, your app receives a response (at a redirect URL you configure) with an authorization token that proves an identity between your app and the server. The tokens issued by an authorization server (ArcGIS Online or ArcGIS Enterprise, for example) are valid for a limited time and for limited use.

While some details vary depending on the OAuth flow and the target platform for your app, the basic steps for implementing OAuth 2.0 in your app are as follows:

1. Use the ArcGIS Developer dashboard to create application metadata. The metadata will include a Client ID, Client Secret, and Redirect URL. See the Access services with OAuth 2.0 tutorial for detailed steps.
2. Set the AuthenticationManager.OAuthAuthorizeHandler property with a class that handles some of the OAuth details, like showing a login UI from the server and obtaining the authorization or error when the login is complete (or canceled).
3. The DefaultChallengeHandler will direct to the OAuthAuthorizeHandler when it detects a token challenge. If you have a custom ChallengeHandler, it must call AuthenticationManager.GenerateCredentialAsync() to start the OAuth authorization process.
4. Add code to register the servers that contain secure content with the AuthenticationManager. For each server, specify the URI and required OAuth parameters (usually client ID and redirect URL). To challenge for all secured content on ArcGIS Online, use this URL for the authorization server: https://www.arcgis.com/sharing/rest.

When a secured resource is encountered from a server registered with the AuthenticationManager, the user is challenged to provide a login for that server. If successful, the resource will be available. All subsequent requests for secured content from the same server will be available as part of the previous authorization (until the authorization expires).

For examples that include helper classes and other code you can borrow for your own implementation, see the Access services with OAuth 2.0 tutorial (for WPF), Access services with OAuth 2.0 tutorial (for .NET MAUI), and Authenticate with OAuth sample.

Platform considerations

WinUI

Currently WebAuthenticator does not work on Windows in a .NET MAUI app without some additional work. See the .NET MAUI GitHub issue #2702 for details. There are a number of possible workarounds, including the use of a 3rd-party NuGet package as described in the Access services with OAuth 2.0 (.NET MAUI) tutorial.

Android

The AndroidManifest.xml file must be updated to include the CustomTabService, which is required by the WebAuthenticator. See the steps in the Access services with OAuth 2.0 (.NET MAUI) tutorial for details.

iOS and Mac Catalyst

You must include your app's callback URI pattern in the Info.plist file. The CFBundleURLSchemes value must match the URI scheme of the redirect URL on your ArcGIS developer account.

Integrated Windows authentication (IWA)

Integrated Windows authentication (IWA) enables users to log in with their Windows credentials using Kerberos or NTLM authentication protocols. IWA is built into Microsoft Internet Information Server (IIS) and manages logins through Microsoft Windows Active Directory. It works well for intranet applications, but may not be practical for many internet apps. If the client computer or device belongs to the same domain, the user is authenticated with their Windows account and is not prompted to enter credentials. Access to ArcGIS Enterprise can be secured using IWA. This provides a smooth user experience since the same credentials used to log in to the user's work computer and network are also used to authenticate with ArcGIS.

When accessing resources that are secured with IWA on Windows platforms (or on a Mac that has joined the domain), default credentials (the login that started the app, in other words) are used and the user is not prompted to login. On other platforms, such as Android and iOS, credentials must be entered explicitly by prompting the user for them.

Platform considerations

On Windows and domain-connected Mac Catalyst apps, IWA authentication is handled using the current user's credential. The user is not prompted to enter credentials and the app does not need to handle authentication.

On Android and iOS, the app must prompt the user to log in or have logic to provide the appropriate credential.

Although a challenge isn't always raised, IWA authentication can be detected (on all platforms except UWP) using ArcGISPortal.GetLoginTypeForUriAsync(). If the portal is secured with IWA, this method returns PortalLoginType.UsernamePassword. If needed, a ArcGISNetworkCredential for accessing a secured service can be added to AuthenticationManager up-front, as shown in the following example.

1
2
3
    // Add a network credential to the AuthenticationManager for the specified service.
    var credential = new ArcGISNetworkCredential(serviceUri, "username", "password", "domain");
    AuthenticationManager.Current.AddCredential(credential);

Other platform considerations:

• Android: Supports NTLM but not Kerberos. Accessing a secured resource will challenge for network authentication (username/password).

• iOS: Supports NTLM. Kerberos is supported when using NSUrlSessionHandler (which is the default). Accessing a secured resource will challenge for network authentication (username/password).

• MacOS (Mac Catalyst): Automatic sign-in with the current user's credential on domain-joined Macs; no challenge.

• Windows Desktop (WPF / WinUI): Automatic sign-in with current user's credential; no challenge.

• Univeral Windows Platform (UWP): Automatic sign-in with current user's credential; no challenge. IWA authentication can not be detected via ArcGISPortal.GetLoginTypeForUriAsync().

Public Key Infrastructure (PKI) authentication

Public Key Infrastructure (PKI) is a framework in which a trusted Certificate Authority issues digital certificates to users and organizations. Certificates contain a public key and the identity of the certificate owner, enabling clients and servers to authenticate and encrypt communications. ArcGIS Enterprise leverages the PKI solution with the IIS web server using the ArcGIS IIS Web Adaptor. When a request is made for a resource hosted with ArcGIS Enterprise, the web server authenticates the user by validating a client certificate that contains the user's digital keys. The request is then forwarded to ArcGIS Enterprise via the Web Adaptor to verify that the specified user has access to the requested resource before sending back the appropriate response.

In a PKI authentication flow, the AuthenticationManager.ChallengeHandler returns a CertificateCredential for accessing a secured resource (portal item, for example). If a credential was previously generated, the credential is returned. Otherwise, a UI is presented for the user to select an available certificate and provide a password. The certificate and password is used to create and return a CertificateCredential. If the certificate choice is cancelled or unsuccessful, a null credential is returned.

In a .NET MAUI app, for example, you could use code like this to have the user select a certificate using the FilePicker and then prompt for the certificate password using a custom popup:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
    // Prompt the user to select a certificate.
    var result = await FilePicker.Default.PickAsync();
    if (result != null)
    {
        // Prompt the user to enter the certificate password.
        var passwordPopup = new CertPasswordPopup(result.FileName);
        var passwordResult = await this.ShowPopupAsync(passwordPopup);
        // Read the certificate file.
        using var stream = await result.OpenReadAsync();
        var buffer = new byte[stream.Length];
        stream.Read(buffer);
        // Create a certificate credential from the certificate contents and password.
        var cert = new X509Certificate2(buffer, (string)passwordResult);
        _credential = new CertificateCredential(new Uri(PortalAddressEntry.Text), cert);
    }

    return _credential;

See Public Key Infrastructure in the Microsoft documentation for an overview of PKI.

Platform considerations

For PKI authentication to work on Android, iOS, or Mac Catalyst, code like the following must be added to CreateMauiApp() in MauiProgram.cs to configure the app to use the SocketsHttpHandler:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .UseMauiCommunityToolkit()
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
        })
        .UseArcGISRuntime(config =>
            config.ConfigureHttp(http => http.UseHttpMessageHandler<SocketsHttpHandler>()
            )
        );

    return builder.Build();

iOS and Mac Catalyst

It's not currently possible to retrieve existing credentials from the keychain in a .NET MAUI app. Instead, use the FilePicker to select the .pfx file and generate a certificate and then a credential for the given portal address.

Credential persistence does not work with PKI Authentication on iOS.

Android

Credential persistence does not work with PKI Authentication on Android.

A network_security_config.xml file must be added to Platforms\Android\Resources\xml with the following content:

1
2
3
4
5
6
7
8
9
<?xml version="1.0" encoding="UTF-8" ?>
<network-security-config>
  <base-config cleartextTrafficPermitted="true">
    <trust-anchors>
      <certificates src="system" />
      <certificates src="user" />
    </trust-anchors>
  </base-config>
</network-security-config>

And the following line must be included in the AndroidManifest.xml file:

1
<application android:networkSecurityConfig="@xml/network_security_config" />

For more information, see Network Security Configuration in the Android developer guide.