====== OAuth ======

//This entire section of the wiki is entirely tentative! While it is unlikely, everything is still subject to change.//

Flashii uses a mix of [[https://oauth.net/2/|OAuth 2.0]], the experimental [[https://oauth.net/2.1/|OAuth 2.1]] and some components of [[https://openid.net/developers/how-connect-works/|OpenID Connect]] to provide authentication and authorization for third-party applications. Being that OAuth is a framework, certain things have been omitted and other things have been augmented where it makes sense, but at a basic level there should be no incompatibilities. The average existent OAuth 2.0 client library should be able to interact with our server implementation without issue.

Because OAuth has its own expected characteristics in how responses and requests are formatted, it is entirely separate from the actual Flashii API. Despite that, as of Version 1 of the Flashii API, the only major difference is the way errors are formatted.

===== Important Notes =====

  * Within the context of OAuth the term "Client" refers to the entity making requests to both the Authorization Server and Resource Server. This wiki may use the phrase "Application" interchangably, as that is how it is presented on the registration page.
  * Currently there is no distinction between the role of Authorization Server and Resource Server. If a distinction is ever introduced, using the metadata endpoints should make this process transparent.

===== Topics =====

  * [[client-types|Types of applications/clients]]
  * [[scope|Details about the scope parameter]]
  * [[discovery|Authorization endpoint discovery]]
  * [[authorize|Making a normal authorization request]]
  * [[device-authorize|Making a device authorization request]]
  * [[client-token|Requesting a token for acting on behalf of the application/client itself]]
  * [[token-refresh|Refreshing access tokens]]
  * [[token-introspection|Viewing details about tokens]]
  * [[token-revocation|Revoking tokens manually]]
  * [[openid|Details about OpenID support]]
  * [[idp|Using Flashii as an external identity provider]]
  * [[reference|Endpoint Reference]]

===== Implemented standards and drafts =====

For reference, a list of supported standards and drafts. The documentation on the wiki will cover everything you need to know specific to Flashii so you won't have to worry about this, but they're here if you're interested or in case there happen to be gaps in the documentation.

  * [[https://datatracker.ietf.org/doc/html/rfc6749|RFC6749]]: The base OAuth 2.0 authorization framework specification.
    * [[https://datatracker.ietf.org/doc/html/rfc8996|RFC8996]]: Deprecation of TLS 1.0 and 1.1, mostly as a result of server configuration.
    * [[https://datatracker.ietf.org/doc/html/rfc9700|RFC9700]]: Redirect URIs are validates against a known list; PKCE is available and required when not explicitly operating in OAuth 2.0 backwards compatible mode; Implicit and Resource Owner Password grants are omitted entirely; DPoP is not implemented at this time but may come in the future as an option.
  * [[https://datatracker.ietf.org/doc/html/rfc7009|RFC7009]]: An endpoint for revocation of access and refresh tokens is provided.
  * [[https://datatracker.ietf.org/doc/html/rfc7662|RFC7662]]: An endpoint for introspecion of access and refresh tokens is provided.
  * [[https://datatracker.ietf.org/doc/html/rfc8414|RFC8414]]: An endpoint with up-to-date metadata about the authorization server is available and should be used if possible. Certain fields specific to OpenID Connect are also included as the same output is used for the OpenID Metadata endpoint, both paths are provided for compatibility reasons.
  * [[https://datatracker.ietf.org/doc/html/rfc8628|RFC8628]]: Device Authorization Grant for clients that are not able to spawn a web browser window is available.
  * [[https://datatracker.ietf.org/doc/html/rfc9728|RFC9728]]: An endpoint with up-to-date protected resource information is available and may should additionally be used to resolve the authorization server.
  * [[https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13|draft-ietf-oauth-v2-1-13]]: A best-effort to implement OAuth 2.1 is made, but for compatibility with existing libraries and services an implicit downgrade to OAuth 2.0 behaviour is done where it doesn't compromise security too much. This may become a developer toggle in the future.
  * [[https://openid.net/specs/openid-connect-core-1_0.html|OpenID Connect Core 1.0]]: Provided for retrieving user info in a more universally standardised manner. Flashii API native alternatives may be available.
  * [[https://openid.net/specs/openid-connect-discovery-1_0.html|OpenID Connect Discovery 1.0]]: Both the aforementioned OpenID discovery endpoint and WebFinger endpoint for user lookup are available.

There are likely things I forgot to include in this list, as standards tend to depend on other standards themselves.