Authorize

Description

The Authentication topic describes the overall OAuth2 authentication flow. This topic describes the user authorization step of that flow.

Apps that support user logins use OAuth2 to allow users to log in to the ArcGIS platform via the app.

User logins using the OAuth2-based ArcGIS APIs are based on the application guiding the user to log in to the platform via a login page hosted on the ArcGIS platform. The /oauth2/authorize endpoint represents that login page. The login page renders an HTML form for the user to enter their credentials.

The user authentication workflow starts with the authorization step. Apps need to direct the browser to this URL. client_id, response_type, and redirect_uri are required parameters. There are other optional parameters as well, and they;'re described below.

The response_type parameter determines the type of grant—implicit or authorization. A response_type of token implies implicit grant and code implies authorization code grant.

Implicit grants are typically used by JavaScript applications, and they complete the flow in a single step. The end result of successful authentication is an access_token that's delivered to the specified redirect_uri in the URL fragment. See the Response section for details.

Authorization grants are used by mobile, desktop, and server-side applications, and they complete the flow in two steps. Authorization represents the first step of that flow. Successful authorization yields an authorization code that's delivered to the specified redirect_uri as a query parameter. See the Response section for details. The second step of the flow requires exchanging the authorization code obtained in the first step for an access_token. This is accomplished by accessing the token endpoint with a grant_type of authorization_code.

Request Parameters

Parameter

Details

client_id

(Required)

The ID of the registered application. Also referred to as APPID.

Example: client_id=GGjeDjEY6kKEiDmX

response_type

(Required)

The type of grant—implicit or authorization.

Values: token, code

token implies implicit grant and code implies authorization code grant.

Example: response_type=token

redirect_uri

(Required)

The URI where the access_token or authorization code will be delivered upon successful authorization. The URI must match one of the URIs specified during app registration, otherwise authorization will be rejected. If registered, a special value of urn:ietf:wg:oauth:2.0:oob can also be specified for authorization grants. This will result in the authorization code being delivered to a portal URL (/oauth2/approval). This value is typically used by applications that don't have a web server or a custom URI scheme where the code can be delivered.

Example: redirect_uri=http://app.example.com/cb

client_secret

The secret of the registered application. Also referred to as APPSECRET.

Example: client_secret=57e2f75cd56346bf9d5654c3338a1250

state

An opaque value used by applications to maintain state between authorization requests and responses. The state, if specified, will be delivered back to the redirect_uri as is. Applications can use this parameter to correlate the authorization request sent with the received response.

Example: state=qyxmpg9e5uWUPbxw

expiration

The requested validity in minutes of access_token for implicit grants or refresh_token for authorization grants.

For implicit grants, the default validity of access_tokens is 2 hours. The expiration parameter, if specified, overrides the validity period up to a max of 2 weeks (i.e., 20160 minutes).

For authorization grants, the default validity of access_tokens is 30 minutes and refresh_tokens is 2 weeks. The expiration parameter, if specified, overrides the validity period of refresh_tokens up to a max of 90 days.

Example: expiration=20160 (2 weeks)

NoteNote:

Org admins can specify the max validity period of tokens for their org that supercedes the expiration parameter. access_token can become invalid before it expires, i.e. if user changes password. When it expires or is invalid, an error response like below will be returned:

{
    "error": {
        "code": 498,
        "message": "Invalid Token",
        "details": []
    }
}

display

The template used to render the login page.

Based on the client platform, applications can choose one of the supported templates to render the login page. If not specified, the default template is used.

Values: default, iframe, win8

locale

The locale assumed to render the login page.

Applications can pass the user's locale using this parameter. The login page will be rendered using the language corresponding to that locale. If not specified, the locale will be determined based on the org's setting or on the incoming request.

Example: locale=fr

persist

If true, implies that the user had checked "Keep me signed in" when signing into ArcGIS Online.

ssl

If true, implies that the user belongs to an ssl-only organization

Response

Implicit Grant

The access_token will be delivered to the specified redirect_uri in the URL fragment.

http://app.example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA&expires_in=3600&state=qyxmpg9e5uWUPbxw

expires_in represents the token expiration in seconds from now.

Explicit Grant

The authorization code will be delivered to the specified redirect_uri as a query parameter.

http://app.example.com/cb?code=KIV31WkDhY6XIWXmWAc6U&state=qyxmpg9e5uWUPbxw

If the special value of urn:ietf:wg:oauth:2.0:oob is specified as the redirect_uri, the authorization code will be delivered to a portal URL (/oauth2/approval). This URL will render an HTML page, and the code can be extracted from the <title> element of the page.

https://www.arcgis.com/sharing/oauth2/approval

The <title> element of the rendered HTML page will include the code as:

<title>SUCCESS code=KIV31WkDhY6XIWXmWAc6U</title>

Example Usage

For all examples, assume this endpoint:

https://www.arcgis.com/sharing/oauth2/authorize

Implicit Grant

Assume these parameters:

client_id=GGjeDjEY6kKEiDmX&
response_type=token&
redirect_uri=http://app.example.com/cb

Explicit Grant

Assume these parameters:

client_id=GGjeDjEY6kKEiDmX&
response_type=code&
redirect_uri=http://app.example.com/cb
10/6/2017