Conversation
Summary of ChangesHello @marythought, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the OpenTDF documentation by introducing a comprehensive guide on Subject Mapping. This guide aims to resolve common misunderstandings by clearly explaining how identity provider attributes are translated into OpenTDF access entitlements, detailing the full authentication and authorization flow, and providing practical examples and troubleshooting steps. The addition of a new 'Guides' section also improves the overall organization and discoverability of in-depth tutorials. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive guide for Subject Mappings, a frequently misunderstood concept in OpenTDF. The new guide is well-structured, detailed, and covers the topic from core concepts to IdP integration and troubleshooting. The changes also include creating a new 'Guides' section in the documentation and linking to the new guide from the existing subject mappings page. Overall, this is an excellent addition to the documentation that will be very helpful for the community. I have one suggestion to improve the clarity of the section on dynamic attributes to avoid potential confusion for users.
|
You and I, we are working on the same stuff; we should sync up and I should hand over my branch to you before you re-write everything. |
jp-ayyappan
left a comment
jp-ayyappan
left a comment
There was a problem hiding this comment.
Check my comment on the PR; we should sync up
@jp-ayyappan It looks like your changes are to the component page about subject mappings, which is great. This one is built as a guide/deep dive that references that page, so I don't think there is any conflict here. |
marythought
force-pushed
the
feat/dspx-2416
branch
3 times, most recently
from
5ec83fe to
d13dfd0
Compare
|
This PR introduces the concept of a "Guide", which may or may not be aligned with the Diataxis definition: https://diataxis.fr/how-to-guides/ . I am open to moving this to an alternative section or re-writing it to be more of a "guide" based on that link. |
Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
marythought
force-pushed
the
feat/dspx-2416
branch
from
d13dfd0 to
5526bf0
Compare
Signed-off-by: Mary Dickson <mary.dickson@virtru.com>
|
We should get rid of the Vale check and introduce something else that is better |
| @@ -1,5 +1,9 @@ | |||
| # Subject Mappings | |||
|
|
|||
| :::tip New to Subject Mappings? | |||
There was a problem hiding this comment.
I'm not sure the best way to do this, but we will want to make it clearer that Subject Mappings are actually logically checking the Entity Resolution Service response (entity representation). The source of truth for the ERS to build an entity representation can be:
- access token claims (the actual JWT)
- idP user info (keycloak, okta, etc)
- LDAP (active directory, etc)
- SQL (a relational database)
The multi-strategy ERS still in experimental status, but there is a need to productionize it to support entity attributes from diverse sources. Mature organizations keep user/entity information across several kinds of systems, and as a platform we should support these.
Practically that means a subject mapping relating a condition set to an attribute value where the condition set finds jake@acme.org IN .emailAddress, depending on the ERS running with the platform and its mode, that could be:
- a JWT payload claim
emailAddressin my access token - an attribute in my idP
emailAddress - a directory attribute
emailAddressin my LDAP system - a column value in my row in a SQL-compatible database, where a query results in a JSON object with a key
emailAddress
TLDR: we should find a clear way to communicate that entity attributes are stored in diverse systems, organized/resolved by ERS, conditionally resolved to platform Attribute Values via Subject Mappings with Subject Condition Sets.
There was a problem hiding this comment.
Addressed in commit 930f394 — added a :::note block immediately after the :::tip in subject_mappings.md that explains:
- Subject Mappings evaluate against the Entity Representation produced by ERS, not directly against IdP tokens
- Lists the four sources (JWT claims, IdP user info, LDAP/AD, SQL) explicitly
- Notes that the same .emailAddress selector works regardless of which source ERS resolves it from
- Links to the Entity Resolution docs for multi-source ERS details
- Added a note that multi-source support is available (left the experimental status callout to the ERS docs page rather than flagging it as experimental here, since that status may change)
| "conditions": [{ | ||
| "subject_external_selector_value": ".groups", | ||
| "operator": 3, | ||
| "subject_external_values": ["/finance/"] |
There was a problem hiding this comment.
I am not sure if these pre and post-fixed slashes are typical. If not, they look a little confusing given our FQN structure, so maybe we could remove them?
There was a problem hiding this comment.
@jakedoublev ok, I spiraled with Claude on this for a good amount of time. It insists that they are needed specifically for a Keycloak group due to the "contains" lookup to prevent false matches. Does this make sense to you? It makes sense to me (based on the underlying code), and if it checks out we can add a comment explaining why the slashes are needed here and not elsewhere.
Why /finance/ has slashes:
Keycloak's "Full Group Path" mapper — when enabled, Keycloak includes group paths in tokens as slash-prefixed hierarchical paths: /finance/senior, not finance. The guide says "User 'bob' is in Keycloak group: /finance/senior" — that IS the literal token value when Full Group Path is on.
Operator 3 is IN_CONTAINS — from [subject_mapping_builtin.go:252](vscode-webview://1p4elejgd9vcld7v92e8m83vnphukfjrb0fjgesrann251okld6r/code/opentdf/platform/service/internal/subjectmappingbuiltin/subject_mapping_builtin.go#L252), this does strings.Contains(mappedValue, possibleValue). So it checks whether the group string /finance/senior contains the substring /finance/.
The trailing slash is intentional precision — /finance/ prevents false matches against /finance-external or /financeops. Without it, IN_CONTAINS with /finance would match any group starting with those characters.
docs/guides/subject-mapping-guide.md
Outdated
| - `jwtentity-0`: The **client application** (NPE - Non-Person Entity) | ||
| - `jwtentity-1`: The **user** (PE - Person Entity) | ||
|
|
||
| **Both need Subject Mappings** if both need attribute access. For SDK decryption, typically the client (`jwtentity-0`) needs mappings based on `.clientId`. |
There was a problem hiding this comment.
The more reliable field to check in logs is environment vs subject entity. In GetEntitlements flows, both subject and environment category entities are considered. In GetDecision flows, only subject category entities are considered, so only they need subject mappings. All users authenticate to an idP through an OIDC Client, which is what causes two chained entities to be present in the authorization logs, but the client (environment) and user (subject) are only identical when using client credentials authentication flows as service accounts for NPEs. Otherwise, the user and client will each correspond to the subject and environment entities in the logs and decisioning flows respectively.
…d content and deprecated APIs - Replace deprecated STANDARD_ACTION_DECRYPT with `read` throughout (objects.proto) - Fix selector syntax: was incorrectly described as JMESPath; platform uses custom flattening library (platform/lib/flattening/flatten.go) - Correct entity category explanation: only CATEGORY_SUBJECT entities are evaluated in GetDecision flows; CATEGORY_ENVIRONMENT (OIDC client) is excluded (authorization.go:653-666) - Rewrite "Dynamic Attribute Values" section — feature does not exist; all values must be explicitly created (attributes.proto CreateAttributeValueRequest) - Remove Auth0 IdP section (untested) - Remove nonexistent "order" key from HIERARCHY attribute JSON (objects.proto Value message) - Fix troubleshooting DENY advice: client entity does not need Subject Mappings in user-auth flows; clarify service account (client credentials) exception - Add otdfctl dev selectors generate/test examples to troubleshooting - Add ERS multi-source note to subject_mappings.md (JWT, LDAP, SQL, IdP user info) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…2930, #1877, #1483, #1021 - Add --subject-sets-file-json alternative for complex condition sets (#1483) - Add --allow-traversal flag explanation for encrypt-before-value-exists pattern (#2930, #1877) - Link to ADR #1181 (typed entities) to explain SUBJECT/ENVIRONMENT design intent (#1021) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… Keycloak group paths - .groups → .groups[] for Keycloak and Okta group examples - .realm_access.roles → .realm_access.roles[] for Keycloak role examples - Add scalar vs array selector reference table with explanation - Fix troubleshooting array example with explanatory comment - Add note on Keycloak Full Group Path mapper and why values include slashes Evidence: lib/flattening/flatten.go produces .key[], .key[0] for arrays — there is no .key key. Confirmed by subject_mapping_builtin_actions_test.go:85 which uses SubjectExternalSelectorValue: ".groups[]" Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Scope (?i)tdf → (?i:tdf) to prevent Go regexp from applying
case-insensitive flag to all subsequent vocab entries (root cause
of spurious Vale.Terms errors like "Use 'JWT' instead of 'IdP'")
- Fix invalid PCRE conditionals: rewrap(?(s)) → rewraps? and
requester(?('s)) → requester('s)?
- Add CI, [Ss]hellcheck, and Okta to suppress false spelling errors
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… and accuracy - Add NIST roles table with actionable "How to use it" links - Update high-level diagram to use full service names - Move NIST table below the diagram - Add per-step-group intro sentences explaining each phase - Fix JWT claims note: clarify email/role/groups are configured, not standard - Remove duplicate prose in steps 3-5 and 6-9 - Add plain-language intro to Subject Mapping JSON example - Fix ERS description: called by KAS, not Authorization Service Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…or codes, fix fake IDs - Add inline explanation of boolean_operator and operator enum values in Step 1 with link to reference section - Add otdfctl policy attributes list command to Step 2 so users can find their attribute ID - Add substitution reminder in Step 3 (IDs shown are from previous steps) - Fix sm-789xyz fake placeholder to a proper UUID format in Steps 3 and 4 - Link prerequisites (platform running, otdfctl) to /quickstart Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Explain .email selector syntax and link to Selectors section - Clarify subject_external_values are matched against JWT claim values - Show attributes list first in Step 2; explain UUID format and clearance/secret display label - Explain --action read is the standard decrypt action - Add payoff sentence in Step 3 explaining what the mapping does at runtime - Add Step 4 guidance on what a correct mapping looks like and what null subject_condition_set means - Add Next Steps section pointing to TDF SDK and troubleshooting - Fix diagram box border cutoff with mirrorActors: false - Fix intro sentence for step-by-step section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3 participants
Summary
Creates comprehensive Subject Mapping guide to resolve the top recurring documentation gap identified across community discussions.
Changes
New: Subject Mapping Comprehensive Guide
Created
/docs/guides/subject-mapping-guide.md- a complete tutorial addressing the most frequently misunderstood concept in OpenTDF.What It Covers:
otdfctlcommandsDocumentation Structure
/docs/guides/) for comprehensive tutorials and deep-dives/docs/components/policy/subject_mappings.mdpointing to the comprehensive guidePreview
https://opentdf-docs-preview-dspx-2416.surge.sh/guides/subject-mapping-guide