ArcGIS Online

Using the OAuth 2.0 protocol, map.apps can delegate the authentication of users to ArcGIS Online. This means that a user can log in to map.apps with an ArcGIS Online account. Groups and roles of the ArcGIS Online user are translated into roles for map.apps.

Connecting to ArcGIS Online creates the following possibilities:

  • Assignment of roles for the use of map.apps Manager

  • Protection of apps

  • Protection of tools

  • Use of non-public content such as webmaps or layers without re-registration (single sign-on)

Connecting to ArcGIS Online has the following limitations:

  • Apps exported with the app export for native apps do not support the authentication. Apps with anonymous access are still supported.

Create connection between map.apps and ArcGIS Online

Connecting map.apps with ArcGIS Online is done in three steps:

  1. First, you register map.apps as a trusted app in ArcGIS Online.

  2. Then, you adjust the configuration of map.apps so that map.apps can delegate the registration to ArcGIS Online.

  3. Finally, you configure your apps to use the authentication information.

Step 1: Register map.apps in ArcGIS Online

map.apps must be registered as an application in ArcGIS Online to use single sign-on in ArcGIS Online. To do this, perform the following steps:

  1. Login to ArcGIS Online.

  2. Switch to the Content tab.

  3. Click New item and in the subsequent dialog click Application.

  4. A dialog for creating the new element is displayed. Use the following settings there:

    • Type: Web Mapping.

    • URL: URL of the map.apps installation, for example https://example.com/mapapps

  5. Click Next.

  6. Now set the other properties of the element as follows:

    • Title: map.apps

    • Folder: Select the folder where you want to save the item.

    • Categories (optional): You can set one or more categories for the element.

    • Tags: map.apps

    • Summary (optional): You can create a summary for the element, for example: Registration of map.apps at ArcGIS Online

  7. Click Save. The overview of the newly created element is displayed.

  8. Set additional registration properties by proceeding as follows:

    • In the app overview click Settings and go to section Web Mapping Application.

    • Click Register.

    • Specify the URL of your map.apps installation as the Redirect URI, for example https://example.com/mapapps.

    • Click Add to add the URI to the list of valid redirect URIs.

    • Click Register to close the dialog.

  9. After you have successfully registered the application, its registration data will be displayed, which you will need for the subsequent configuration of map.apps:

    • Store the displayed App ID somewhere.

    • Click Show secret and store the displayed App Secret.

      app secrets en

The registration is now complete and you can proceed with the configuration of map.apps.

URLs should start with https:// to ensure that secret tokens are always sent over a secure channel.

Step 2: Configure map.apps

The following parameters must be added or changed in the map.apps Configuration.

Configuration example
security.mode=OAUTH
esri.api.arcgisPortalUrl=https://myorganization.maps.arcgis.com
security.oauth.clientId=6nyEFYqYSYtu60Ws
security.oauth.clientSecret=fb3e3425976e4980a1793cbe6231f4b6
# Replace "0123456789" with an arbitrary string of at least 32 characters
security.sharedSecret=0123456789
security.mode

The value OAUTH specifies that the authentication is delegated to ArcGIS Online using the OAuth 2.0 protocol.

esri.api.arcgisPortalUrl

URL of your ArcGIS Online organization, for example https://myorganization.maps.arcgis.com.

security.oauth.clientId

App ID that has been created when map.apps has been registered as an application in ArcGIS Online.

security.oauth.clientSecret

App Secret that has been created when map.apps has been registered as an application in ArcGIS Online.

security.sharedSecret

The text you enter here will be used by map.apps as a key for encrypting data that needs to be exchanged between different parts of the application. To prevent unauthorized access or manipulation of data you should keep this secret private, like a password. You must create this key yourself. It must have a length of at least 32 characters for security reasons.

You can create a secure key with these commands, for example:

Windows PowerShell
> [Convert]::ToBase64String((1..32|%{[byte](Get-Random -Minimum ([byte]::MinValue) -Maximum ([byte]::MaxValue))}))
Linux
$ openssl rand -base64 32

In a scenario where, for example, multiple application instances are used for load balancing, all instances must use the same value.

Allow App Overview only for logged in users

To allow only people with a valid login to access the map.apps app overview, set the following configuration:

# this is used to specify the protected resource paths (which require authentication before use)
# add '/,/*.html' to protect the index.html
security.application.protectedResources=/,/*.html

Allow logins for multiple organizations

To allow logins to users of more than one organization, please set esri.api.arcgisPortalUrl to https://www.arcgis.com and additionally configure the parameter security.oauth.provider.arcgis.organizations as described in the following example:

Configuration example
esri.api.arcgisPortalUrl=https://www.arcgis.com
security.oauth.provider.arcgis.organizations=myorganization.maps.arcgis.com,otherorg.maps.arcgis.com

List all organizations separated by commas.

Access secured services from your ArcGIS Online organization

If you want to use services published in your organization, you have to configure the parameter security.oauth.tokenRules as described below:

Configuration example
security.oauth.tokenRules=https://services.arcgis.com/<organization-id>/arcgis,TOKEN

To find out the URL of your organization, proceed as follows:

  1. In ArcGIS Online switch to the Content tab and click on an arbitrary service of your organization.

  2. You find the service’s URL in its overview page, for example https://services.arcgis.com/ObdACOfl4Z5LP2D0/arcgis/rest/services/TestLayer/FeatureServer.

  3. Copy the required part from the URL. It is ObdACOfl4Z5LP2D0 in this example.

Replace <organization-id> with the previously determined value. For example:

security.oauth.tokenRules=https://services.arcgis.com/ObdACOfl4Z5LP2D0/arcgis,TOKEN

If you want to use services from multiple organizations, you have to provide all URLs separated by commas:

security.oauth.tokenRules=https://services.arcgis.com/<organization1-id>/arcgis,https://services.arcgis.com/<organization2-id>/arcgis,TOKEN

Step 3: Configure your apps

Finally, register each app in which a login via ArcGIS Online should be performed using the Register App in ArcGIS function in map.apps Manager. This step adds the authentication and portal-app-security bundles to the app and adds necessary entries in the properties section to the app configuration. Set the sharing settings in the created item in ArcGIS Online to specify who is allowed to access the app.

To use ArcGIS Online login without creating an item in ArcGIS Online, just add the bundle authentication to the app without registering the app. In this case, the app is approved via the settings in map.apps Manager.

Role assignment

map.apps grants access to protected resources depending on roles to which a user is assigned in map.apps. For example, only users assigned to the 'maAdmin' role can access the map.apps Manager. Additionally, you can make the availability of apps or tools dependent on specific roles.

When you configure ArcGIS Online to authenticate users, information from the corresponding ArcGIS Online account determines which roles are assigned to the user in map.apps. The list of roles of a user in map.apps is composed of the role and the groups that are assigned to the user within ArcGIS Online.

ArcGIS Online roles

The role to which a user is assigned in ArcGIS Online is translated by map.apps as follows:

ArcGIS Online role map.apps role Description

org_admin

maAdmin

ArcGIS Online administrators become map.apps administrators.

org_publisher

maEditor

ArcGIS Online publishers become map.apps editors.

roleX

roleX

All other roles are adopted from ArcGIS Online without changes.

If the ArcGIS Online access belongs to an organization, the domain name of the organization is registered as a map.apps role.

Example: myorganization.maps.arcgis.com

ArcGIS Online groups

The groups a person belongs to in ArcGIS Online are also translated into map.apps roles. Since multiple people can create ArcGIS Online groups with the same title, a group is translated into a map.apps role of the form <title>::<owner>.

ArcGIS Online group map.apps role

Forest (Owner: user1)

Forest::user1

Water (Owner: user2)

Water::user2