ArcGIS Enterprise portal and ArcGIS Online

Because the following information applies equally to ArcGIS Enterprise portal and ArcGIS Online, only portal is referred for better readability.

ArcGIS Enterprise portal can be used as user administration for map.apps. This means that a user can log in to map.apps with a portal account. Groups and roles of a portal user are translated into roles for map.apps. Connecting to portal 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)

Restrictions

  • This mode is not applicable for dynamic load balancing.

  • When logging on to portal, a token is registered for the use of protected resources. Because this is not renewed, a new login is necessary after some time.

Configuration of the connection

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

security.integrated.agol.enabled

Activates the portal user administration.
Allowed values are true or false. The default value is false.

The preconfigured users admin and editor can still be used.
security.integrated.agol.organization

Portal or ArcGIS Online organization to connect map.apps to.
The default value is www.arcgis.com. If you are connecting map.apps with portal, enter hostname and path of the portal web adaptor, for example gis.example.com/portal. When connecting to an ArcGIS Online organization, enter the fully qualified hostname of the organization, for example myorganization.map.arcgis.com.

security.integrated.agol.expirationInMinutes

Lifetime of the token, which is retrieved with the login at portal.
The default value is 60 (1 hour). This value influences the time after which a new login is necessary when using protected portal resources.

security.integrated.agol.tokenreferer

External base URL of the map.apps installation, for example https://apps.example.com/mapapps. The value must match the URL in the browser as seen by the user. Otherwise the portal token is not applicable and no protected resources can be queried, even if the actual login is successful.

The configuration might look like this:

Example: Connect map.apps with portal
security.integrated.agol.enabled=true
security.integrated.agol.organization=gis.example.com/portal
security.integrated.agol.tokenreferer=https://apps.example.com/mapapps
Example: Connect map.apps with an ArcGIS Online organization
security.integrated.agol.enabled=true
security.integrated.agol.organization=myorg.maps.arcgis.com
security.integrated.agol.tokenreferer=https://apps.example.com/mapapps

Use properties of portal users as roles in map.apps

Automatic assignment

Roles

Portal roles are translated by default as follows:

ArcGIS Online role map.apps role Description

org_admin

maAdmin

Portal administrators become map.apps administrators.

org_publisher

maEditor

Portal publishers become map.apps editors.

All other roles are adopted from portal without changes, for example org_user.

Groups

Portal groups consist of an ID, a title and an owner. Because the ID of a group is not directly visible in portal and assignment is therefore difficult, a group is translated into a map.apps role in the form <Title>::<Owner> by default.

ArcGIS Online group map.apps role

Forest (ID: a24534, Owner: user1)

Forest::user1

Water (ID: a345b4, Owner: user2)

Water::user2

Organization (ArcGIS Online only)

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

Example: myorg.maps.arcgis.com

Adjustment of the assignment

The way portal roles, groups, and organizations are translated into map.apps roles can be customized in the spring-security-agol-config.xml file. The entry agolRoleMapping has to be edited.

Rename a portal role
<util:map id="agolRoleMapping">
    <!-- Portal administrator becomes map.apps administrator -->
    <entry key="org_admin" value="maAdmin"/>

    <!-- Portal Online publisher becomes map.apps editor -->
    <entry key="org_publisher" value="maEditor"/>

    <!-- Portal user gets "user" role in map.apps -->
    <entry key="org_user" value="user"/>
</util:map>
Rename portal group to map.apps role
<util:map id="agolRoleMapping">
    <!-- ArcGIS group "Test" with ID "Q123469" and owner "exception" becomes role "TestUser" in map.apps -->
    <entry key="Q123469" value="TestUser"/>

    <!-- Alternatively, the default mapping can be used -->
    <entry key="auser@@Test" value="TestUser"/>
</util:map>
Rename ArcGIS Online organization to map.apps role
<util:map id="agolRoleMapping">
    <!-- ArcGIS organization "myorganization.maps.arcgis.com" becomes role "MyOrganization" in map.apps -->
    <entry key="myorganization.maps.arcgis.com" value="MyOrganization"/>
</util:map>

Restrict login to users of certain organizations (ArcGIS Online only)

To restrict the ArcGIS Online registration to certain organizations, the following options are available:

  • Configuration of the parameter security.integrated.agol.organization with the domain name of a specific organization

  • Change the configuration in the spring-security-agol-config.xml file. The entry agolAllowedOrganizations must be edited.

<util:set id="agolAllowedOrganizations">
    <!-- Add concrete domain names -->
    <value>myorg.maps.arcgis.com</value>
</util:set>

Consume protected webmaps and services

Login to portal

If a protected portal resource (a webmap, for example) is requested, an authentication dialog is opened, where users sign in with their portal credentials.

Following configuration options are available to change the mechanism.

client.config.allowCredentialsOverHTTP

Defines that authentication credentials are allowed to be transported over HTTP connections.
Allowed values are true or false. In the case of ArcGIS Online HTTPS is used always. Set this parameter to true, to request a protected ArcGIS Server that only supports HTTP.

client.config.persistIdentityManagerState

Defines that the state of the JavaScript object esri/IdentityManager is made persistent within the browser.
Only tokens are saved, not the users credentials. With this option set to true a users is authenticated as long as the tokens are valid.

esri.api.arcgisPortalUrl

Defines the base URL of ArcGIS Online or the central ArcGIS Enterprise portal installation.
The default value is //www.arcgis.com. The value can be changed to the hostname of an ArcGIS Online organization. This is important if OAuth is used or if the ArcGIS Online organization has configured an enterprise login, because in this case an organization specific authentication dialog is shown.

OAuth

A modification of the portal authentication mechanism is the use of the OAuth2 protocol. The user is redirected to a central authentication page of portal instead of showing an app specific authentication dialog. The precondition for using this protocol is the registration of the map.apps app in portal.

During app registration a redirect URL is required. The following two options are allowed. It is allowed to register both at a time.

  • Popup mode: https://<server>:<port>/<mapapps_context>/account/oauth-callback.html

  • Browser redirect mode: https://<server>:<port>/<mapapps_context>/resources/apps/<appname>/index.html (URL of an app’s index.html)

As a result of a successful registration, the app gains an "app ID".

To activate OAuth, the following parameters have to be configured in the "properties" section of the app configuration:

"oauthEnabled": true

Activates the OAuth support.

"oauthAppId": "<app-ID>"

App ID created during the registration of the app at ArcGIS Online.

"oauthUsePopup": false

Defines that the authentication process shows a popup window instead of redirecting the main browser window.
This property is optional. The default value is false. The user’s browser might block popup windows.

"arcgisPortalUrl": "<organization-url>"

Overwrites the global configuration parameter esri.api.arcgisPortalUrl.
This property is optional. If the value points to an ArcGIS Online organization, an organization-specific authentication dialog is shown.

"portalItemId": "<item-id>"

Item ID of the map.apps app inside portal.
This property is optional, but required if the access to the app should be linked to the sharing state of a portal item. After successful authentication of a user, access to this portal item is tested. If access is forbidden, access to the app is also forbidden.

The parameters can be edited in the App Editor.

Additionally, it is necessary to add the following bundles to the app, to enforce OAuth when using the map.apps:

  • agolauthn

  • authentication

  • forcelogin

  • portal-app-security

oauth config properties