Single Sign-On with Portal for ArcGIS and ArcGIS Online

Since 4.8.0

security.manager helps client applications interact with security.manager services and Portal for ArcGIS – including ArcGIS Online – in a single sign-on manner. The goal is to let the user sign in at the Portal with her Portal identity and let her use security.manager services or protected applications without a second login required. This can be achieved by the following two approaches, each having different implications.

(A) ArcGIS Server Federation

This approach requires to register a security.manager-protected ArcGIS Server endpoint as a federated service with the Portal. This is the recommended way to intgerate protected services into Portal applications and works with all Esri clients, including the ArcGIS API for JavaScript. security.manager identifies users based on the ArcGIS server token sent with every request.

This approach does not work with ArcGIS Online as service federation is not supported in ArcGIS Online.
(B) security.manager Domain Cookie

This way of integrating Portal users with security.manager requires client applications to send a separate request to security.manager. It is used to obtain a domain cookie for the user of the Portal token as soon as in possession of a user’s Portal token. With this additional request security.manager identifies the Portal user. Subsequent requests use the domain cookie to identify the user.

Although this approach requires special client logic (the additional request), it is the only method to enable the client to make use of applications that are protected by means of security.manager domain cookie mechanism. This method is currently not supported by standard Esri APIs.

In both cases security.manager needs to be linked to a Portal instance (or ArcGIS Online organization). When security.manager receives a client request (either token-based or containing a domain cookie) it looks up the user details from Portal based on the information provided by the requesting client. The Portal user identity is then matched to a security.manager user account by username. It is common that security.manager and ArcGIS for Portal use the same LDAP or Active Directory as a user repository, so that user accounts are based on the same data source. You can also run security.manager with its native database user repository. Take care that all users managed by the Portal have a corresponding user account in security.manager with the same username.

Common Setup

1 Enable Portal integration

To activate the Portal integration, you need to specify the Portal URL in the application.properties configuration file, using the parameter security.login.portal.url. For a detailed description of relevant configuration parameters, see Portal integration.

2 Link user accounts

Single Sign-on with Portal for ArcGIS and ArcGIS Online is based on usernames. For every user managed by the Portal there must be a corresponding user with the same username in security.manager before single sign-on works. The most consistent way to link the accounts is to make security.manager and Portal use the same LDAP or Active Directory. Otherwise you need to manually create a user account in security.manager for every users that exist in the Portal.

With Portal integration enabled, roles and policies controlling service access is still managed in security.manager. Imagine a Portal user with username a.miller. To enable single sign-on there must also be user a.miller in security.manager. To grant access to a protected service, create a role in security.manager, assign that role to a.miller, and create policies that grant access to certain service resources.

ArcGIS Server Federation

This approach does not work with ArcGIS Online as service federation is not supported in ArcGIS Online.

To federate a protected ArcGIS Server instance you need to . Register the "agstoken" endpoint URL with Portal. . Copy the generated Server Key over to security.manager.

1 Register Service at Portal

  1. In a browser open https://[myportal.host.com]/[WebAdaptorName]/sharing/rest

  2. Login with Portal administrative account

  3. In the same browser navigate to https://[myportal.host.com]/[WebAdaptorName]/sharing/rest/portals/0123456789ABCDEF/servers/register

  4. Enter the requested values:

    register service1

    Name: A descriptive name for the service you are federating
    URL: The base "agstoken" URL of the protected service, e. g. http://[mysecman.host.com]/wss/service/ags-relay/serviceA/agstoken/arcgis
    Is hosted: false
    Server Type: ArcGIS
    Server Admin URL: The same URL as for the field URL, e. g. http://[mysecman.host.com]/wss/service/ags-relay/serviceA/agstoken/arcgis

  5. Click Register

  6. Copy the Server Secret Key

    register service2
    The Secret Server Key is only displayed once. You are not able to retrieve this key later on. If you need the key again, you have to register the service endpoint again.

2 Copy the Server Key to security.manager

  1. In a browser open https://[mysecman.host.com]/administration

  2. Sign in with an administrative account.

  3. Navigate to Protected Services.

  4. Edit the service you registered.

  5. Assert that agstoken authentication is enabled and enter the Server Key:

    agstoken server key

  6. Click Save

3 Access the protected service

After the federation is set up as well as roles and policies are defined in security.manager, use the "agstoken" endpoint to access the protected service as any other federated ArGIS Server.

Examples of protected, federated service usage:

To load a federated service as a GIS Server resource in ArcGIS Desktop use this URL:
http://[mysecman.host.com]/wss/service/ags-relay/serviceB/agstoken/arcgis/services

To register a MapServer as an item in Portal for ArcGIS, use the URL of a protected MapServer like this:
http://[mysecman.host.com]/wss/service/ags-relay/serviceB/agstoken/arcgis/rest/services/USA/MapServer

4 Limitations

Navigating the Service Directory

Currently it is not possible to navigate the HTML view of the service directory of a protected service using the "agstoken" endpoint, for example by calling http://[mysecman.host.com]/wss/service/ags-relay/serviceB/agstoken/arcgis/services in a browser.

Display of Federation State

If you sign in to the Portal as an administrative user, the state of federation is displayed for every federated service under Organization > Settings > Servers > Federated Servers. The services you federated with security.manager are displayed in the list of servers, but the icon indicating the federation state represents unknown state or error state. You can ignore this state info for services federated with security.manager. Currently, security.manager is not able to report the actual state back to Portal.

security.manager Domain Cookie

To request a domain cookie, a client is required to send a user’s Portal token to the /token/cookie endpoint of security.manager:

Example of a portal token conversion request
https://[HOST][:PORT]/administration/token/cookie?portaltoken=02YuGX3aoYxRPzcylglzIEPwcRA-2pKCErNdKXHoAzVp-B826fNrCUTTfTi9uqc...

security.manager returns a response setting the domain cookie:

Example of a token conversion response
HTTP/1.1 200 OK
Server Apache-Coyote/1.1 is not blacklisted
Server: Apache-Coyote/1.1
Set-Cookie: ct_SSO=*|040ee5fb86c3772c46d77413c8f65474|586eeb64716ec700bab9c83ad8e4dce1141ee45f; Version=1; Comment=""; Path=/
Content-Length: 0
Date: Mon, 01 Jan 2017 00:00:01 GMT
If an error occurs, for example the Portal token is invalid or timed out, you get an HTTP response with 403 status code.