refactor: Update authentication documentation for clarity and completeness

- Revise the authentication section to enhance readability and structure.
- Introduce Single Sign-On (OIDC) details and emphasize security best practices.
- Consolidate information on built-in username/password and session management.

Author: lovasoa

examples/official-site/safety.sql

@@ -86,23 +86,37 @@ parameter of the [`shell`](documentation.sql?component=shell#component) componen
 
 ## Authentication
 
-SQLPage provides an [authentication](/documentation.sql?component=authentication#component) component that allows you to
-restrict access to some pages of your website to authenticated users.
-
-It also provides useful built-in functions such as 
-[`sqlpage.basic_auth_username()`](/functions.sql?function=basic_auth_username#function), 
-[`sqlpage.basic_auth_password()`](/functions.sql?function=basic_auth_password#function) and 
-[`sqlpage.hash_password()`](/functions.sql?function=hash_password#function)
-to help you implement your authentication system entirely in SQL.
-
-The components and functions provided by SQLPage are designed to be used by non-technical users,
-and to respect [security best practices](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) by default.
-Passwords are [hashed with a salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) using the
-[argon2](https://en.wikipedia.org/wiki/Argon2) algorithm.
-
-However, if you implement your own session management system using the [`cookie` component](/documentation.sql?component=cookie#component),
-you should be careful to follow the [OWASP session management best practices](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#cookies).
-Implementing your own session management system is not recommended if you are a non-technical user and don''t have a good understanding of web security.
+Use either the built-in username/password or Single Sign-On; both follow safe defaults.
+
+### Built-in username/password
+
+SQLPage provides an [authentication](/documentation.sql?component=authentication#component) component to protect pages,
+with helpers like [`sqlpage.basic_auth_username()`](/functions.sql?function=basic_auth_username#function),
+[`sqlpage.basic_auth_password()`](/functions.sql?function=basic_auth_password#function), and
+[`sqlpage.hash_password()`](/functions.sql?function=hash_password#function).
+Passwords are salted and hashed with [argon2](https://en.wikipedia.org/wiki/Argon2),
+following [best practices](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html).
+
+### Session management
+
+If you implement your own sessions using the [`cookie` component](/documentation.sql?component=cookie#component),
+follow the [OWASP recommendations](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#cookies).
+Avoid rolling your own unless you fully understand web security.
+
+### Single Sign-On (OIDC)
+
+When OIDC is enabled, SQLPage validates a signed identity token on every request
+before any of your SQL runs. Without a successful login, requests are redirected
+to your identity provider and your application code never executes.
+This keeps attackers outside your SSO realm from reaching your app,
+even if a vulnerability exists in your own code.
+
+By default, all pages are protected. You can scope access using the
+`oidc_protected_paths` and `oidc_public_paths` settings. See the
+[configuration documentation](https://github.com/sqlpage/SQLPage/blob/main/configuration.md#openid-connect-oidc-authentication).
+Once authenticated, access user claims with
+[`sqlpage.user_info()`](/functions.sql?function=user_info) or inspect the full token with
+[`sqlpage.user_info_token()`](/functions.sql?function=user_info_token).
 
 ## Protection against [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery)