--- title: "Configuration oauthsonas" description: "Configurez les clients oauthsonas, personas, noms de claims, TTL et CORS. Décodage YAML strict et validation avec --check-config." canonical_url: https://optimi.com/fr/docs/oauthsonas/configuration md_url: https://optimi.com/fr/docs/oauthsonas/configuration.md last_updated: 2026-09-04 --- # Configuration oauthsonas La configuration YAML est décodée de façon **stricte** : les champs inconnus font échouer le démarrage au lieu d'être ignorés. Validez sans démarrer le serveur : ```sh go run ./cmd/oauthsonas --config config.yaml --check-config ``` Le dépôt fournit [`config.example.yaml`](https://github.com/optimiweb/oauthsonas/blob/main/config.example.yaml) avec un client public `dashboard` et des personas plateforme, staff et client. ## Champs de premier niveau | Champ | Rôle | | --- | --- | | `issuer` | URL d'issuer OIDC exacte (exemple : `http://127.0.0.1:8181`) | | `api_audience` | Audience apposée sur les access tokens | | `token_ttl` | Durée de vie des access tokens (et associés) | | `authorization_code_ttl` | Durée de vie des codes d'autorisation | | `refresh_token_ttl` | Durée de vie des refresh tokens | | `claims` | Surcharges optionnelles des noms de claims (voir ci-dessous) | | `clients` | Clients OAuth enregistrés | | `personas` | Identités sélectionnables sur la page d'autorisation | | `allowed_roles` | Vocabulaire optionnel ; si défini, les rôles des personas doivent en faire partie | ## Clients ```yaml clients: - id: dashboard name: Optimi Dashboard public: true redirect_uris: - http://127.0.0.1:5173/auth/callback post_logout_redirect_uris: - http://127.0.0.1:5173/ allowed_origins: - http://127.0.0.1:5173 ``` Règles : - `redirect_uris` et `post_logout_redirect_uris` sont des valeurs à **correspondance exacte**. Les paramètres de requête fixes sont autorisés ; les fragments ne le sont pas. - `allowed_origins` autorise le CORS navigateur uniquement pour les origines listées. - Les réponses token et userinfo appliquent le CORS propre au client ; la découverte et le JWKS appliquent le CORS uniquement à l'**union** des origines enregistrées — jamais `*`. - Les clients publics (comme dans l'exemple) exigent **S256 PKCE**. ## Personas Les personas sont les identités qu'un développeur choisit sur la page d'autorisation. Chacune a besoin d'un `id` unique et d'au moins un rôle : ```yaml personas: - id: acme-admin subject: oauthsonas|acme-admin email: admin@acme.dev.optimi.test name: Acme Administrator organization_id: org_acme roles: [customer-admin] - id: platform-admin subject: oauthsonas|platform-admin email: platform-admin@dev.optimi.test name: Platform Admin roles: [platform-admin] ``` | Champ | Requis | Notes | | --- | --- | --- | | `id` | oui | Sélecteur / valeur de formulaire stable | | `subject` | oui | JWT `sub` | | `email` | oui | Émis lorsque le scope `email` est accordé | | `name` | oui | Émis lorsque le scope `profile` est accordé | | `roles` | oui | Au moins un nom de rôle | | `organization_id` | non | Devient `org_id` (ou le claim configuré) s'il est défini | | `memberships` | non | Liste optionnelle d'appartenances multi-org | Les rôles sont portés comme **noms uniquement**. oauthsonas n'expand jamais les rôles en permissions applicatives — cela reste dans la partie cliente. Ajoutez un persona en appendant une entrée unique sous `personas`. Définissez optionnellement une liste de premier niveau `allowed_roles` si un projet veut une validation de vocabulaire au chargement de la config ; sinon tout nom de rôle non vide est valide. ## Claims applicatifs Les attributs de persona sont émis comme claims JWT et userinfo. Défauts : | Champ persona | Nom de claim par défaut | Quand il est émis | | --- | --- | --- | | `roles` | `roles` | Toujours (au moins un rôle requis) | | `organization_id` | `org_id` | Uniquement s'il est défini sur le persona | | `memberships` | `memberships` | Uniquement s'ils sont définis sur le persona | Exemple de payload d'access token avec les défauts : ```json { "roles": ["customer-admin"], "org_id": "org_acme" } ``` `org_id` est omis pour les personas staff sans `organization_id`. `memberships` est omis sauf si le persona les liste. ### Surcharger les noms de claims ```yaml claims: roles: roles memberships: memberships org_id: org_id ``` Utilisez des URL namespacées lorsqu'un consommateur exige des claims personnalisés style Auth0 : ```yaml claims: roles: https://example.com/roles memberships: https://example.com/memberships org_id: org_id ``` Règles : - Les noms de claims doivent être non vides et sans espaces. - Les trois noms configurés doivent être distincts les uns des autres. - Les mêmes noms apparaissent dans les access tokens, ID tokens, userinfo et `claims_supported` de la découverte. - Les champs YAML des personas (`roles`, `organization_id`, `memberships`) restent les mêmes ; seules les **clés** de claims JWT émises changent. - Les noms de claims personnalisés ne doivent pas entrer en collision avec les claims JWT/OIDC standard (par exemple `sub`, `email`, `scope`, `client_id`). ## Claims de profil gated par scope - `email` et `email_verified` exigent le scope `email`. - `name` exige `profile`. - Les scopes OAuth restent des scopes protocole et n'encodent pas de permissions applicatives. ## Clés et forme des tokens Le serveur génère une clé **RSA 2048 bits** au démarrage et publie la composante publique sur `/.well-known/jwks.json`. Les access et ID tokens sont signés en **RS256** et incluent un `kid` de durée de vie du processus. Aucun JWT non signé ni symétrique n'est produit. Les valeurs JWT `aud` sont sérialisées en tableaux JSON par Fosite (JWT/OIDC valide) : - Les access tokens ciblent l'`api_audience` configurée. - Les ID tokens ciblent l'ID client. ## Exemple : configuration minimale complète ```yaml issuer: http://127.0.0.1:8181 api_audience: https://api.example.test token_ttl: 15m authorization_code_ttl: 5m refresh_token_ttl: 8h clients: - id: dashboard name: Local Dashboard public: true redirect_uris: - http://127.0.0.1:5173/auth/callback post_logout_redirect_uris: - http://127.0.0.1:5173/ allowed_origins: - http://127.0.0.1:5173 personas: - id: developer subject: oauthsonas|developer email: dev@example.test name: Local Developer roles: [customer-admin] organization_id: org_local ``` ## Suite - Retour à **[oauthsonas](/fr/docs/oauthsonas)** pour le protocole, les conteneurs et l'automation. - **[Vue d'ensemble open source](/fr/docs/open-source)** pour les autres projets.