Use OAuth 2.0 authentication

This topic describes how to use OAuth 2.0 in an ArcGIS Runtime SDK for Java SE application to authenticate users into the ArcGIS platform via a Portal instance. For general information about OAuth 2.0 in ArcGIS and how to use it in different scenarios depending on the SDK, see OAuth 2.0 authentication.

As a developer using the ArcGIS platform, you can use OAuth 2.0 to build the following two types of applications:

  • Applications that target end users of the ArcGIS platform—These apps need to allow users to log in to the platform via the application. These types of logins are known as user logins.
  • Applications that target end users who are unknown to the ArcGIS platform—These apps need to log in to the platform for the user. These types of logins are known as app logins.

The Portal class contains methods to allow OAuth 2.0 authorization for both of these use cases.

User logins

User logins allow application users to authorize themselves on an ArcGIS portal and access secured resources made available to their particular user identity, without the application handling the user's credentials.

There are two main steps involved in the authentication process:

  1. Obtain an authorization code for the user. This requires the application to open a browser window and direct the user to a specific URL where they will log in using their username and password.
  2. Once the authorization code has been obtained, the application needs to exchange it for an access token to complete the authorization process. The access token will then be automatically used to access any secured resources shared with the user.

To perform these steps, use the Portal method doOAuthUserAuthenticate. This method takes the following parameters:

  • A client ID, obtained when registering an app with an ArcGIS portal.
  • A callback (GetAuthCodeCallback) that you need to use to direct the user to a login page and obtain an authorization code upon successful authentication of the user into the ArcGIS portal. This corresponds to step 1 above.
  • A second callback used when authorization is complete, for example, when the access token has successfully been obtained. This corresponds to step 2 above.
  • An optional parameter: a client secret, also obtained during app registration.

The client secret parameter is optional for the user login scenario. Using it is not recommended, because storing it in the app exposes it to extraction. Instead, authentication of the app by the platform during the user login is based on the acceptance of the displayed identity of the app corresponding to the client ID by the user.

The main work you need to do as a developer is to implement the getAuthCode method in the GetAuthCodeCallback instance you'll pass into Portal's doOAuthUserAuthenticate method. This method needs to take an authorization URL, which it receives as a parameter, display the web page at this URL (which is a user login screen), and return the authorization code obtained when a user successfully logs in.

The following code snippet shows an example partial implementation of the GetAuthCodeCallback interface:

GetAuthCodeCallback authcodeCallback = new GetAuthCodeCallback() {
  // the authorization code you need to obtain from the user logging in
  String authorizationCode = "";
 
  @Override
  public String getAuthcode(String authorizationUrl) {
    final CountDownLatch latch = new CountDownLatch(1);
 
    // This method call needs to pop up a dialog displaying the web page at 'authorizationURL', 
    // which will show an ArcGIS sign-in dialog. 
    // 'MyAuthorizeCallback' is a custom callback used to pass the authorization 
    // code through to the GetAuthCodeCallback on successful initialization
    AuthorizationDialog.authorize(mainWindow, authorizationUrl, new MyAuthorizeCallback() {
 
      @Override
      public void authorized(String authCode) {
        code = authCode;
        // authorization code obtained - countdown the latch
        latch.countDown();
      }
    });
    try {
      // wait until the latch is counted down to 0
      latch.await();
    } catch (InterruptedException e) {
      // handle exception as desired
    }

    return authorizationCode;
  }
};

There are several ways to display the web page at authorizationURL. Because the Java Swing HTML support can be inadequate, a good alternative is to use a JavaFX WebView component. You can then use the Swing JFXPanel to display JavaFX components in a Swing-based application as described in Oracle's document Integrating JavaFX into Swing Applications.

Not shown in the previous code snippet but crucial to the OAuth 2.0 implementation is to obtain the authorization code from the browser component. When the user successfully logs in through the web page at authorizationURL, the browser will redirect to a URL containing the authorization code, for example https://www.arcgis.com/sharing/oauth2/approval?code=SplxlOBeZQQYbYS6WxSbIA. In addition, the title of the web page will be of the form: <title>SUCCESS code=SplxlOBeZQQYbYS6WxSbIA</title>. In your application source code, you need to extract the authorization code from either of these strings using standard Java String methods.

Once you have obtained the authorization code and made it the return value of the getAuthCode method as shown above, the second callback will use the code to internally obtain an access token and authenticate the user into the portal. When this step completes successfully, the second callback will be called, at which point you can take an action such as informing the user they are logged in, showing some new options for the signed-in user, and so on.

App logins

For the case where the application targets users unknown to the ArcGIS platform, the application itself can log in to the ArcGIS platform and access secured resources shared with the application. To perform this app login, the Portal class provides the method doOAuthAppAuthenticate, which takes as parameters the client ID and corresponding client secret, as well as an optional callback to take an action upon successful or unsuccessful authentication.

The following code sample shows how to use this method:

_portal.doOAuthAppAuthenticate(CLIENT_SECRET, CLIENT_ID, new CallbackListener<Portal>() {
 
  @Override
  public void onError(Throwable e) {
    // handle the error, alert the user
  }
 
  @Override
  public void onCallback(Portal objs) {
    // take some action upon successful authentication
    System.out.println("app signed in!");
  }
});

While it is optional (and not recommended) to use the client secret for the user login scenario, both the client ID and client secret must be used to perform an app login. Care must be taken to prevent malicious users from extracting the client secret from the application. This scenario is described in more detail in the topic App logins and OAuth 2.0 with some suggestions as to how to secure the client secret.


In this topic
  1. User logins
  2. App logins