Skip to content

feat: DSPX-2416 add subject mapping guide #182

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marythought wants to merge 5 commits into
base: main
Choose a base branch
from
+1,373 −3
Open

feat: DSPX-2416 add subject mapping guide #182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
768aff8
feat: DSPX-2416 add subject mapping deep dive to new Guides section
marythought Feb 9, 2026
4dbc281
code review
marythought Feb 9, 2026
648196c
fix vale ci issues
marythought Feb 9, 2026
6e73256
go back to previous example
marythought Feb 9, 2026
d13dfd0
updates to agents file
marythought Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .github/vale-styles/config/Vocab/Opentdf/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
Docusaurus
[Oo]tdfctl
API
(?i)tdf
[Nn]amespace
Keycloak
Virtru
SDK
IdP
NPE
PE
FQN
JWT
proto
Postgres
ECDSA
[Nn]ano
Podman
assertation
[Dd]issem
JavaScript
Autoconfigure
requester(?('s))
rewrap(?(s))
20 changes: 17 additions & 3 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,13 @@
- `npm run check-vendored-yaml`: Verify vendored OpenAPI YAML matches upstream.
- `npm run update-vendored-yaml`: Refresh vendored specs in `specs/` from upstream.

Preview deployment:
- Deploy to preview using pattern: `surge build opentdf-docs-preview-<ticket>.surge.sh`
- Extract ticket number from branch name (e.g., branch `feat/dspx-2416` → `opentdf-docs-preview-dspx-2416.surge.sh`)

Docs-only checks:
- `vale sync`: Install Vale styles configured in `.vale.ini`.
- `git diff --name-only | xargs vale --glob='!blog/*'`: Lint changed docs (matches CI’s “added lines” behavior closely).
- `git diff --name-only | xargs vale --glob='!blog/*'`: Lint changed docs (matches CI's "added lines" behavior closely).

Check failure on line 27 in AGENTS.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'CI's'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'CI's'?", "location": {"path": "AGENTS.md", "range": {"start": {"line": 27, "column": 84}}}, "severity": "ERROR"}

## Coding Style & Naming Conventions

Expand All @@ -30,8 +34,18 @@

## Testing Guidelines

- There is no dedicated unit test runner; CI primarily validates `npm run build` and Vale.
- If you touch `docs/getting-started/` Docker Compose instructions, sanity-check them locally when feasible.
CI runs the following tests:

- **BATS tests**: Shell script tests in `tests/quickstart.bats` validate quickstart scripts on Ubuntu, macOS, and Windows
- **Shellcheck**: Lints shell scripts in `static/quickstart/` (check.sh, install.sh)

Check failure on line 40 in AGENTS.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Shellcheck'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Shellcheck'?", "location": {"path": "AGENTS.md", "range": {"start": {"line": 40, "column": 5}}}, "severity": "ERROR"}
- **Docker Compose stack test**: Verifies the platform starts successfully on Ubuntu (triggered by changes to `docs/getting-started/`, `static/quickstart/`, or `tests/`)
- **Build validation**: `npm run build` must complete successfully
- **Vale linting**: Documentation prose style checks (run locally with `git diff --name-only | xargs vale --glob='!blog/*'`)

If you modify quickstart scripts or Docker Compose instructions:
- Run shellcheck locally: `shellcheck static/quickstart/check.sh static/quickstart/install.sh`

Check failure on line 46 in AGENTS.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'shellcheck'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'shellcheck'?", "location": {"path": "AGENTS.md", "range": {"start": {"line": 46, "column": 7}}}, "severity": "ERROR"}
- Run BATS tests if available: `bats tests/quickstart.bats`
- Test the Docker Compose stack if feasible: Follow steps in `docs/getting-started/quickstart.mdx`

## Commit & Pull Request Guidelines

Expand Down
4 changes: 4 additions & 0 deletions docs/components/policy/subject_mappings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Subject Mappings

:::tip New to Subject Mappings?
For a comprehensive tutorial with IdP integration examples, troubleshooting, and step-by-step guides, see the [Subject Mapping Comprehensive Guide](/guides/subject-mapping-guide).

Check failure on line 4 in docs/components/policy/subject_mappings.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'SDK' instead of 'IdP'.

Raw Output:
{"message": "[Vale.Terms] Use 'SDK' instead of 'IdP'.", "location": {"path": "docs/components/policy/subject_mappings.md", "range": {"start": {"line": 4, "column": 35}}}, "severity": "ERROR"}
:::

As data is bound to fully qualified Attribute Values when encrypted within a TDF, entities are associated with Attribute values through a mechanism called Subject Mappings.

Entities (subjects, users, machines, etc.) are represented by their identity as determined from an identity provider (IdP). After an entity has securely authenticated with the IdP, the client's token (OIDC/OAUTH2) will include claims or attributes that describe that identity. Subject Mappings define how to map these identity attributes to actions on attribute values defined in the OpenTDF platform Policy. For more details on how the platform integrates with the IdP and how entities are resolved, refer to the [Authorization documentation](../authorization).
Expand Down
8 changes: 8 additions & 0 deletions docs/guides/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"label": "Guides",
"position": 3,
"link": {
"type": "generated-index",
"description": "Comprehensive guides and tutorials for implementing OpenTDF features."
}
}
Loading
Loading