- URL:
- https://[root]/oauth2/authorize
- Methods:
GET
Example usage
https://www.arcgis.com/sharing/rest/oauth2/authorize
Description
Apps that support user logins use OAuth2 to allow users to sign in to the ArcGIS organization through the app. The authorize
operation represents the login page for users to sign in to their ArcGIS organization. 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 the authorize
endpoint. For the authentication workflow, the client
, response
, and redirect
parameters are required.
Additional, optional parameters include the response
parameter, which determines whether an implicit or authorization grant is used. Setting the response
as token
implies an implicit grant, and setting the response
as code
implies an authorization code grant.
Implicit grants complete the authorization workflow in a single step. The result of successful authentication is an access
value that's delivered to the specified redirect
value in the URL fragment. For more information, see the Response section below.
Until recently, implicit grants were used by ArcGIS Online organization home page logins. With the March 2022 release of ArcGIS Online, the organization home page logins were updated to use Proof Key for Code Exchange (PKCE). PKCE is an extension to authorization grant flow and is recommended for all the applications including web applications, rather than implicit grants.
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 produces an authorization code
value that's delivered to the specified redirect
value as a query parameter. See the Sample responses section below for details. The second step of the flow requires exchanging the authorization code obtained in the first step for an access
value. This is accomplished by accessing the token end point with a grant
of authorization
. It is recommended that you use an authorization grant with PKCE for all applications.
Request parameters
Parameter | Details |
---|---|
(Required) | The ID of the registered application. This is also referred to as APPID. Example:
|
(Required) | The URI where the Example:
|
(Required) | The type of grant, either implicit ( Values: Example:
|
| The secret of the registered application. This is also referred to as APPSECRET. Example:
|
| The Base64-URL-encoded SHA256 hash of the client-generated code verifier. The code verifier is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long. Clients that cannot perform a SHA256 hash can use the Example:
|
| Indicates whether the If the value is set to Values: |
| Specifies the template used to render the login page. Based on the client platform, you can choose one of the supported templates for the app to render the login page. If not specified, the Values: |
| The requested validity, specified in minutes, of the For authorization grants, the default validity of the Example of two weeks:
|
| The locale assumed to render the login page. The user's locale can be passed using this parameter. The login page will be rendered using the language corresponding to that locale. If not specified, the locale is based on the organization's setting or on the incoming request. Example:
|
| An opaque value used by applications to maintain state between authorization requests and responses. The Example:
|
| Specifies, the color scheme used to render the login page regardless of browser or operating system settings. If not specified, the style will follow the browser or OS color scheme if designated. The Values: |
Sample responses
Implicit grant
The access
value will be delivered to the specified redirect
value in the URL fragment.
Example:
https
expires
represents the token expiration in seconds from now.
Explicit grant
The authorization code
value will be delivered to the specified redirect
value as a query parameter.
Example:
https
If the special value of urn
is specified for the redirect
parameter, 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.
Example:
https://www.arcgis.com/sharing/rest/oauth2/approval
The <title
element of the rendered HTML page will include the following code:
<title>SUCCESS code=KIV31WkDhY6XIWXmWAc6U</title>
Examples
For all examples, assume this endpoint:
https://www.arcgis.com/sharing/rest/oauth2/authorize
Implicit grant
Assume these parameters:
client_id=GGjeDjEY6kKEiDmX&
response_type=token&
redirect_uri=https://app.example.com/cb
Explicit grant
Assume these parameters:
client_id=GGjeDjEY6kKEiDmX&
response_type=code&
redirect_uri=https://app.example.com/cb
PKCE flow
Assume these parameters:
client_id=GGjeDjEY6kKEiDmX&
response_type=code&
redirect_uri=https://app.example.com/cb
code_challenge=asdfasf23423asdfasf234234asdf224asdfasdasdfg456dgffgh
code_challenge_method=S256