Clean up to bring it to final state and add refs

Author: ArtyomVancyan

docs/integration/configuration.md

@@ -64,3 +64,5 @@ Claims(
     identity=lambda user: f"{user.provider}:{user.id}",
 )
 ```
+
+Check out the [tutorial](/references/tutorials#claims-mapping) on claims mapping for a clearer understanding.

docs/integration/integration.md

@@ -43,9 +43,9 @@ also contains all attributes of the user received from a certain provider.
 ### Callback
 
 The `callback` is called with the [`Auth`](#auth-context) and [`User`](#user-context) arguments when the authentication
-succeeds. This can be used for migrating an external user into the system of the existing application. Apart from other
-OAuth2 solutions that force using their base user models, certain architectural designs, or a database from a limited
-set of choices, this kind of solution gives developers freedom.
+succeeds. This can be used for [user provisioning](/references/tutorials#user-provisioning). Apart from other OAuth2
+solutions that force using their base user models, certain architectural designs, or a database from a limited set of
+choices, this kind of solution gives developers freedom.
 
 ## Router
 

docs/references/tutorials.md

@@ -4,16 +4,16 @@ outline: deep
 
 # Tutorials
 
-This documentation section contains samples and tutorials on important topics of using the library. Look at
+This documentation section covers samples and tutorials on important topics of using the library. Look at
 the [examples](https://github.com/pysnippet/fastapi-oauth2/tree/master/examples)
 and [tests](https://github.com/pysnippet/fastapi-oauth2/tree/master/tests) directories of the repository for other
 use-case implementations. Feel free to open an [issue](https://github.com/pysnippet/fastapi-oauth2/issues/new/choose) or
 a [discussion](https://github.com/pysnippet/fastapi-oauth2/discussions/new/choose) if your question is not covered by
 the documentation.
 
-## User authentication
+## Authentication
 
-By following the [integration](/integration/integration) docs, for the basic authentication, you must already have
+By following the [integration](/integration/integration) docs, for the basic user authentication, you must already have
 generated the client ID and secret to configure your `OAuth2Middleware` with at least one client configuration.
 
 1. Go to the developer console or settings of your OAuth2 identity provider and generate new client credentials.
@@ -28,31 +28,6 @@ generated the client ID and secret to configure your `OAuth2Middleware` with at
 Once the authentication is successful, the user will be redirected to the `redirect_uri` and the `request.user` will
 contain the user information obtained from the IDP.
 
-## User provisioning
-
-User provisioning refers to the process of creating, updating, and deleting user accounts within the OAuth2 IDP and
-synchronizing that information with your FastAPI application's database. There are two approaches to user provisioning
-and both require the user claims to be mapped properly for creating a new user or updating an existing one.
-
-### Automatic provisioning
-
-After successful authentication, you can automatically create a user in your application's database using the
-information obtained from the IDP. The user creation or update can be handled at the `callback` function of the
-[middleware](/integration/integration#oauth2middleware) as it is called when authentication succeeds.
-
-### Manual provisioning
-
-After successful authentication, redirect the user to a registration form where they can complete their profile. This
-approach is useful when there missing mandatory attributes in `request.user` for creating a user in your application's
-database. You need to define a route for provisioning and provide it as `redirect_uri`, so
-the [user context](/integration/integration#user-context) will be available for usage.
-
-::: info NOTE
-In both scenarios, it is recommended to use the `identity` attribute for uniquely identifying the user from the
-database. So if the application uses or plans to use multiple IDPs, make sure to include the `provider` attribute when
-calculating the `identity` attribute.
-:::
-
 ## Claims mapping
 
 The `Claims` class includes permanent attributes like `display_name`, `identity`, `picture`, and `email`. It also allows
@@ -88,8 +63,8 @@ Claims(
 
 ::: info NOTE
 
-Not all IDPs provide the `first_name` and the `last_name` attributes already joined as in the example or the `email` as
-a list. So you are given the flexibility using transformer function to map the attributes as you want.
+Not all IDPs provide the `first_name` and the `last_name` attributes already joined as in the example above, or
+the email in a list. So you are given the flexibility using transformer function to map the attributes as you want.
 
 ```mermaid
 flowchart LR
@@ -102,9 +77,32 @@ flowchart LR
 
 :::
 
-## CSRF protection
+## User provisioning
+
+User provisioning refers to the process of creating, updating, and deleting user accounts within the OAuth2 IDP and
+synchronizing that information with your FastAPI application's database. There are two approaches to user provisioning
+and both require the user claims to be mapped properly for creating a new user or updating an existing one.
+
+### Automatic provisioning
+
+After successful authentication, you can automatically create a user in your application's database using the
+information obtained from the IDP. The user creation or update can be handled at the `callback` function of the
+[middleware](/integration/integration#oauth2middleware) as it is called when authentication succeeds.
+
+### Manual provisioning
 
-## PKCE support
+After successful authentication, redirect the user to a registration form where they can complete their profile. This
+approach is useful when there missing mandatory attributes in `request.user` for creating a user in your application's
+database. You need to define a route for provisioning and provide it as `redirect_uri`, so
+the [user context](/integration/integration#user-context) will be available for usage.
+
+::: info NOTE
+
+In both scenarios, it is recommended to use the `identity` attribute for uniquely identifying the user from the
+database. So if the application uses or plans to use multiple IDPs, make sure to include the `provider` attribute when
+calculating the `identity` attribute.
+
+:::
 
 <style>
 .info {