docs: add generic OIDC authentication documentation

Add comprehensive authentication guide explaining that Catalogi
supports any OIDC-compliant provider via automatic discovery.

- New authentication.md with generic OIDC setup guide
- Environment variables (OIDC_ISSUER_URI, OIDC_CLIENT_ID, etc.)
- Keycloak configuration example
- Redirect URIs, scopes, troubleshooting, security
- Update sidebar and README with authentication section

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: JeromeBu

docs/3.1-authentication.md

@@ -0,0 +1,103 @@
+<!-- SPDX-FileCopyrightText: 2021-2025 DINUM <[email protected]> -->
+<!-- SPDX-FileCopyrightText: 2024-2025 Université Grenoble Alpes -->
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- SPDX-License-Identifier: Etalab-2.0 -->
+
+# Authentication
+
+Catalogi uses OpenID Connect (OIDC) for authentication, allowing you to connect to any OIDC-compliant identity provider.
+
+## How It Works
+
+Catalogi implements the standard OIDC Authorization Code Flow:
+
+1. User clicks login
+2. Application redirects to identity provider
+3. User authenticates with the provider
+4. Provider redirects back with authorization code
+5. Application exchanges code for tokens
+6. User is authenticated
+
+The implementation uses automatic OIDC discovery via `/.well-known/openid-configuration`, making it compatible with any standard OIDC provider.
+
+## Required Environment Variables
+
+To configure authentication, you need to set the following environment variables:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `OIDC_ISSUER_URI` | The OIDC provider's issuer URL (without `.well-known/openid-configuration`) | `https://auth.example.com/realms/my-realm` |
+| `OIDC_CLIENT_ID` | Your application's client ID registered with the provider | `catalogi` |
+| `OIDC_CLIENT_SECRET` | Your application's client secret | `secret-value-here` |
+| `OIDC_MANAGE_PROFILE_URL` | URL where users can manage their profile (optional) | `https://auth.example.com/realms/my-realm/account` |
+| `APP_URL` | Your Catalogi application URL (used for redirect URIs) | `http://localhost:3000` |
+
+## Redirect URIs to Configure
+
+When registering your application with the identity provider, you need to configure these redirect URIs:
+
+- **Login callback**: `${APP_URL}/api/auth/callback`
+- **Logout callback**: `${APP_URL}/api/auth/logout/callback`
+
+For example, if `APP_URL=http://localhost:3000`:
+- Login callback: `http://localhost:3000/api/auth/callback`
+- Logout callback: `http://localhost:3000/api/auth/logout/callback`
+
+## Required OIDC Scopes
+
+The application requests the following standard OIDC scopes:
+- `openid` - Required for OIDC
+- `email` - To get user email
+- `profile` - To get user profile information
+
+For AgentConnect/ProConnect, additional scopes are automatically added:
+- `given_name`
+- `usual_name`
+
+## Configuration Example
+
+### Keycloak
+
+Keycloak is an open-source identity and access management solution used as reference example.
+
+```bash
+OIDC_ISSUER_URI=http://localhost:8080/realms/catalogi
+OIDC_CLIENT_ID=catalogi
+OIDC_CLIENT_SECRET=your-client-secret
+OIDC_MANAGE_PROFILE_URL=http://localhost:8080/realms/catalogi/account
+APP_URL=http://localhost:3000
+```
+
+See [Setting up Keycloak](3.2-setup-a-keycloak.md) for detailed Keycloak setup instructions.
+
+## Other OIDC Providers
+
+Any OIDC-compliant provider should work (Keycloak, AgentConnect, ProConnect, Auth0, Okta, Google, Azure AD, etc.) as long as it:
+1. Provides a `/.well-known/openid-configuration` discovery endpoint
+2. Supports the Authorization Code flow
+3. Provides standard `openid`, `email`, and `profile` scopes
+4. Returns user information with at least `sub` and `email` claims
+
+Generic configuration:
+```bash
+OIDC_ISSUER_URI=https://your-provider.com
+OIDC_CLIENT_ID=your-client-id
+OIDC_CLIENT_SECRET=your-client-secret
+OIDC_MANAGE_PROFILE_URL=https://your-provider.com/account
+APP_URL=http://localhost:3000
+```
+
+## Security
+
+**Production requirements**:
+- Use HTTPS for `APP_URL`
+- Keep `OIDC_CLIENT_SECRET` secure
+- Sessions use secure HTTP-only cookies (24h expiry)
+- Tokens stored server-side only
+
+## Related Documentation
+
+- [Setting up Keycloak](3.2-setup-a-keycloak.md) - Detailed Keycloak setup guide
+- [Environment Variables and Customization](6-env-variables-and-customization.md) - All environment variables
+- [Deploying with Docker Compose](4-deploying-with-docker-compose.md) - Production deployment
+- [Deploying with Kubernetes](5-deploying-with-kubernetes.md) - Kubernetes deployment

docs/3-setup-a-keycloak.md renamed to docs/3.2-setup-a-keycloak.md

@@ -24,8 +24,11 @@ Use the sidebar on the left to navigate through the complete documentation:
 ### Getting Started
 - **[Getting Started](2-getting-started.md)** - Set up and run Catalogi locally for development
 
-### Deployment Guides  
-- **[Setting up Keycloak](3-setup-a-keycloak.md)** - Authentication setup with Keycloak
+### Authentication
+- **[Authentication (OIDC)](3.1-authentication.md)** - Configure authentication with any OIDC provider
+- **[Setting up Keycloak](3.2-setup-a-keycloak.md)** - Detailed Keycloak setup guide
+
+### Deployment Guides
 - **[Deploying with Docker Compose](4-deploying-with-docker-compose.md)** - Production deployment using Docker Compose
 - **[Deploying with Kubernetes](5-deploying-with-kubernetes.md)** - Scalable deployment with Kubernetes
 - **[Environment Variables and Customization](6-env-variables-and-customization.md)** - Configuration options and customization

docs/README.md

@@ -4,7 +4,8 @@
 <!-- SPDX-License-Identifier: Etalab-2.0 -->
 
 * [🎯 Getting started](2-getting-started.md)
-<!-- * [🔐 Setting up Keycloak](3-setup-a-keycloak.md) -->
+* [🔐 Authentication (OIDC)](3.1-authentication.md)
+* [🔐 Setting up Keycloak](3.2-setup-a-keycloak.md)
 * [🏁 Deploying the web App (docker-compose)](4-deploying-with-docker-compose.md)
 * [🏁 Deploying the web App (Kubernetes)](5-deploying-with-kubernetes.md)
 * [⚙ Environment variables and customization](6-env-variables-and-customization.md)