Hide Table of Contents
esri
esri/arcgis
esri/dijit
esri/dijit/analysis
esri/dijit/geoenrichment
esri/dijit/geoenrichment/ReportPlayer
esri/geometry
esri/layers
esri/opsdashboard
esri/renderers
esri/symbols
esri/tasks
esri/tasks/datareviewer
esri/tasks/geoenrichment
esri/tasks/locationproviders
Class: IdentityManagerBase
[ AMD Module Require | Legacy Module Require ]
require(["esri/IdentityManagerBase"], function(IdentityManagerBase) { /* code goes here */ });
Description
(Added at v2.5)
This class provides the framework and helper methods required to implement a solution for managing user credentials.
The supported resources are:
- ArcGIS Server resources secured using token-based authentication. Note that only ArcGIS Server versions 10 SP 1 and greater are supported.
- Secured ArcGIS.com resources (i.e., web maps).
esri/IdentityManager class provides a complete out-of-the-box implementation.Samples
Search for samples that use this class.Subclasses
Properties
| Name | Type | Summary |
|---|---|---|
| tokenValidity | Number | The suggested lifetime of the token in minutes. |
| useSignInPage | Boolean | If your application is on the same domain as *.arcgis.com or ArcGIS Enterprise Server, the IdentityManager will redirect the user to its sign-in page. |
Methods
| Name | Return type | Summary |
|---|---|---|
| checkSignInStatus(resUrl) | Deferred | Returns the credential (via Deferred) if the user has already signed in to access the given resource. |
| destroyCredentials() | None | Destroys all credentials. |
| findCredential(url, userId?) | Credential | Returns the credential for the resource identified by the specified url. |
| findOAuthInfo(url) | OAuthInfo | Returns the OAuth configuration for the passed in Portal server URL. |
| findServerInfo(url) | ServerInfo | Returns information about the server that is hosting the specified url. |
| generateToken(serverInfo, userInfo, options?) | Deferred | Returns an object containing a token and its expiration time. |
| getCredential(url, options?) | Deferred | Returns a Credential object that can be used to access the secured resource identified by the input url. |
| initialize(json) | None | Call this method (during your application initialization) with JSON previously obtained from toJson method to re-hydrate the state of identity manager. |
| isBusy() | Boolean | Returns true if the identity manager is busy accepting user input, i.e., the user has invoked signIn and is waiting for a response. |
| oAuthSignIn(resUrl, serverInfo, OAuthInfo, options?) | Deferred | Sub-classes must implement this method if OAuth support is required. |
| registerOAuthInfos(oAuthInfos) | None | Registers OAuth configurations. |
| registerServers(serverInfos) | None | Register secure servers and the token endpoints. |
| registerToken(properties) | None | Registers the given OAuth2 access token with the identity manager. |
| setProtocolErrorHandler(handlerFunction) | None | When accessing secured resources, identity manager may prompt for username and password and send them to the server using a secure connection. |
| setRedirectionHandler(handlerFunction) | None | If your application is on the same domain as *.arcgis.com or ArcGIS Enterprise Server, the IdentityManager will redirect the user to its sign-in page. |
| signIn(url, serverInfo, options?) | Deferred | Sub-classes must implement this method to create and manager the user interface that is used to obtain a username and password from the end-user. |
| toJson() | Object | Return properties of this object in JSON. |
Events
[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.
Events
| Name | Event Object | Summary |
|---|---|---|
| credential-create | {
credential: < | Fired when a credential is created. |
| credentials-destroy | Fired when all credentials are destroyed. |
Property Details
<Number
NumberThe suggested lifetime of the token in minutes. Default is 60 minutes.
<Boolean
BooleanIf your application is on the same domain as
*.arcgis.com or ArcGIS Enterprise Server, the IdentityManager will redirect the user to its sign-in page. For instance, let's say an application accesses secure resources from ArcGIS.com or one of its subdomains. Once the application attempts to access this resource, the IdentityManager redirects the user to the ArcGIS.com sign-in page. Once a user successfully logs in, they are redirected back to the application. The same holds true if the application accesses secure resources from ArcGIS Enterprise as the IdentityManager will redirect the user to its sign-in page. If you do not wish for the application to automatically redirect, set this property to false. (Please note that this is not a common scenario. For most, using the OAuth sign-in behavior should handle most of their authentication needs.)Default value:
trueMethod Details
Returns the credential (via Deferred) if the user has already signed in to access the given resource. If the user has not signed in, then the deferred will be rejected and its error callback will be called. (Added at v3.10)
Return type:
DeferredParameters:
< |
Required | The resource URL. |
Returns the credential for the resource identified by the specified url. Optionally you can provide a
userId to find credentials for a specific user.Return type:
CredentialReturns the OAuth configuration for the passed in Portal server URL. (Added at v3.10)
Return type:
OAuthInfoParameters:
< |
Required | The ArcGIS for Portal URL, for example "https://www.arcgis.com" for ArcGIS Online and "https://www.example.com/portal" for your in-house portal. |
Sample:
require([
"esri/arcgis/OAuthInfo", "esri/IdentityManager", ...
], function(OAuthInfo, esriId, ... ) {
var portalURL = "https://host.arcgis.com";
...
findOAuthInfo = function (){
var oAuthInfo = esriId.findOAuthInfo(portalURL)
console.log(oAuthInfo.toJson())
}
...
});Returns information about the server that is hosting the specified url.
Return type:
ServerInfoParameters:
< |
Required | The url to a server. |
Returns an object containing a token and its expiration time. You need to provide the ServerInfo object that contains token service URL and a user info object containing username and password. This is a helper method typically called by sub-classes to generate tokens.
Return type:
DeferredParameters:
< |
Required | A ServerInfo object that contains a token service URL. |
< |
Required | A user info object containing a user name and password. |
< |
Optional | Optional parameters. (As of 3.0). See the Object Specifications table below for the structure of the options object. |
Object Specifications:
<
options>< |
Required | Indicates that the token should be generated using the token service deployed with the ArcGIS Server Admin API. The default value is false. |
Returns a
Credential object that can be used to access the secured resource identified by the input url. If required the user will be challenged for a username and password which is used to generate a token. Note: The IdentityManager sets up a timer to update the Credential object with a new token prior to the expiration time. This method is typically called by esri.request when a request fails due to an "invalid credentials" error.Return type:
DeferredParameters:
< |
Required | The url for the secure resource. |
< |
Optional | Optional parameters. (As of 3.0). See the Object Specifications table below for the structure of the options object. |
Object Specifications:
<
options>< |
Required | Error object returned by the server from a previous attempt to fetch the given url. |
< |
Required | If set to "false", the user will not be shown a dialog before the OAuth popup window is opened. The default is "true" since otherwise the browser is likely to block the popup from opening. Added at version 3.10 |
< |
Required | Determines if the method should make additional attempts to get the credentials after a failure. |
< |
Required | Token used for a previous unsuccessful attempt to fetch the given url. |
Call this method (during your application initialization) with JSON previously obtained from
toJson method to re-hydrate the state of identity manager. (Added at v2.8)Parameters:
< |
Required | The JSON obtained from the toJson method. |
Returns true if the identity manager is busy accepting user input, i.e., the user has invoked
signIn and is waiting for a response.Return type:
BooleanSub-classes must implement this method if OAuth support is required. (Added at v3.10)
Return type:
DeferredParameters:
< |
Required | The resource URL. |
< |
Required | A ServerInfo object that contains the token service url. |
< |
Required | A OAuthInfo object that contains the authorization configuration. |
< |
Optional | Optional parameters. See the Object Specifications table below for the structure of the options object. |
Object Specifications:
<
options>< |
Required | Error object returned by the server from a previous attempt to fetch the given url. |
< |
Required | If set to "false", the user will not be shown a dialog before the OAuth popup window is opened. The default is "true" since otherwise the browser is likely to block the popup from opening. |
< |
Required | Token used for previous unsuccessful attempts to fetch the given url. |
Registers OAuth configurations. (Added at v3.10)
Parameters:
< |
Required | An OAuthInfos object that defines the OAuth configurations. |
Sample:
require([
"esri/arcgis/OAuthInfo", "esri/IdentityManager", ...
], function(OAuthInfo, esriId, ... ) {
var oAuthInfo = new OAuthInfo({
appId: "", //required parameter
... //specify optional parameters if needed
esriId.registerOAuthInfos([oAuthInfo]);
});
Register secure servers and the token endpoints.
Parameters:
< |
Required | A ServerInfos object that defines the secure service and token endpoint. The Identity Manager makes its best guess to determine the location of the secure server and token endpoint so in most cases calling registerServers is not necessary. However, use this method to register the location if the location of your server or token endpoint is non-standard. |
Sample:
require([
"esri/ServerInfo", "esri/IdentityManager", ...
], function(ServerInfo, esriId, ... ) {
var serverInfo = new ServerInfo();
serverInfo.server = 'http://sampleserver3.arcgisonline.com';
serverInfo.tokenServiceUrl = 'http://sampleserver3.arcgisonline.com/arcgis/tokens/generateToken';
esriId.registerServers([serverInfo]);
});
Registers the given OAuth2 access token with the identity manager.
An access token can be obtained after the user logs in to ArcGIS Online through your application. This process is described in the Browser-based User Logins help topic and demonstrated in this sample application.
Once registered with the identity manager, the access token will be passed along with all AJAX requests made by the application (on behalf of the logged in user) to access WebMaps and other items stored in ArcGIS Online.
(Added at v3.4)
An access token can be obtained after the user logs in to ArcGIS Online through your application. This process is described in the Browser-based User Logins help topic and demonstrated in this sample application.
Once registered with the identity manager, the access token will be passed along with all AJAX requests made by the application (on behalf of the logged in user) to access WebMaps and other items stored in ArcGIS Online.
Parameters:
< |
Required | See the object specifications table below for the structure of the properties object. |
Object Specifications:
<
properties>< |
Required | Token expiration time specified as number of milliseconds since 1 January 1970 00:00:00 UTC. |
< |
Required | For ArcGIS Online or Portal, this is https://www.arcgis.com/sharing/rest or similar to https://www.example.com/portal/sharing/rest. |
< |
Required | Set this to true if the user has an ArcGIS Online Organizational Account and the organization is configured to allow access to resources only through SSL. |
< |
Required | The access token. |
< |
Required | The id for the user who owns the access token. |
When accessing secured resources, identity manager may prompt for username and password and send them to the server using a secure connection. Due to browser limitations under certain conditions, it may not be possible to establish a secure connection with the server if the application is being run over HTTP protocol (you can identify the protocol by looking at the URL bar in any browser). In such cases, the Identity Manager will abort the request to fetch the secured resource.
To resolve this issue, configure your web application server with HTTPS support and run the application over HTTPS. This is the recommended solution for production environments. However, for internal development environment that don't have HTTPS support, you can define a protocol error handler that allows the Identity Manager to continue with the process over HTTP protocol (insecure connection).
Note that identity manager will call your handler function with an object containing the following properties:
| <String> resourceUrl | The secure resource URL. |
| <ServerInfo> serverInfo | Object describing the server where the secure resource is hosted. |
Parameters:
< |
Required | The function to call when the protocol is mismatched. |
Sample:
require([
"esri/IdentityManager", ...
], function(esriId, ... ) {
//Note: This should not be used in a production enviroment
esriId.setProtocolErrorHandler(function(){
console.log("Protocol mismatch error");
return window.confirm("Protocol mismatch error .... proceed anyway?");
});
});
If your application is on the same domain as *.arcgis.com or ArcGIS Enterprise Server, the IdentityManager will redirect the user to its sign-in page. For instance, let's say an application accesses secure resources from ArcGIS.com or one of its subdomains. Once the application attempts to access this resource, the IdentityManager redirects the user to the ArcGIS.com sign-in page. Once a user successfully logs in, they are redirected back to the application. The same holds true if the application accesses secure resources from ArcGIS Enterprise as the IdentityManager will redirect the user to its sign-in page. Use this method if the application needs to execute custom logic before the page is redirected by creating a custom redirection handler. The IdentityManager calls the custom handler function with an object containing the redirection properties.
Note that identity manager will call your handler function with an object containing the following properties:
| <String> resourceUrl | The URL of the secure resource that triggers the redirection to the ArcGIS.com sign-in page. |
| <String> returnUrlParamName |
The application URL where the sign-in page redirects after a successful log-in. To create the return URL append the application's URL to signInPage as a parameter. The returnUrlParamName contains the name of the parameter. |
| <ServerInfo> serverInfo | ServerInfo object describing the server where the secure resource is hosted. |
| <String> signInPage | URL of the sign-in page where users will be redirected. |
Parameters:
< |
Required | When called, the function passed to setRedirectionHandler receives an object containing redirection properties. |
Sample:
require([
"esri/IdentityManager", ...
], function(esriId, ... ) {
esriId.setRedirectionHandler(function(info) {
// Execute custom logic then perform redirect
window.location = info.signInPage "?"
info.returnUrlParamName "=" window.location.href;
});
});
Sub-classes must implement this method to create and manager the user interface that is used to obtain a username and password from the end-user. It should perform the following tasks:
- Challenge the user for a username and password.
- Generate a token and return it to the caller via Deferred object.
Return type:
DeferredParameters:
< |
Required | Url for the secure resource. |
< |
Required | A ServerInfo object that contains the token service url. |
< |
Optional | Optional parameters. (As of 3.0). See the Object Specifications table below for the structure of the options object. |
Object Specifications:
<
options>< |
Required | Error object returned by the server from a previous attempt to fetch the given url. |
< |
Required | Indicate that the token should be generated using the token service deployed with the ArcGIS Server Admin API. The default value is false. |
< |
Required | Token used for previous unsuccessful attempts to fetch the given url. |
Return properties of this object in JSON. It can be stored in a Cookie or persisted in HTML5 LocalStorage and later used to:
- Initialize the IdentityManager the next time user opens your application.
- Share the state of identity manager between multiple web pages of your website.
This way your users won't be asked to sign in repeatedly when they launch your app multiple times or when navigating between multiple web pages in your website.
(Added at v2.8)Return type:
ObjectEvent Details
[ On Style Events | Connect Style Event ]
Fired when a credential is created. (Added at v3.10)
Event Object Properties:
< |
The returned credential. |
Sample:
require([IdentityManager], function(esriId) {
esriId.on("credential-create", function(e) {
console.log ('Credential: ', e.credential);
});
});