ArcGIS Online and Portal for ArcGIS

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

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

  • This mode is not applicable for dynamic load balancing.

  • When logging on to ArcGIS Online, 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.


Activates the ArcGIS Online user administration. Possible values are true or false. The default value is false.

The preconfigured users admin and editor can still be used.

This value contains the domain name of the ArcGIS Online organization. The default value is If the value is set to an organization, registrations are only possible for users of this organization.


This value defines the lifetime of the token, which is retrieved with the login at ArcGIS Online. The default value is 60 (1 hour). This value influences the time after which a new login is necessary if protected resources are used by ArcGIS Online.

security.integrated.agol.tokenreferer=<mapapps basis url>

Here the external base URL of the map.apps installation must be specified, for example https://<yourserver>/mapapps. If the value does not match the URL in the user’s browser, the token generated by ArcGIS Online is not applicable and no protected resources can be queried, even if the actual login is successful.

The configuration might look like this:


Use of ArcGIS Online properties as roles in map.apps

Automatic assignment


ArcGIS Online roles are translated by default as follows:

ArcGIS Online role map.apps role Description



ArcGIS Online administrators become map.apps administrators.



ArcGIS Online publishers become map.apps editors.

All other roles are taken over by ArcGIS Online without changes, for example org_user.


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

ArcGIS Online group map.apps role

Forest (ID: a24534, Owner: user1)


Water (ID: a345b4, Owner: user2)



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


Adjustment of the assignment

The way ArcGIS Online 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 an ArcGIS Online Role
<util:map id="agolRoleMapping">
    <!-- ArcGIS Online administrator becomes map.apps administrator -->
    <entry key="org_admin" value="maAdmin"/>

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

    <!-- ArcGIS Online user gets "user" role in map.apps -->
    <entry key="org_user" value="user"/>
Rename an ArcGIS Online 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"/>
Rename an ArcGIS Online organization to a map.apps role
<util:map id="agolRoleMapping">
    <!-- ArcGIS organization "" becomes role "MyOrganization" in map.apps -->
    <entry key="" value="MyOrganization"/>

Restrict login to users of certain organizations

To restrict the ArcGIS Online registration to certain organisations, 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 -->

Consume protected webmaps and services

ArcGIS Online user authentication

If a protected resource (for example webmap) is requested from ArcGIS Online, an authentication dialog is opened, where users can enter their ArcGIS Online credentials.

Following configuration options are available to change the mechanism.


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


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.


Defines the base URL of ArcGIS Online or the central ArcGIS Portal installation. The default value is // The value can be changed to an ArcGIS Online organization sub domain URL. 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.


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

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

OAuth Redirect URLs
// Popup Modus

// Browser Redirect Modus -> URL der App 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>"

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

"oauthUsePopup": false

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

"arcgisPortalUrl": "<organistations url>"

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

The parameters can be edited in the manual configuration.

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

  • agolauthn

  • authentication

  • forcelogin

oauth config properties