Authorization

Authorization is required for users who wish to access data that is in a non-public ArGIS Online (AGOL) organization, in an ArcGIS Enterprise portal, or wish to upload data to or modify data in AGOL.

Authorization is done using OAuth2. There are two ways to authenticate with OAuth2: either by using a a code or a client flow. The recommendation for most people is to utilize code based authentication.

Note: users of arcgisbinding can use auth_binding() to utilize the tokens that result from arc.check_portal().

Tip: use client based authorization for non-interactive work.

Code based authorization

To use code based authorization use the auth_code() function. This requires a client ID. A client ID is a public identifier to an application that you will authenticate against. This is the only method of authorization that provides you with a refresh token.

Getting the Client ID

A client ID would likely be provided by an admin of an AGOL organization or ArcGIS Enterprise. In the case that you don’t have one you can more than likely create one. To create a client application log into your portal and create a new item.

Create a new Developer credentials

Ensure the redirect URL is urn:ietf:wg:oauth:2.0:oob and keep the other default selections. Press next and fill out additional fields.

You will be redirected to the content page. You will see credentials for your application. Do not share these.

By default environment variables will be used by auth_code(). To edit your environment variables with your newly created credentials use usethis::edit_r_environ() which will open an .Renviron file for you.

User level environment variables will be used by default. If you want to use a project level .Renviron file use usethis::edit_r_environ("project").

Add the following lines to your .Renviron file.

ARCGIS_CLIENT=your-client-id
ARCGIS_SECRET=your-super-secret-key

The ARCGIS_SECRET environment variable will only be used in auth_client() and not necessary for auth_code().

Authorizing

First, load the library.

library(arcgis)

Next run auth_code() which will open a tab in your browser. If you are authorizing to somewhere other than AGOL, set the host argument—e.g. auth_code(host = "https://portal.my-company.com")

token <- auth_code()

You will be prompted to sign in to your portal.

Once you’ve signed in, copy the code that appears, and return to R. Enter the code into the console without any modifications and press enter.

Your authorization will have completed.

token
#> <httr2_token>
#> token_type: bearer
#> access_token: <REDACTED>
#> expires_at: 2023-03-03 13:21:40
#> refresh_token: <REDACTED>
#> username: your-user
#> ssl: TRUE
#> refresh_token_expires_in: 1209599

Refreshing tokens

auth_code() tokens can be refreshed. These tokens come with a refresh token that can be exchanged for a new token. This can be done with refresh_token(). It requires the original token, client ID, and hostname (which is https://arcgis.com by default).

refresh_token(token)
#> <httr2_token>
#> token_type: bearer
#> access_token: <REDACTED>
#> expires_at: 2023-03-03 15:52:13
#> username: user-name
#> ssl: TRUE
#> refresh_token: <REDACTED>

Additionally the function validate_or_refresh_token() is provided. This can be useful if you have a very long running job that may exceed your token’s validity. If your token is a expired, it will be refreshed. If it is not expired, and will not expire within the refresh_threshold, it will be returned.

Client authorization

For non-interactive workflows a client OAuth2 flow is more appropriate. This approach does not require you to copy and paste a code from the browser into your R session. This method does not generate a refresh token, though.

Use auth_client() to perform client based authorization. auth_client() has a secret argument which, by default, uses the environment variable ARCGIS_SECRET which was set in your .Renviron file above. Running

auth_client()
#> <httr2_token>
#> token_type: bearer
#> access_token: <REDACTED>
#> expires_at: 2023-03-03 17:12:48

Legacy Password authorization

If you find yourself on a legacy system that requires username and password authorization, you can accomplish this with auth_password(). While this method of authorization is not recommended, it is still possible.

auth_user() has the arguments username and password which, by default, use the .Renviron environment variables ARCGIS_USER and ARCGIS_PASSWORD. It is strongly recommended that you use environment variables and never store your credentials in plain text in your scripts.

auth_user()
#> <httr2_token>
#> token_type: bearer
#> access_token: <REDACTED>
#> expires_at: 2023-03-03 15:18:21