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.
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.
The ID of the registered application. Also referred to as APPID.
The type of grant—implicit or authorization.
Values: token, code
token implies implicit grant and code implies authorization code grant.
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.
The secret of the registered application. Also referred to as APPSECRET.
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.
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)
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:
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
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.
If true, implies that the user had checked "Keep me signed in" when signing into ArcGIS Online.
If true, implies that the user belongs to an ssl-only organization
The access_token will be delivered to the specified redirect_uri in the URL fragment.
expires_in represents the token expiration in seconds from now.
The authorization code will be delivered to the specified redirect_uri as a query parameter.
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.
The <title> element of the rendered HTML page will include the code as:
For all examples, assume this endpoint:
Assume these parameters:
client_id=GGjeDjEY6kKEiDmX& response_type=token& redirect_uri=http://app.example.com/cb
Assume these parameters:
client_id=GGjeDjEY6kKEiDmX& response_type=code& redirect_uri=http://app.example.com/cb