This section describes how to authenticate users and optionally obtain an access token using the OAuth 2.0 Authorization Code Flow with IndieAuth.
Note: If the client is only trying to learn who the user is and does not need an access token, the client exchanges the authorization code for the user profile information at the Authorization Endpoint instead.
5.2 Authorization Request
The client builds the authorization request URL by starting with the discovered authorization_endpoint URL and adding parameters to the query component.
All IndieAuth clients MUST use PKCE ([RFC7636]) to protect against authorization code injection and CSRF attacks. A non-canonical description of the PKCE mechanism is described below, but implementers should refer to [RFC7636] for details.
Clients use a unique secret per authorization request to protect against authorization code injection and CSRF attacks. The client first generates this secret, which it can later use along with the authorization code to prove that the application using the authorization code is the same application that requested it.
The client first creates a code verifier for each authorization request by generating a random string using the characters [A-Z] / [a-z] / [0-9] / - / . / _ / ~ with a minimum length of 43 characters and maximum length of 128 characters. This value is stored on the client and will be used in the authorization code exchange step later.
The client then creates the code challenge derived from the code verifier by calculating the SHA256 hash of the code verifier and Base64-URL-encoding the result.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
For backwards compatibility, authorization endpoints MAY accept authorization requests without a code challenge if the authorization server wishes to support older clients.
response_type=code - Indicates to the authorization server that an authorization code should be returned as the responseclient_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.code_challenge - The code challenge as previously described.code_challenge_method - The hashing method used to calculate the code challenge, e.g. "S256"scope - (optional) A space-separated list of scopes the client is requesting, e.g. "profile", or "profile create". If the client omits this value, the authorization server MUST NOT issue an access token for this authorization code. Only the user's profile URL may be returned without any scope requested. See Profile Information for details about which scopes to request to return user profile information.me - (optional) The profile URL that the user entered
https://example.org/auth?response_type=code&
client_id=https://app.example.com/&
redirect_uri=https://app.example.com/redirect&
state=1234567890&
code_challenge=OfYAxt8zU2dAPDWQxTAUIteRzMsoj9QBdMIVEDOErUo&
code_challenge_method=S256&
scope=profile+create+update+delete&
me=https://user.example.net/
The client SHOULD provide the me query string parameter to the authorization endpoint, either the exact value the user entered, or the canonical profile URL resulting from the discovery step.
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], or delegate to other identity providers.
The authorization endpoint MAY use the provided me query component as a hint of which user is attempting to sign in, and to indicate which profile URL the client is expecting in the resulting profile URL response or access token response. This is specifically helpful for authorization endpoints where users have multiple supported profile URLs, so the authorization endpoint can make an informed decision as to which profile URL the user meant to identify as. Note that from the authorization endpoint's view, this value as provided by the client is unverified external data and MUST NOT be assumed to be valid data at this stage. If the logged-in user doesn't match the provided me parameter by the client, the authorization endpoint MAY either ignore the me parameter completely or display an error, at the authorization endpoint's discretion.
Once the user is authenticated, the authorization endpoint presents the authorization request 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.
5.2.1 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, and MUST be valid for only one use. 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.
5.3 Redeeming the Authorization Code
Once the client has obtained an authorization code, it can redeem it for an access token or the user's final profile URL.
5.3.1 Request
If the client needs an access token in order to make requests to a resource server such as a [Micropub] endpoint, it can exchange the authorization code for an access token and the user's profile URL at the token endpoint.
If the client only needs to know the user who logged in and does not need to make requests to resource servers with an access token, the client exchanges the authorization code for the user's profile URL at the authorization endpoint.
After the client validates the state parameter, the client makes a POST request to the token endpoint or authorization endpoint to exchange the authorization code for the final user profile URL and/or access token. The POST request contains the following parameters:
grant_type=authorization_codecode - The authorization code received from the authorization endpoint in the redirect.client_id - The client's URL, which MUST match the client_id used in the authentication request.redirect_uri - The client's redirect URL, which MUST match the initial authentication request.code_verifier - The original plaintext random string generated before starting the authorization request.
Example request to authorization endpoint
POST https://example.org/auth
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
&code_verifier=a6128783714cfda1d388e2e98b6ae8221ac31aca31959e59512c59f5
Example request to token endpoint
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
&code_verifier=a6128783714cfda1d388e2e98b6ae8221ac31aca31959e59512c59f5
Note that for backwards compatibility, the authorization endpoint MAY allow requests without the code_verifier. If an authorization code was issued with no code_challenge present, then the authorization code exchange MUST NOT include a code_verifier, and similarly, if an authorization code was issued with a code_challenge present, then the authorization code exchange MUST include a code_verifier.
5.3.2 Profile URL Response
When the client receives an authorization code that was requested with either no scope or only profile scopes (defined below), the client will exchange the authorization code at the authorization endpoint, and only the canonical user profile URL and possibly profile information is returned.
The authorization endpoint verifies that the authorization code is valid, has not yet been used, and that it was issued for the matching client_id and redirect_uri, and checks that the provided code_verifier hashes to the same value as given in the code_challenge in the original authorization request. If the request is valid, then the endpoint responds with a JSON [RFC7159] object containing the property me, with the canonical user profile URL for the user who signed in, and optionally the property profile with the user's profile information as defined in Profile Information.
HTTP/1.1 200 OK
Content-Type: application/json
{
"me": "https://user.example.net/"
}
The resulting profile URL MAY be different from canonical profile URL as resolved by the client, but MUST be on the same domain. This gives the authorization endpoint an 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, and see Differing User Profile URLs for security considerations client developers should be aware of..
See OAuth 2.0 [RFC6749] Section 5.2 for how to respond in the case of errors or other failures.
5.3.3 Access Token Response
When the client receives an authorization code that was requested with one or more scopes that will result in an access token being returned, the client will exchange the authorization code at the token endpoint.
The token endpoint needs to verify that the authorization code is valid, and that it was issued for the matching client_id and redirect_uri, contains at least one scope, and checks that the provided code_verifier hashes to the same value as given in the code_challenge in the original authorization request. 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].
The specifics of how the token endpoint verifies the authorization code are out of scope of this document, as typically the authorization endpoint and token endpoint are part of the same system and can share storage or another private communication mechanism.
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, and optionally the property profile with the user's profile information as defined in Profile Information. 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 the canonical profile URL as resolved by the client, 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.
If the client would like to request the user's profile information in addition to confirming their profile URL, the client can include one or more scopes in the initial authorization request. The following scope values are defined by this specification to request profile information about the user:
profile (required) - This scope requests access to the user's default profile information which include the following properties: name, photo, url.email - This scope requests access to the user's email address in the following property: email.
Note that because the profile scope is required when requesting profile information, the email scope cannot be requested on its own and must be requested along with the profile scope if desired.
When an authorization code is issued with any of the scopes defined above, then the response when exchanging the authorization code MAY include a new property, profile, alongside the me property in the response from the authorization endpoint or the token endpoint. The profile property is defined as a JSON [RFC7159] object with the properties defined by each scope above.
For example, a complete response to a request with the scopes profile email create, including an access token and profile information, may look like the following:
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "XXXXXX",
"token_type": "Bearer",
"scope": "profile email create",
"me": "https://user.example.net/",
"profile": {
"name": "Example User",
"url": "https://user.example.net/",
"photo": "https://user.example.net/photo.jpg",
"email": "user@example.net"
}
}
As is always the case with OAuth 2.0, there is no guarantee that the scopes the client requests will be granted by the authorization server or the user. The client should not rely on the presence of profile information even when requesting the profile scope. As such, implementing support for returning profile information from the authorization server is entirely optional.
The information returned in the profile object is informational, and there is no guarantee that this information is "real" or "verified". The information provided is only what the user has chosen to share with the client, and may even vary depending on which client is requesting this data.
The client MUST NOT treat the information in the profile object as canonical or authoritative, and MUST NOT make any authentication or identification decisions based on this information.
For example, attempting to use the email returned in the profile object as a user identifier will lead to security holes, as any user can create an authorization endpoint that returns any email address in the profile response. A client using the email address returned here should treat it the same as if it had been hand-entered in the client application and go through its own verification process before using it.
Similarly, the url returned in the profile object is not guaranteed to match the me URL, and may even be on a different domain. For example, a multi-author website may use the website's URL as the me URL, but return each specific author's own personal website in the profile data.
