About
The authorization endpoint is one of two endpoints of the authorization server.
It's used by the client (app) to obtain authorization from the resource owner in the form of a authorization grant via user-agent redirection.
The authorization endpoint is used in:
by requiring a grant type with the help of the response type query parameter
Example
Example of Authorization Request
Example of authorization_request
GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcallback HTTP/1.1
Host: server.example.com
where:
- response_type is the type of authorization grant requested (in this case, a code)
- client_id is the client identifier
- redirect_uri is where the response will be send via redirection
Example of Authorization Response
Example of an authorization_response
HTTP/1.1 302 Found
Location: https://client.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz
where:
- https://client.example.com/callback is the redirection URI value
- code=SplxlOBeZQQYbYS6WxSbIA is the authorization grant in a code format
- state=xyz is your state. It should be an opaque / encoded value to prevent cross site surgery and it contains generally the session (ie where the user was to continue back the navigation)
Authorization Request
Prerequisites
The authorization endpoint:
- MUST support the use of the HTTP “GET” for the authorization endpoint
- MAY support the use of the “POST” method as well.
- MUST require the use of TLS when sending requests to the authorization endpoint (since requests to the authorization endpoint result in user authentication and the transmission of clear-text credentials in the HTTP response)
URI
- URI:
- The location of the authorization endpoint is typically provided in the service documentation.
- The endpoint URI MAY include an application/x-www-form-urlencoded formatted query component, which MUST be retained when adding additional query parameters.
- The endpoint URI MUST NOT include a fragment component.
Response Type
The client informs the authorization server of the desired grant type using the following parameter:
response_type REQUIRED.
The value MUST be one of:
- code for requesting an authorization code
- token for requesting an access token (used only in a implicit grant flow)
Extension response types MAY contain a space-delimited (%x20) list of values, where the order of values does not matter (e.g., response type “a b” is the same as “b a”). The meaning of such composite response types is defined by their respective specifications.
If an authorization request is missing the “response_type” parameter, or if the response type is not understood, the authorization server MUST return an error response as described in Section 4.1.2.1.
redirect_uri
With the authorization request, you can defined an optional redirection endpoint using the redirect_uri request parameter.
This is also known as the callback endpoint.
The authorization server upon successful authentication will respond with a redirection to this URI.
Example
HTTP/1.1 302 Found
Location: https://client.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz
where:
- https://client.example.com/callback is the redirection URI value
- code=SplxlOBeZQQYbYS6WxSbIA is the authorization grant in a code format
- state=xyz is the state of your session (generally where the user was to return it back to the page requested)
The authorization server MUST compare and match the value received against at least one of the registered redirection URIs if any redirection URIs were registered.
Scope request
The scope parameter defines the scope request.
Client Id
The client id is required.
State
The state is an opaque value used by the client to maintain state between the request and callback (response).
The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery 1).
Authorization Validation
The authorization server validates the request to ensure that all required parameters are present and valid.
If an authorization request fails validation due to a missing, invalid, or mismatching redirection URI, the authorization server send an error_response
Response
If the request is:
- valid, the authorization server:
- authenticates the resource owner
- obtains an authorization decision (by asking the resource owner or by establishing approval via other means)
- and send an authorization_response
- not valid, the authorization server send an error_response
Error response
If an authorization request fails validation due to a missing, invalid, or mismatching redirection URI, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
More, see Error Response
Authorization Response
When a decision is established, the authorization server directs the user-agent to the provided client redirection URI using an HTTP redirection response, or by other means available to it via the user-agent.
Content
The redirection request to the client's endpoint typically results in an HTML document response, processed by the user-agent.
If the HTML response is served directly as the result of the redirection request, any script included in the HTML document will execute with full access to the redirection URI and the credentials it contains.
The client SHOULD NOT include any third-party scripts (e.g., third- party analytics, social plug-ins, ad networks) in the redirection endpoint response.
Instead, it SHOULD extract the credentials from the URI and redirect the user-agent again to another endpoint without exposing the credentials (in the URI or elsewhere).
If third-party scripts are included, the client MUST ensure that its own scripts (used to extract and remove the credentials from the URI) will execute first.
Scope Response
The scope parameter defines the scope response.
Response Validation
The client MUST ignore unrecognized response parameters.
- The authorization code string size is left undefined by this specification.
- The client should avoid making assumptions about code value sizes.
- The authorization server SHOULD document the size of any value it issues.