How partners can set up a single sign-on experience with ArcGIS: part 2

Want to make your ArcGIS apps easier for your customers to access? In this second part of our blog post series, Esri Canada technical solutions specialist Brianna Kelly and solution architect John Osborne demonstrate how to build a web mapping application that authenticates with the ArcGIS Enterprise environment configured in part one.

In part one of this series, we configured SAML logins to authenticate ArcGIS Enterprise users with Auth0. If we were just using ArcGIS apps licensed to users in ArcGIS Enterprise, the configuration would be complete. However, many of you are using ArcGIS Enterprise as part of a larger solution you’re offering to your customers. You’re also likely using one or more ArcGIS Developer technologies, including APIs, Tools and Location Services, to customize and add advanced GIS functionality to your applications.

In this second part of the blog post series, we’ll show you how to customize an Auth0 JavaScript sample app to include an ArcGIS Maps SDK for JavaScript web mapping application.

The steps in this blog post series are also available on GitHub. Our repository on GitHub also includes optional steps mentioned in this blog post. 

Want to find out more about becoming a member of the Esri Partner Network? Get more information now.

Before you start

To follow along with this tutorial, you’ll need, at a minimum:

• ArcGIS Enterprise 11 (minimum version 10.9.1) – Administrator account with privileges
• Lite Partner User Type annual subscription (available to Partners only) or Viewer User Type annual subscription
• Auth0 Account – Auth0 free plan
• Auth0 JavaScript Login Tutorial
• Auth0 User – A user defined in Auth0 who will be assigned administrator privileges in ArcGIS Enterprise

At the end of this blog post, the Auth0 JavaScript sample app will incorporate an ArcGIS Maps SDK for JavaScript web mapping app that accesses content secured by ArcGIS Enterprise using web single sign-on.

Now that we’ve introduced what will be covered in this tutorial and the technical requirements, let’s dive in!

Part 1: Download the Auth0 Single Page Application JavaScript Sample App

Important: The Auth0 JavaScript sample app requires that either NODEJS LTS or Docker be installed. 

1. Log into your Auth0 account. From your Auth0 dashboard, click on Applications, then select your ArcGIS app.
2. Navigate to the Quick Start tab.
3. Select JavaScript to open the JavaScript tutorial.
4. In the JavaScript: Login tutorial, click DOWNLOAD SAMPLE. Follow the Auth0 Tutorial.

For additional testing steps, read the “Optional Step: Test the Auth0 JavaScript Sample App” part of our README file on GitHub.

The Auth0 JavaScript sample app will be responsible for prompting a user to log in. In Part 3 of this tutorial, you’ll add an additional webpage that features a web map containing secure content.

Part 2: Register an Application with ArcGIS Enterprise

1. Log into your ArcGIS Enterprise organization as the user that will own the application.
2. Under the Content tab, click on New item.
3. In the New item dialogue box, select Application.
4. For Application type, select Web mapping, then set the URL to http://localhost:3000 and click Next.
5. Provide a title, tags and summary for the App Registration, then click Save.
6. Once the item is created, click the Settings tab.
7. Under Web Mapping Application, click Register.
8. Set the Redirect URL to http://localhost:3000/map.html then click Add.
9. Select Register.

The App ID generated by registering the Auth0 JavaScript sample app allows users to sign into ArcGIS Enterprise with OAuth 2.0. The App ID will be used in the next set of steps.

Part 3: Add the map.html page to the Auth0 JavaScript sample app

The map.html file referred to in this section was created using two ArcGIS Maps SDK for JavaScript code samples available from Esri's ArcGIS Developers site:

• Intro to Feature Layer
• Access ArcGIS Online items using OAuth 2.0

1. Create a new file called map.html in the /01-login/public folder of the Auth0 Sample App.
2. Navigate to the map.html file on GitHub.
3. Copy raw contents and paste to your map.html file in /01-login/public.
4. In ArcGIS Enterprise, under the Content tab, click on your web app then click the Settings tab.
5. Under Web Mapping Application, click Registered Info.
6. Copy the App ID. You’ll use it in an upcoming step.
7. In the map.html file in the /01-login/public folder, replace the following URLS:
   1. your_portal_url – ArcGIS Enterprise portal URL
   2. your_app_id – The App ID from your registered app in ArcGIS Enterprise
   3. your_fs_service_URL – The secure layer you wish to use in the map. This example uses the SampleWorldCities service that is created by default when ArcGIS Enterprise is installed.
8. Save.
9. Open /01-login.index.html.
10. Find the Home navigation item. The code looks like this:

```
    <li class="nav-item">
        <a href="/" class="nav-link route-link">Home</a>
    </li>
    ```

11. Add the following code under the Home item. This will cause users to navigate to the map.html page.

```
<li class="nav-item">
            <a href="/map.html" class="nav-link route-link">Map</a>
        </li>
 ```

12. The code should now look like this:

    ```
    <ul class="navbar-nav mr-auto">
        <li class="nav-item">
            <a href="/" class="nav-link route-link">Home</a>
        </li>
        <li class="nav-item">
            <a href="/map.html" class="nav-link route-link">Map</a>
        </li>
    </ul>
    ```

13. Run the application.
14. Navigate to http://localhost:3000, log into the web application and then click on the Map tab to load the map.

A new webpage with an ArcGIS Maps SDK for JavaScript web map has now been added to the Auth0 JavaScript sample app. The web map accesses secure content from ArcGIS Enterprise. The new webpage can be accessed from the Map tab created on the Auth0 JavaScript sample app landing page. When the user clicks on the Map tab, they will be taken to the Sign in to ArcGIS Enterprise with Esri screen. To remove this login screen, follow this next set of steps.

Part 4: Disable the default ArcGIS Enterprise login screen

Important: Before completing these steps, ensure that at least one Auth0 user is assigned the Administrator role in ArcGIS Enterprise. If an Auth0 user is not assigned as an administrator, portal administration will need to be performed programmatically. For more information on how to create an Auth0 user, review the Auth0 help topic Create Users.

1. Log into your ArcGIS Enterprise as an administrator.
2. Under the Organization tab, go to Members. Ensure that there is at least one member in the ArcGIS Enterprise organization with an Administrator role and that the user also has an existing account in Auth0. 
3. Under the Organization tab, go to Settings and select Security.
4. Under Logins, disable the ArcGIS login.
5. Navigate to http://localhost:3000, log into the web application and then click on the Map tab to load the map.

When a user logs into the Auth0 Sample App and clicks on the Map tab, the Sign in to ArcGIS Enterprise with Esri screen no longer prompts users. 

Any questions?

This concludes our two-part blog post series on single sign-on. (Read part 1 here.) By following the steps from both parts of the blog post series, you can offer a single sign-on experience when using ArcGIS Enterprise and ArcGIS Developer APIs and SDKs. Please note that if you’d like to include Esri technology as part of a commercial offering, you’ll need an approved sales authorization. To find out more about the sales authorization process or about adding Esri technology to your commercial offerings, feel free to reach out to us at bpp@esri.ca.