OAuth Layer Authentication

This tutorial will guide you through authenticating an ArcGIS feature layer using OAuth 2.0. You'll learn how to set up OAuth authentication to access protected ArcGIS layers that require user login credentials.

Use Case Context: Authenticate a Protected ArcGIS Layer

In this tutorial, we'll walk through the process of accessing an ArcGIS feature layer (Feature Service) that requires authentication. This is commonly needed when working with private or organization-specific layers hosted on ArcGIS Online or ArcGIS Enterprise that require users to have proper Esri login credentials.

---

Prerequisites

Before you begin, make sure you have completed the following steps:

• ArcGIS Hosted Layer - You need the URL for your hosted layer that requires authentication. (Learn more) This layer URL will also need to be added to your OAuth configuration.
• ArcGIS OAuth 2.0 Configuration - You must configure OAuth 2.0 credentials in ArcGIS and obtain the client ID. (Learn more)

By the end of this tutorial, you'll be able to:

• Create or configure an OAuth authentication profile in MapTaskr.
• Add protected ArcGIS layers to your Layer Gallery using OAuth authentication.
• Successfully authenticate and display protected ArcGIS content in your maps.

---

Step 1: Create or Configure OAuth Authentication Profile

The OAuth authentication profile setup depends on your MapTaskr installation type. Choose the method that applies to your situation:

Option A: Fresh Install of Release 1

If you have a brand new, fresh installation of MapTaskr Release 1 or newer, the required OAuth profile is already pre-configured for you.

1. Navigate to Auth Manager in the Advanced section.

2. Look for the pre-built profile called "ArcGIS Online (Authorization code with PKCE)".

3. Open this profile and navigate to the Auth Request Details tab.

4. Locate both sections where {{clientid}} is used (Authorization Endpoint and Token Request Body) and replace it with your client ID from the prerequisite step ArcGIS OAuth 2.0 Configuration.

5. Click Save to save your profile.

Option B: Manual Creation (For Upgrades or Custom Setups)

If you're upgrading from an earlier version or need to create the profile manually:

1. Navigate to Auth Manager in the Advanced section.

2. Click Add New Profile.

3. On the Auth Details tab, configure the basic settings:

   • Auth Profile Name: ArcGIS Online (Authorization code with PKCE) (or your preferred name)
   • Additional URL Parameters: Add the following parameter:

   Name	Value	Notes
   token	{{access_token}}	Enter exactly as shown (including the curly braces)

4. Now switch to the Auth Request Details tab and configure the OAuth settings:

   • Check Has Auth Request checkbox
   • Check Use OAuth checkbox

5. Configure the Authorization Endpoint section:

   • Authorization URL: https://www.arcgis.com/sharing/rest/oauth2/authorize
   • Authorization Query Parameters: Add the following parameters:

   Name	Value	Notes
   client_id	{{client_id}}	This is your Client ID from the prerequisites
   code_challenge	{{challenge}}	Enter exactly as shown (including the curly braces)
   code_challenge_method	S256
   response_type	code
   expiration	20160

6. Configure the Token Endpoint section:

   • Token URL: Select POST and enter: https://www.arcgis.com/sharing/rest/oauth2/token
   • Token Headers: Add the following header:

   Name	Value
   Content-Type	application/json; charset=UTF-8

7. Configure the Token Request Body section (x-www-form-urlencoded): Add the following parameters:

   Name	Value	Notes
   client_id	{{client_id}}	This is your Client ID from the prerequisites
   grant_type	authorization_code
   code	{{code}}	Enter exactly as shown (including the curly braces)
   redirect_uri	{{redirectUri}}	Enter exactly as shown (including the curly braces)
   code_verifier	{{verifier}}	Enter exactly as shown (including the curly braces)

8. Configure the token refresh settings:

   • Set Token needs refreshing every to match your business requirements (value in minutes, e.g., 1440 for 24 hours, 10080 for 7 days)
   Token Expiration Impact

   When the token refresh timeout expires, the authentication table will clear all approved authentications. This means all users who want to access this layer will need to authenticate again with their ArcGIS credentials.

   Consider your users' workflow when setting this timeout - shorter periods provide better security but require more frequent re-authentication.

9. Click Save to save your profile.

Option C: Import from ZIP File (For Upgrades)

If you're upgrading and prefer to import the pre-configured profile:

1. Download the OAuth profile ZIP file from MapTaskr Resources.

2. Navigate to Package Manager in the Maptaskr Power Maps Admin application.

3. Click Import Configuration.

4. Select the downloaded ZIP file (This will trigger the import process).

5. Navigate to the Authentication Manager to verify that the "ArcGIS Online (Authorization code with PKCE)" profile has been imported successfully.

6. Open this profile and navigate to the Auth Request Details tab.

7. Locate both sections where {{clientid}} is used (Authorization Endpoint and Token Request Body) and replace it with your client ID from the prerequisite step ArcGIS OAuth 2.0 Configuration.

8. Click Save to save your profile.

---

Step 2: Add Your Protected Layer

Now that you have your OAuth authentication profile configured, you can add your protected ArcGIS layer to the Layer Gallery.

1. Navigate to the Layer Gallery.

2. Click Add Layer.

3. Configure your layer with the following settings:

   • Layer Type: Select the layer type
   • Layer Group: Select the group this layer should sit within
   • Service URL: Enter the URL of your protected ArcGIS feature layer
   • Authentication Profile: Select "ArcGIS Online (Authorization code with PKCE)" (or the name you used if created manually)

4. Click Query. This will trigger a page redirect (this will open in a new page) which will first take you to an authentication validation page, then will redirect you to the ArcGIS login page for authentication. Please enter your username and password, then click Allow.

5. Once authentication is successful, you will be redirected back to the Add layer page and the console log will display a successful query.

6. Complete the remaining layer configuration settings as needed for your specific layer.

7. Click Save Layer.

info

For detailed steps on adding layers, refer to the Adding a Layer guide.

---

Step 3: Test Your OAuth Authentication

1. Create a new map profile or edit an existing one where you want to use your protected layer.

2. Go to the Preconfigured Layers tab in your profile. Note: This doesn't have to be a preconfigured layer - this can also be a layer that a user can add from the gallery.

3. Click Add Layer and select your newly added protected layer from the gallery.

User Authentication Required

If the user adding this layer to the preconfigured layers tab is different from the person who created the layer or their authentication token has expired, they will also need to authenticate with their ArcGIS credentials.

What happens during authentication:

1. Adding the layer will trigger the OAuth authentication process
2. A new tab will open for authentication validation
3. You'll be redirected to the ArcGIS login page
4. After entering your credentials and clicking Sign in, you'll be redirected back to the preconfigured layers tab
5. The layer will be successfully added to your preconfigured layers list

This ensures that each user has proper access permissions to the protected layer.

tip

If a user has authenticated and their authentication token has not expired, then they will have no interrupted workflow when adding, viewing, and interacting with the authenticated layer.

4. Save your profile configuration.

5. Navigate to where your map profile is used (dashboard or record form).

6. When the map loads, you should be prompted to authenticate with your ArcGIS credentials if you haven't already authenticated and your authentication token hasn't expired.

7. After successful authentication, your protected layer should display on the map. Otherwise, it won't be added to the map.

---

Authentication Flow in Action

Once configured, here's what users will experience:

1. Initial Load: When a user first accesses a map containing your protected layer, they will see an authentication prompt.

2. OAuth Login: Users will be redirected to ArcGIS Online to enter their credentials securely.

3. Authorization: After successful login, users will be redirected back to MapTaskr with the necessary tokens.

4. Layer Access: The protected layer will now load and display on the map with full functionality.

5. Token Management: MapTaskr handles token refresh automatically, so users won't need to re-authenticate frequently.

---

Troubleshooting Common Issues

Layer Not Loading:

• Verify that your OAuth Client ID is correct and matches the one configured in ArcGIS.
• Ensure the layer URL is accessible and correctly formatted.
• Check that your authentication profile settings match the ArcGIS OAuth configuration.

Authentication Loop:

• Verify that your redirect URLs in ArcGIS OAuth settings include your MapTaskr domain.
• Ensure PKCE is enabled if using the recommended authentication method.

Permission Denied:

• Confirm that the authenticating user has appropriate permissions to access the layer in ArcGIS.
• Check that the layer is shared with the appropriate users or groups in ArcGIS Online.

tip

For additional support with OAuth configuration, contact the MapTaskr support team with your specific error messages and configuration details.

---