kevinveenbirkenbachandClaude Opus 5
fcc98bcad1
The lint accepted a link that resolved to a file or a directory. myst builds a document reference only when the target is_file(), so a link to a directory without a README is a bare file listing on GitHub and a dead cross-reference in the documentation build. It now reports which of the two reasons applies. The tightened rule found 41 links. Where a README backs the directory, bd15eae9fa's resolver carries the link and it stays. Where none exists, the link becomes a code span rather than an invented README: 15 of them point at a role's meta/addons/, whose addon table already sits below the sentence, and the rest at code directories such as utils/ or cli/administration/deploy/runner/. The changed sentences are msgids, so these entries return to the translator on the next extract. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2.4 KiB
Common 🧭
This page covers IAM rules that span both providers. Provider-specific guidance lives in oidc.md and ldap.md.
Two Providers, Two Namespaces 🎯
| Provider | Role | Variable namespace | Definition file |
|---|---|---|---|
| OIDC | web-app-keycloak | OIDC.* |
11_oidc.yml |
| LDAP | svc-db-openldap | LDAP.* |
12_ldap.yml |
Application roles MUST consume identity data exclusively through these namespaces. Hardcoding a claim name, attribute name, DN, or endpoint in a role template is forbidden because it bypasses the canonical definition file and breaks platform-wide renames or realm migrations.
Paired Identifier Principle 🔗
OIDC.ATTRIBUTES.USERNAME and LDAP.USER.ATTRIBUTES.ID are paired on purpose.
They MUST resolve to the same logical user on both sides so that an account created in OpenLDAP can sign in through Keycloak without an extra mapping step.
Changing one without the other breaks LDAP-OIDC correlation.
Integration Checklist For New Apps ✅
When you add OIDC or LDAP support to a role, you MUST:
- Read endpoints, client identifiers, and claim names from
OIDC.*. Never hardcode realm names, URLs, or claim strings. - Read attribute names, DNs, and the server URI from
LDAP.*. Never hardcodeuid,cn, base DNs, or LDAP URIs. - Use
OIDC.ATTRIBUTES.USERNAMEandLDAP.USER.ATTRIBUTES.IDas the user identifier on both sides. - Keep app-specific Keycloak protocol mappers in a per-client scope file
under the Keycloak
roles/web-app-keycloak/templates/import/scopes/directory. Do not extend default.json.j2. - Hide or disable application UI fields that are sourced from OIDC or LDAP, per the rules in javascript.js.md.
- Document the integration in the role README under Features and, when the wiring is non-obvious, in the role Developer Notes section. See readme_md.md.
Related Areas 📚
For the broader service-loading model see base.md. For the documentation conventions used in this directory see documentation.md.