This section describes how to obtain an access token using the Authorization Code Flow.
6.2 Authorization Endpoint
6.2.1 Authorization Request
The client builds the authorization request URL by starting with the discovered authorization_endpoint URL and adding the following parameters to the query component:
response_type=code - Indicates to the authorization server that this is an authorization request and an authorization code should be returnedme - The profile URL that the user enteredclient_id - The client URLredirect_uri - The redirect URL indicating where the user should be redirected to after approving the requeststate - A parameter set by the client which will be included when the user is redirected back to the client. This is used to prevent CSRF attacks. The authorization server MUST return the unmodified state value back to the client.scope - (optional) A space-separated list of scopes the client is requesting, e.g. "create". If the client omits this value, the authorization server MUST use a default value.
https://example.org/auth?me=https://user.example.net/&
redirect_uri=https://app.example.com/redirect&
client_id=https://app.example.com/&
state=1234567890&
scope=create+update+delete&
response_type=code
The authorization endpoint SHOULD fetch the client_id URL to retrieve application information and the client's registered redirect URLs, see Client Information Discovery for more information.
If the URL scheme, host or port of the redirect_uri in the request do not match that of the client_id, then the authorization endpoint SHOULD verify that the requested redirect_uri matches one of the redirect URLs published by the client, and SHOULD block the request from proceeding if not.
It is up to the authorization endpoint how to authenticate the user. This step is out of scope of OAuth 2.0, and is highly dependent on the particular implementation. Some authorization servers use typical username/password authentication, and others use alternative forms of authentication such as [RelMeAuth].
Once the user is authenticated, the authorization endpoint presents the authorization prompt to the user. The prompt MUST indicate which application the user is signing in to, and SHOULD provide as much detail as possible about the request, such as information about the requested scopes.
6.2.2 Authorization Response
If the user approves the request, the authorization endpoint generates an authorization code and builds the redirect back to the client.
The redirect is built by starting with the redirect_uri in the request, and adding the following parameters to the query component of the redirect URL:
code - The authorization code generated by the authorization endpoint. The code MUST expire shortly after it is issued to mitigate the risk of leaks. A maximum lifetime of 10 minutes is recommended. See OAuth 2.0 Section 4.1.2 for additional requirements on the authorization code.state - The state parameter MUST be set to the exact value that the client set in the request.
HTTP/1.1 302 Found
Location: https://app.example.com/redirect?code=xxxxxxxx
state=1234567890
Upon the redirect back to the client, the client MUST verify that the state parameter in the request is valid and matches the state parameter that it initially created, in order to prevent CSRF attacks. The state value can also store session information to enable development of clients that cannot store data themselves.
See OAuth 2.0 [RFC6749] Section 4.1.2.1 for how to indicate errors and other failures to the user and client.
6.3 Token Endpoint
6.3.1 Token Request
After the state parameter is validated, the client makes a POST request to the token endpoint to verify the authorization code and retrieve the final user profile URL. The POST request contains the following parameters:
grant_type=authorization_codecode - The authorization code received from the authorization endpoint in the redirectclient_id - The client's URL, which MUST match the client_id used in the authorization request.redirect_uri - The client's redirect URL, which MUST match the initial authorization request.me - The user's profile URL as originally used in the authorization request
POST https://example.org/token
Content-type: application/x-www-form-urlencoded
Accept: application/json
grant_type=authorization_code
&code=xxxxxxxx
&client_id=https://app.example.com/
&redirect_uri=https://app.example.com/redirect
&me=https://user.example.net/
6.3.2 Authorization Code Verification
The token endpoint needs to verify that the authorization code is valid, and that it was issued for the matching me, client_id and redirect_uri, and contains at least one scope. If the authorization code was issued with no scope, the token endpoint MUST NOT issue an access token, as empty scopes are invalid per Section 3.3 of OAuth 2.0 [RFC6749].
If the authorization endpoint and token endpoint are tightly integrated, then they can use any mechanism to share the information about the authorization code, such as looking up the code in a database, or sharing a JWT secret. If the authorization endpoint and token endpoint are separate, then they MUST use the mechanism described below to communicate.
The token endpoint MUST make a POST request to the authorization endpoint to verify the authorization code if it is not able to verify it using other means. To find the authorization endpoint, the token endpoint uses the user's profile URL in the me parameter and performs discovery to find the user's authorization_endpoint. The token endpoint makes a POST request to the authorization endpoint with the following parameters:
code - The authorization code received from the authorization endpoint in the redirectclient_id - The client's URL, which MUST match the client_id used in the authorization request.redirect_uri - The client's redirect URL, which MUST match the initial authorization request.
POST https://example.org/auth
Content-type: application/x-www-form-urlencoded
Accept: application/json
code=xxxxxxxx
&client_id=https://app.example.com/
&redirect_uri=https://app.example.com/redirect
Note that this is the same request that clients make to the authorization endpoint in the authentication flow.
The authorization endpoint will validate that the code corresponds with the given client_id and redirect_uri and respond with a JSON response containing the me URL corresponding to this authorization code as well as the scope that was authorized, or an OAuth 2.0 error response. The error returned from the authorization endpoint is acceptable to pass through to the client.
HTTP/1.1 200 OK
Content-Type: application/json
{
"me": "https://user.example.net/",
"scope": "create update delete"
}
6.3.3 Access Token Response
If the request is valid, then the token endpoint can generate an access token and return the appropriate response. The token response is a JSON [RFC7159] object containing the OAuth 2.0 Bearer Token [RFC6750], as well as a property me, containing the canonical user profile URL for the user this access token corresponds to. For example:
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "XXXXXX",
"token_type": "Bearer",
"scope": "create update delete",
"me": "https://user.example.net/"
}
The resulting profile URL MAY be different from what the user initially entered, but MUST be on the same domain. This provides the opportunity to canonicalize the user's URL, such as correcting http to https, or adding a path if required. See Redirect Examples for an example of how a service can allow a user to enter a URL on a domain different from their resulting me profile URL.
See OAuth 2.0 [RFC6749] Section 5.2 for how to respond in the case of errors or other failures.
6.3.4 Access Token Verification
Since in OAuth 2.0, access tokens are opaque to clients, clients do not need to know anything about the contents or structure of the token itself, if any. Additionally, endpoints that clients make requests to, such as [Micropub] endpoints, may not even understand how to interpret tokens if they were issued by a standalone token endpoint. If the token endpoint is not tightly integrated with the endpoint the client is interacting with, then the other endpoint needs a way to verify access tokens that it receives. If the token endpoint and Micropub endpoint are tightly coupled, then they can of course use an internal mechanism to verify access tokens.
Token endpoints that intend to interoperate with other endpoints MUST use the mechanism described below to allow other endpoints to verify access tokens.
If an external endpoint needs to verify that an access token is valid, it MUST make a GET request to the token endpoint containing an HTTP Authorization header with the Bearer Token according to [RFC6750]. Note that the request to the endpoint will not contain any user-identifying information, so the external endpoint (e.g. Micropub endpoint) will need to know via out-of-band methods which token endpoint is in use.
GET https://example.org/token
Authorization: Bearer xxxxxxxx
Accept: application/json
The token endpoint verifies the access token using (how this verification is done is up to the implementation), and returns information about the token:
me - The profile URL of the user corresponding to this tokenclient_id - The client ID associated with this tokenscope - A space-separated list of scopes associated with this token
HTTP/1.1 200 OK
Content-Type: application/json
{
"me": "https://user.example.net/",
"client_id": https://app.example.com/",
"scope": "create update delete"
}
Specific implementations MAY include additional parameters as top-level JSON properties. Clients SHOULD ignore parameters they don't recognize.
If the token is not valid, the endpoint MUST return an appropriate HTTP 400, 401 or 403 response. The response body is not significant.
6.3.5 Token Revocation
A client may wish to explicitly disable an access token that it has obtained, such as when the user signs out of the client. IndieAuth extends OAuth 2.0 Token Revocation [RFC7009] by defining the following:
- The revocation endpoint is the same as the token endpoint.
- The revocation request includes an additional parameter,
action=revoke.
An example revocation request is below.
POST https://example.org/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
action=revoke
&token=xxxxxxxx
As described in [RFC7009], the revocation endpoint responds with HTTP 200 for both the case where the token was successfully revoked, or if the submitted token was invalid.