###############################################################################
# OAuth Providers — Microsoft 365 + Google (B-2.4)
###############################################################################
#
# These providers complement (do NOT replace) the generic OIDC SSO at
# config/env.sso.example. Both can be enabled simultaneously: users see
# Microsoft 365, Google, and SSO buttons on /login, plus the magic-link
# fallback that does not require any OAuth provider.
#
# IMPORTANT — Loi 25 art. 14 (consent must be granular, free, informed):
# OAuth signups still require Loi 25 consent capture via
# /auth/oauth/finish-signup BEFORE the User row is created. Existing
# users (matched by sso_subject or email) skip the consent page and log
# in directly.
#
# Magic-link login (/auth/magic-link, /auth/magic-link/<token>) reuses
# the SMTP settings from env.email.example — no additional env vars needed.

###############################################################################
# Microsoft 365 (Microsoft Entra ID, formerly Azure AD)
###############################################################################
# 1. Register a new app at https://entra.microsoft.com
#    > Identity > Applications > App registrations > New registration
# 2. Set the redirect URI to:
#       https://your-domain.example/auth/oauth/microsoft/callback
# 3. Generate a client secret under Certificates & secrets > Client secrets
# 4. Set MS_CLIENT_ID to the Application (client) ID
# 5. Set MS_CLIENT_SECRET to the secret VALUE (NOT the secret ID)
#
# Tenant restriction: by default the OAuth flow accepts users from any
# Microsoft tenant (server_metadata_url uses /common/). To restrict to a
# specific organization, edit src/auth/oauth_providers.py and replace
# /common/ with your tenant ID (e.g. /your-tenant-id-guid/).
#
# MS_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# MS_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

###############################################################################
# Google (Google Cloud Console)
###############################################################################
# 1. Create an OAuth client at https://console.cloud.google.com
#    > APIs & Services > Credentials > Create Credentials > OAuth client ID
#    Application type: "Web application"
# 2. Set the redirect URI to:
#       https://your-domain.example/auth/oauth/google/callback
# 3. Configure the OAuth consent screen in the same console
#    (must be in "Production" status to accept users outside the test list)
# 4. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from the credentials page
#
# GOOGLE_CLIENT_ID=xxxxxxxxxxxx-xxxxxxxxxxxx.apps.googleusercontent.com
# GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxx

###############################################################################
# Notes
###############################################################################
#
# Token storage:
# - sso_provider stores the literal string "microsoft" or "google"
# - sso_subject stores the OAuth `sub` claim (provider-issued user ID)
# - email_verified is set to True automatically (the provider has
#   already verified the email address)
# - password is NULL for OAuth-only accounts; users can set a password
#   later via /forgot-password if they want a fallback login method
#
# Magic-link tokens:
# - Stateless via itsdangerous.URLSafeTimedSerializer
# - 15-minute expiry, signed with SECRET_KEY + salt 'magic-link-login'
# - No DB column — tokens are not single-use within the 15-min window
# - SMTP must be configured (see env.email.example) for the link to send