diff --git a/docs/reference/clients.md b/docs/reference/clients.md new file mode 100644 index 00000000..967c3f0b --- /dev/null +++ b/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`.