📝(oidc) add "how-to" documentation about backends

This provides a very simple documentation about how to integrate the
backends in a project. This is surely not enough.

Author: qbey

documentation/how-to-use-oidc-backend.md

@@ -0,0 +1,97 @@
+# Using the OIDC Authentication Backend
+
+This guide explains how to integrate and configure the `OIDCAuthenticationBackend` in your Django project for OpenID Connect (OIDC) authentication.
+
+## Installation
+
+1. Ensure you have the necessary packages installed:
+
+```bash
+pip install django-lasuite
+```
+
+## Configuration
+
+### Settings
+
+Add the following to your Django settings:
+
+```python
+# Add the authentication backend
+AUTHENTICATION_BACKENDS = [
+    'lasuite.oidc_login.backends.OIDCAuthenticationBackend',
+]
+
+# Required OIDC settings
+OIDC_RP_CLIENT_ID = "your-client-id"
+OIDC_RP_CLIENT_SECRET = "your-client-secret"
+OIDC_OP_TOKEN_ENDPOINT = "https://your-provider.com/token"
+OIDC_OP_USER_ENDPOINT = "https://your-provider.com/userinfo"
+OIDC_OP_LOGOUT_ENDPOINT = "https://your-provider.com/logout"
+
+# Optional settings
+OIDC_USER_SUB_FIELD = "sub"  # Field to store the OIDC subject identifier, defaults to "sub"
+USER_OIDC_FIELDS_TO_FULLNAME = ["first_name", "last_name"]  # Fields used to compute user's full name
+OIDC_FALLBACK_TO_EMAIL_FOR_IDENTIFICATION = True  # Allow fallback to email for user identification
+OIDC_CREATE_USER = True  # Automatically create users if they don't exist
+ALLOW_LOGOUT_GET_METHOD = True  # Allow GET method for logout
+```
+
+### URLs
+
+Include the OIDC URLs in your project's `urls.py`:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    # Your other URLs
+    path('', include('lasuite.oidc_login.urls')),
+]
+```
+
+## User Model Requirements
+
+Your User model should include the following fields:
+
+1. `sub` - To store the OIDC subject identifier, you may replace this with 
+    another field if needed but needs to set the `OIDC_USER_SUB_FIELD` setting
+2. `email` - For user identification (especially if fallback to email is enabled)
+3. `name` - To store user's full name (computed from fields defined in `USER_OIDC_FIELDS_TO_FULLNAME`)
+
+## Authentication Flow
+
+1. User is redirected to the OIDC provider login page
+2. After successful authentication, the provider redirects back to your app
+3. The backend verifies the authentication and:
+   - Retrieves an existing user based on the `sub` field or falls back to email
+   - Creates a new user if no match is found (when `OIDC_CREATE_USER=True`)
+   - Updates user information if needed
+4. User is now authenticated in your application
+
+## Logout Functionality
+
+The package includes custom logout views that will properly sign the user out from both your application and the OIDC provider.
+
+## Customization
+
+To customize the behavior of the OIDC authentication backend, you can create your own subclass:
+
+```python
+from lasuite.oidc_login.backends import OIDCAuthenticationBackend
+
+
+class CustomOIDCAuthenticationBackend(OIDCAuthenticationBackend):
+    def get_extra_claims(self, user_info):
+        # Add custom claims processing
+        claims = super().get_extra_claims(user_info)
+        claims['custom_field'] = user_info.get('custom_field')
+        return claims
+
+    def post_get_or_create_user(self, user, claims):
+        # Add custom post-processing
+        super().post_get_or_create_user(user, claims)
+        # Additional processing...
+```
+
+Then update your `AUTHENTICATION_BACKENDS` setting to use your custom class.

documentation/how-to-use-oidc-resource-server-backend.md

@@ -0,0 +1,112 @@
+# Using the OIDC Resource Server Backend
+
+This guide explains how to integrate and configure the `ResourceServerBackend` in your Django project for secure API access using OpenID Connect (OIDC) token introspection.
+
+## Overview
+
+The `ResourceServerBackend` allows your application to act as an OAuth 2.0 resource server, validating access tokens through introspection with an authorization server. This enables secure API access control using OIDC standards.
+
+## Installation
+
+1. Ensure you have the necessary packages installed:
+
+```bash
+pip install django-lasuite
+```
+
+## Configuration
+
+### Settings
+
+Add the following to your Django settings:
+
+```python
+# Resource Server Backend
+OIDC_RS_BACKEND_CLASS = "lasuite.oidc_resource_server.backend.ResourceServerBackend"
+
+# Resource Server Configuration
+OIDC_RS_AUDIENCE_CLAIM = "client_id"  # The claim used to identify the audience
+OIDC_RS_ENCRYPTION_ENCODING = "A256GCM"  # Encryption encoding algorithm
+OIDC_RS_ENCRYPTION_ALGO = "RSA-OAEP"  # Encryption algorithm
+OIDC_RS_SIGNING_ALGO = "ES256"  # Signing algorithm
+OIDC_RS_SCOPES = ["groups"]  # Required scopes for authentication
+
+# Private key for encryption/decryption
+OIDC_RS_PRIVATE_KEY_STR = """-----BEGIN PRIVATE KEY-----
+YOUR_PRIVATE_KEY_HERE
+-----END PRIVATE KEY-----"""
+OIDC_RS_ENCRYPTION_KEY_TYPE = "RSA"  # Key type (RSA, EC, etc.)
+
+# Client credentials
+OIDC_RP_CLIENT_ID = "your-client-id"
+OIDC_RP_CLIENT_SECRET = "your-client-secret"
+
+# Authorization server endpoints
+OIDC_OP_TOKEN_ENDPOINT = "https://your-provider.com/token"
+OIDC_OP_USER_ENDPOINT = "https://your-provider.com/userinfo"
+```
+
+### URLs Configuration
+
+Include the OIDC Resource Server URLs in your project's `urls.py`:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    # Your other URLs
+    path('', include('lasuite.oidc_resource_server.urls')),
+]
+```
+
+This will expose the JWKS endpoint (`/jwks`) which provides the public key used for token verification.
+
+## Usage in Views
+
+To secure your API views, use the authorization backend with Django REST Framework:
+
+```python
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from lasuite.oidc_resource_server.authentication import ResourceServerAuthentication
+
+class SecureAPIView(APIView):
+    authentication_classes = [ResourceServerAuthentication]
+    permission_classes = [IsAuthenticated]
+    
+    def get(self, request):
+        # Your secure view logic here
+        return Response({"message": "Authenticated access"})
+```
+
+## Token Verification Flow
+
+1. Client sends request with access token in Authorization header
+2. `ResourceServerBackend` intercepts the request
+3. Backend sends token to authorization server for introspection
+4. Backend validates returned claims (issuer, audience, etc.)
+5. If valid, request is processed; otherwise, authentication fails
+
+## Advanced: JWT Resource Server
+
+For JWT-based introspection (RFC 9701), use the `JWTResourceServerBackend`:
+
+```python
+OIDC_RS_BACKEND_CLASS = "lasuite.oidc_resource_server.backend.JWTResourceServerBackend"
+```
+
+This implementation handles JWT format introspection responses that are signed and encrypted, providing an additional layer of security.
+
+## Key Management
+
+The resource server requires a key pair:
+- The private key is used for decryption and stored securely in your settings
+- The public key is exposed via the JWKS endpoint for the authorization server
+
+Generate a suitable RSA key, like using OpenSSL:
+
+```bash
+openssl genrsa -out private_key.pem 2048
+```