Merge branch 'main' into feature/algorithmic-anonymous-sessions

docs/reference/clients.md

@@ -0,0 +1,124 @@
+---
+title: Clients
+---
+
+# Clients
+
+A Client is an entity that uses authentication and authorization services provided by the Authorization Server. 
+This authorization enables the Client to access protected resources.
+In a common scenario, the Client is a browser application and the Resource Owner is a backend application 
+located on a remote server.
+
+Before a Client can ask for authorization, it must get registered at the Authorization Server and obtain a unique ID.
+The registration can either be done in Admin UI or via the Admin API.
+
+## Client metadata
+
+The actual list of client metadata supported by Seacat Auth can be obtained at `GET /client/features` API.
+
+### Canonical OAuth 2.0 and OpenID Connect metadata
+
+Defined in [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
+and [OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591#section-2).
+
+#### `client_id`
+`NOT EDITABLE` Unique ID of the Client. By default, it is an opaque string generated by the Authorization Server.
+It is possible to request a custom ID by supplying the non-canonical `preferred_client_id` parameter in the 
+client registration request.
+The ID is not editable once the client is already registered.
+
+#### `client_name`
+`REQUIRED` Human-palatable name of the Client to be presented to the End-User.
+
+#### `client_secret`
+OAuth 2.0 client secret string. This value is used by confidential clients to authenticate to the token endpoint.
+It is generated by the Authorization Server and is not directly editable. 
+
+#### `client_uri`
+URL of the home page of the Client.
+
+#### `redirect_uris`
+`REQUIRED` Array of Redirection URI values used by the Client.
+
+#### `application_type`
+Kind of the application. The default, if omitted, is `web`.
+
+Supported options: `web`
+
+#### `response_types`
+JSON array containing a list of the OAuth 2.0 response_type values that the Client is declaring that it will restrict 
+itself to using. If omitted, the default is that the Client will use only the `code` Response Type.
+
+Supported options: `code`
+
+#### `grant_types`
+JSON array containing a list of the OAuth 2.0 Grant Types that the Client is declaring that it will restrict itself 
+to using. If omitted, the default is that the Client will use only the `authorization_code` Grant Type.
+
+Supported options: `authorization_code`
+
+#### `token_endpoint_auth_method`
+Requested Client Authentication method for the Token Endpoint. If omitted, the default is `none`.
+
+Supported options: `none`
+
+#### `code_challenge_method`
+Code Challenge Method (used in [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636)) 
+that the Client will restrict itself to use at the Authorize Endpoint. The default, if omitted, is `none`.
+
+Supported options: 
+
+- `none`: PKCE is disabled.
+- `plain`: Code challenge is the same as the code verifier.
+- `S256`: Code challenge is derived from the code verifier by using SHA-256 hashing algorithm.
+
+
+## Non-canonical metadata
+
+These are Seacat-Auth-specific features.
+
+#### `preferred_client_id`
+`REGISTRATION ONLY` Requests a specific `client_id` instead of a randomly generated one at client registration.
+
+#### `redirect_uri_validation_method`
+Specifies the method how the redirect URI used in authorization requests is validated. The default and recommended 
+value is `full_match`.
+
+Supported options: 
+
+- `full_match`: **The only OAuth2.0 compliant option.** Requested Redirect URI must exactly match one of the registered
+  Redirect URIs.
+- `prefix_match`: Requested Redirect URI must start with one of the registered Redirect URIs and their hostname must 
+  exactly match.
+- `none`: There is no Redirect URI validation. Not secure.
+
+#### `cookie_name`
+`NOT EDITABLE` Unique cookie name derived from Client ID by the Authorization Server. Cookie with this name holds 
+the information 
+
+#### `cookie_webhook_uri`
+Webhook URI for setting additional custom cookies at the cookie entrypoint. It must be a back-channel URI and must 
+accept a JSON PUT request and respond with a JSON object of cookies to set.
+
+#### `cookie_entry_uri`
+Public URI of the client's cookie entrypoint. This field is **required** for cookie-based authorization (including 
+batman authorization). One such entrypoint should be available on every hostname where there are Clients that use 
+cookie-based authorization.
+
+#### `cookie_domain`
+Domain of the client cookie. If not specified, the application's default cookie domain is used.
+
+#### `authorize_uri`
+URL of OAuth authorize endpoint. Useful when logging in from different than the default domain.
+
+#### `login_uri`
+URL of preferred login page. Useful when logging in from different than the default domain.
+
+#### `authorize_anonymous_users`
+Boolean value specifying whether to authorize requests with anonymous users.
+
+#### `anonymous_cid`
+ID of credentials that is used for authenticating anonymous sessions.
+
+#### `session_expiration`
+Client session expiration. The value can be either the number of seconds or a time-unit string such as `4 h` or `3 d`.