diff --git a/docs/README.md b/docs/README.md index 9685e5df..52ac2cf1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,6 @@ This documentation has four main sections: - The [installation guide](./setup/README.md) will guide you through the process of setting up the `matrix-authentication-service` on your own infrastructure. - The topics sections goes into more details about how the service works, like the [policy engine](./topics/policy.md) and how [authorization sessions](./topics/authorization.md) are managed. - The reference documentation covers [configuration options](./reference/configuration.md), the [GraphQL API](./reference/graphql.md), the [scopes](./reference/scopes.md) supported by the service, and the [command line interface](./reference/cli/). -- The developer documentation is intended for people who want to [contribute to the project](./development/contributing.md). Other links: +- The developer documentation is intended for people who want to [contribute to the project](./development/contributing.md). Developers may also be interested in: - Technical documentation for individual crates: [`rustdoc`](./rustdoc/mas_handlers/) - UI components: [`storybook`](./storybook/) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 33959a2c..4abab79b 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -157,7 +157,7 @@ clients: client_auth_method: none ``` -**Note:** any additions or modification in this list are synced with the database on server startup. Removed entries are only removed with the [`config sync --prune`](../reference/cli/config.md#config-sync---prune---dry-run) command. +**Note:** any additions or modifications in this list are synced with the database on server startup. Removed entries are only removed with the [`config sync --prune`](../reference/cli/config.md#config-sync---prune---dry-run) command. ## `secrets` @@ -410,7 +410,7 @@ upstream_oauth2: # - `private_key_jwt` (using the keys defined in the `secrets.keys` section) token_endpoint_auth_method: client_secret_post - # What signing algorithm to use to sign the authentication request when using + # Which signing algorithm to use to sign the authentication request when using # the `private_key_jwt` or the `client_secret_jwt` authentication methods #token_endpoint_auth_signing_alg: RS256 @@ -498,7 +498,7 @@ upstream_oauth2: ## `experimental` Settings that may change or be removed in future versions. -Some of those settings are in this section just because they don't have a stable place in the configuration yet. +Some of which are in this section because they don't have a stable place in the configuration yet. ```yaml experimental: diff --git a/docs/reference/graphql.md b/docs/reference/graphql.md index 96fbde29..ed700df1 100644 --- a/docs/reference/graphql.md +++ b/docs/reference/graphql.md @@ -2,11 +2,11 @@ MAS provides a GraphQL API which serves two purposes: - - it is used by the self-service user interface (usually accessible on `/account/`), for users to manage their own account - - it can be used with external tools to manage the service + - it is used by the self-service user interface (usually accessible on `/account/`), for users to manage their own account. + - it can be used with external tools to manage the service. The endpoint for this API can be discovered through the OpenID Connect discovery document, under the `"org.matrix.matrix-authentication-service.graphql_endpoint` key. -It is though usually hosted at `https:///graphql`. +Though it is usually hosted at `https:///graphql`. GraphQL uses [a self-describing schema](https://github.com/matrix-org/matrix-authentication-service/blob/main/frontend/schema.graphql), which means that the API can be explored in tools like the GraphQL Playground. If enabled, MAS hosts an instance of the playground at `https:///graphql/playground`. diff --git a/docs/topics/authorization.md b/docs/topics/authorization.md index 3efc86ed..b5527412 100644 --- a/docs/topics/authorization.md +++ b/docs/topics/authorization.md @@ -1,7 +1,7 @@ # Authorization and sessions -The main job of the authentication service is to grant access to resources to clients, and to lets resources know who is accessing them. -In less abstract terms, this means that the service is responsible for issuing access token and let the homeserver (and other services) introspect those access tokens. +The main job of the authentication service is to grant access to resources to clients, and to let resources know who is accessing them. +In less abstract terms, this means that the service is responsible for issuing access tokens and letting the homeserver (and other services) introspect those access tokens. ## How access tokens work @@ -13,7 +13,7 @@ An access token has: - a client for which the token is issued - a timeframe for which the token is valid -On a single token, those metadata are immutable: they don't change over time. +On a single token, metadata is immutable: it doesn't change over time. One exception is the validity of the token: the service may revoke a token before its expiration date. A typical client will get a short-lived access token (valid 5 minutes) along with a refresh token. @@ -34,7 +34,7 @@ Out of this request, Synapse will care about the following: - [`urn:matrix:org.matrix.msc2967.client:device:AABBCC`], which encodes the Matrix device ID used by the client - [`urn:synapse:admin:*`], which grants access to the Synapse admin API -It's important to understand that when Synapse delegates the authentication to MAS, a lot of user attributes are not managed by Synapse anymore. +It's important to understand that when Synapse delegates authentication to MAS, Synapse no longer manages many user attributes. This includes the user admin, locked, and deactivated status. ## Compatibility sessions @@ -57,7 +57,7 @@ This was the case in the past with Synapse, as the admin status was set on the u ## OAuth 2.0 sessions Modern clients are expected to use OAuth 2.0 to authenticate with the homeserver. -In OAuth 2.0/OIDC, there are multiple way to start an OAuth 2.0 session called grants. +In OAuth 2.0/OIDC, there are multiple ways to start an OAuth 2.0 session called grants. An OAuth 2.0 session has three important properties: diff --git a/docs/topics/policy.md b/docs/topics/policy.md index c6718a40..193fe7f6 100644 --- a/docs/topics/policy.md +++ b/docs/topics/policy.md @@ -32,7 +32,7 @@ The policy is evaluated in three different scenarios: ### Client registration -The policy ([`client_registration.rego`]) is evaluated when a client send their metadata through the OAuth 2.0 dynamic client registration API. +The policy ([`client_registration.rego`]) is evaluated when a client sends their metadata through the OAuth 2.0 dynamic client registration API. By default, it enforces a set of strict rules to make sure clients provide enough information about themselves, with coherent URLs. This is useful in production environments, but can be relaxed in development environments.