Authentication API

You can manage the authentication process in your application code using the authentication API provided by ArcGIS Maps SDK for Flutter. This is the same API used by the Authenticator component, and gives you fine-grained control over the authentication process. When using the API rather than the toolkit, you are responsible for the code that handles authentication details.

The central class in the authentication API is the AuthenticationManager. This is a static property of the ArcGISEnvironment.

1
ArcGISEnvironment.authenticationManager

The AuthenticationManager provides:

• Credential stores for your application to hold ArcGIS and network credentials that are automatically checked when your application attempts to connect to secure resources. These stores can be persisted in a keychain so that user does not have to sign in again when the application is re-launched. For more information, see Create and store credentials.
• ArcGIS and network challenge handlers that allow your application to respond to the authentication challenges. For example, you can write code to present the user with a login screen and then continue to authenticate with those credentials. For more information, see Handle authentication challenges.

Handle authentication challenges

If your application attempts to access a secure resource and there is no matching credential in the credential store, an authentication challenge is raised:

• ArcGISAuthenticationChallenge is raised if the ArcGIS secured resource requires OAuth or ArcGIS Token authentication.
• NetworkAuthenticationChallenge is raised if the ArcGIS secured resource requires network credentials, such as Integrated Windows Authentication (IWA) or Public Key Infrastructure (PKI).

You can catch and respond to the authentication challenges using the ArcGISAuthenticationChallengeHandler and NetworkAuthenticationChallengeHandler, respectively. These challenge handlers represent abstract interfaces that you can implement in any class. You can catch and respond to the authentication challenges using the ArcGISAuthenticationChallengeHandler and NetworkAuthenticationChallengeHandler, respectively. These challenge handlers represent abstract interfaces that you can implement in any class.

ArcGIS authentication challenge handler

The ArcGISAuthenticationChallengeHandler is used to handle authentication challenges from ArcGIS secured resources that require OAuth or ArcGIS Token authentication. Handle the challenge by returning one of the ArcGISAuthenticationChallenge options:

• continueWithCredential(ArcGISCredential) - Continue the challenge with the given credential.

• continueAndFail() - The request that issued the authentication challenge will fail with the challenge's error.

• cancel() - Cancels the request that initiated the challenge.

1. Create a class implementing the ArcGISAuthenticationChallengeHandler abstract interface to handle ArcGIS authentication challenges.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   // Defines an ArcGIS authentication challenge handler.
   class _AuthenticateWithOAuthState extends State<AuthenticateWithOAuth>
       implements ArcGISAuthenticationChallengeHandler {
   
     // The OAuth configuration that this challenge handler can work with.
     final _oauthUserConfiguration = OAuthUserConfiguration(
       portalUri: portalUri,
       clientId: clientId,
       redirectUri: redirectUri,
     );
   
     // Handles the challenge to an ArcGIS secured resources that requires
     // OAuth or ArcGIS Token authentication.
     @override
     void handleArcGISAuthenticationChallenge(
       ArcGISAuthenticationChallenge challenge,
     ) async {
   
       try {
         // Initiate the sign in process to the OAuth server using the
         // defined user configuration.
         final credential = await OAuthUserCredential.create(
           configuration: _oauthUserConfiguration,
         );
   
         // If sign in was successful, then continue with the provided
         // credential.
         challenge.continueWithCredential(credential);
       } on ArcGISException catch (error) {
         // The sign in was canceled or there was some other error.
         final e = (error.wrappedException as ArcGISException?) ?? error;
   
         if (e.errorType == ArcGISExceptionType.commonUserCanceled) {
           // Cancel the request that initiated the challenge.
           challenge.cancel();
         } else {
           // Handle the challenge without a credential, causing it to fail
           // with the original authentication error.
           challenge.continueAndFail();
         }
       }
     }
   }

2. Set an instance of the class on the AuthenticationManager.arcGISAuthenticationChallengeHandler property of the ArcGISEnvironment.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
       // `this` represents an instance of the class that implements the
       // ArcGISAuthenticationChallengeHandler.
       ArcGISEnvironment
           .authenticationManager.arcGISAuthenticationChallengeHandler = this;
   

Network authentication challenge handler

The NetworkAuthenticationChallengeHandler is used to handle authentication challenges from ArcGIS secured resources that require network credentials, such as Integrated Windows Authentication (IWA) or Public Key Infrastructure (PKI). Handle the challenge by returning one of the following subclasses of the NetworkAuthenticationChallenge sealed class.

• continueWithCredential(NetworkCredential) - Handles the challenge with the specified credential.

• continueAndFail() - Handles the challenge without a credential, causing it to fail with the original authentication error.

• cancel() - Cancels the request that initiated the challenge.

1. Create a class that implements the NetworkAuthenticationChallengeHandler protocol to handle Network authentication challenges.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   // Define a Network authentication challenge handler.
   class MyNetworkChallengeHandler
     implements NetworkAuthenticationChallengeHandler {
   }

2. Set an instance of the class on the AuthenticationManager.networkAuthenticationChallengeHandler property of the ArcGISEnvironment.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   // Create the challenge handler and set it on the authentication manager.
   final myNetworkChallengeHandler = MyNetworkChallengeHandler();
   
   ArcGISEnvironment.authenticationManager
     .networkAuthenticationChallengeHandler = myNetworkChallengeHandler;

Create and store credentials

When an authentication challenge is raised, your application can create a credential that is held in the ArcGIS and network credential stores provided by the AuthenticationManager.

• ArcGISCredentialStore stores ArcGIS credentials.
• NetworkCredentialStore stores Network credentials.

These credential stores exist for the lifetime of the application. They ensure that an authentication challenge is only raised if a matching credential does not exist in the store. If you want to avoid prompting users for credentials between application sessions, persist the credential stores by using the static method initPersistentStore() on the ArcGIS credential store.

1
2
ArcGISEnvironment.authenticationManager.arcGISCredentialStore =
    await ArcGISCredentialStore.initPersistentStore();

During application sign-out, you should revoke all tokens and clear all credentials from the credential stores.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
  @override
  void dispose() {
    // Remove the challenge handler from the ArcGIS environment.
    ArcGISEnvironment
        .authenticationManager.arcGISAuthenticationChallengeHandler = null;

    // Revoke OAuth tokens and remove all credentials to log out.
    Future.wait(
      ArcGISEnvironment.authenticationManager.arcGISCredentialStore
          .getCredentials()
          .whereType<OAuthUserCredential>()
          .map((credential) => credential.revokeToken()),
    ).catchError((error) {
      // Handle errors.
    }).whenComplete(() {
      ArcGISEnvironment.authenticationManager.arcGISCredentialStore.removeAll();
    });

    super.dispose();
  }