feat: DSPX-2416 add subject mapping guide

[marythought]

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:

• Why Subject Mappings exist: Addresses the core misconception that IdP attributes directly map to OpenTDF attributes
• Complete authentication flow: Sequence diagrams showing IdP → Entity Resolution → Subject Mapping → Authorization
• Entity types explained: Clarifies PE/NPE, Subject/Environment categories, and the common jwtentity-0 vs jwtentity-1 confusion
• Subject Condition Sets: 5 progressively complex examples from simple role matching to multi-group logic
• Enumerated vs. Dynamic attributes: Most frequently asked question - when to use fixed values vs. freeform strings
• Real IdP integration examples: Keycloak, Auth0, and Okta with actual token structures and JMESPath selectors
• Step-by-step creation guide: Complete workflow using otdfctl commands
• Comprehensive troubleshooting: Solutions for "resource relation invalid", missing entitlements, and entity type issues
• Best practices & FAQ: Reusable condition sets, hierarchical attributes, pattern-based mappings

Documentation Structure

• Created new "Guides" section (/docs/guides/) for comprehensive tutorials and deep-dives
• Added cross-reference in /docs/components/policy/subject_mappings.md pointing to the comprehensive guide
• Established pattern for future comprehensive guides

Preview

https://opentdf-docs-preview-dspx-2416.surge.sh/guides/subject-mapping-guide

[gemini-code-assist]

Summary of Changes

Hello @marythought, I'm Gemini Code Assist¹! 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 Comprehensive Subject Mapping Guide: A detailed tutorial has been added at /docs/guides/subject-mapping-guide.md to clarify core concepts, authentication flow, entity types, condition sets, attribute types, IdP integration examples (Keycloak, Auth0, Okta), creation steps, troubleshooting, and best practices for Subject Mappings.
• Documentation Structure Enhancement: A new 'Guides' section (/docs/guides/) has been introduced in the documentation to organize comprehensive tutorials and deep-dives, improving content discoverability.
• Cross-referencing Existing Documentation: The existing docs/components/policy/subject_mappings.md file now includes a prominent tip box that links directly to the new comprehensive Subject Mapping guide, ensuring users are directed to the most complete resource.

🧠 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

• docs/components/policy/subject_mappings.md
  • Added a Docusaurus tip block at the beginning of the file, directing users to the new comprehensive Subject Mapping guide.
• docs/guides/category.json
  • Created a new JSON file to define the 'Guides' category in the documentation sidebar, including its label, position, and description.
• docs/guides/subject-mapping-guide.md
  • Added a new Markdown file containing the extensive 'Subject Mapping: Comprehensive Guide'. This guide covers the core problem, architecture, entity types, condition sets with examples, enumerated vs. dynamic attributes, IdP integration examples (Keycloak, Auth0, Okta), step-by-step creation, troubleshooting, best practices, and FAQs.

Activity

• The author, marythought, has created a new comprehensive guide for Subject Mapping.
• The documentation structure has been updated to include a new 'Guides' section.
• An existing documentation page now cross-references the newly created guide.

Using Gemini Code Assist

The 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 /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

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 .gemini/ folder in the base of the repository. Detailed instructions can be found here.

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

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

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.

[jp-ayyappan]

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.

https://github.com/opentdf/docs/blob/docs/update_policy_docs/docs/explanation/platform-architecture/components/policy/subject_mappings.md

[jp-ayyappan]

Check my comment on the PR; we should sync up

[marythought]

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.

https://github.com/opentdf/docs/blob/docs/update_policy_docs/docs/explanation/platform-architecture/components/policy/subject_mappings.md

@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]

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.