Failed Decryption with attributes

[mm192010]

Hello,

here is my subject mapping

"attribute_value": { "id": "f57fe245-0658-4d31-aa24-466ffe942583", "value": "finance", "active": { "value": true } }, "subject_condition_set": { "id": "d8a3295e-3a61-48de-8c56-f3bca8317ff3", "subject_sets": [ { "condition_groups": [ { "conditions": [ { "subject_external_selector_value": ".department", "operator": 1, "subject_external_values": [ "Finance" ] } ], "boolean_operator": 1 } ] } ],

Here i my JWT
"scope": "organization email profile", "email_verified": false, "name": "Jen Z", "preferred_username": "jen", "department": "Finance", "given_name": "Jen", "family_name": "Z", "email": "jen@email.com"

And here is how i login as jen
SDK sdk = builder .platformEndpoint(platformEndpoint) .clientSecret(clientId, clientSecret) .authorizationGrant( AuthorizationGrant.parse(Map.of( "grant_type", List.of("password"), "username", List.of(username), "password", List.of(password) )) ) .useInsecurePlaintextConnection(false) .sslFactory(sslFactory) .build();
But decryption fails. Pls review and let me know, if i missed something

Regards
Max

[marythought]

Hi Max, it looks like you've found a gap in our test coverage and documentation, and I've opened a PR to address it: #3122

Root cause: When using the default Keycloak ERS, subject mapping conditions are evaluated against the Keycloak user object, not the raw JWT claims. The ERS extracts preferred_username from your token, calls the Keycloak Admin API to fetch the full user record, and flattens that object for evaluation. A custom Keycloak user attribute department: ["Finance"] appears in the flattened object as:

.attributes.department[]  → "Finance"
.attributes.department[0] → "Finance"

There is no .department key. This means the selector .department never matches, even though your JWT contains "department": "Finance".

Fix: Update your subject_external_selector_value:

{
  "subject_external_selector_value": ".attributes.department[]",
  "operator": 1,
  "subject_external_values": ["Finance"]
}

Alternative: If you'd prefer to match JWT claims directly, configure the ERS with mode: "claims" in your platform config (default is "keycloak"). The Claims ERS passes JWT private claims through as-is, making .department work as a selector.

One thing to be aware of in claims mode: the correct selector also depends on the multi-valued setting of your Keycloak User Attribute mapper:

• Multi-valued OFF → claim is emitted as a string → use .department
• Multi-valued ON → claim is emitted as an array → use .department[]

The trade-off with claims mode is that the ERS only has access to what's in the token — it cannot look up Keycloak groups, roles, or other data from the user store.

Please confirm if this fix works for you. 🙏 And I'll make sure to update our documentation to reflect this as well. Thanks again!

[mm192010]

Thank you. The below worked.

{
  "subject_external_selector_value": ".attributes.department[]",
  "operator": 1,
  "subject_external_values": ["Finance"]
}

I have another question on attributes, i have a file with 2 attributes

• https://example.com/attr/department/value/finance
• https://example.com/attr/country/value/us
  I need Users to meet both the criteria to read the file. How the subject mapping will look like ?

i will also look into ERS. I am also try to setup a Platform deployment with keycloak but to another internal IDP which support OIDC. Any document for this?

Regards
Max

[marythought]

Hi Max, glad it's working!

Multiple attributes on one file (AND logic)

When a file is tagged with two attribute values, OpenTDF automatically enforces AND — a user must be entitled to both to decrypt. You need two separate subject mappings, one per attribute value — each linked to its specific attribute value ID:

Subject Mapping 1 — linked to department/value/finance:

{
  "subject_external_selector_value": ".attributes.department[]",
  "operator": 1,
  "subject_external_values": ["Finance"]
}

Subject Mapping 2 — linked to country/value/us:

{
  "subject_external_selector_value": ".attributes.country[]",
  "operator": 1,
  "subject_external_values": ["US"]
}

Note: .attributes.country[] assumes country is also a custom Keycloak user attribute. Run otdfctl dev selectors generate --subject "<your-jwt>" to confirm the exact selector if you're unsure.

No special configuration is needed to link them. The authorization service evaluates each attribute definition independently and requires all of them to pass — so tagging a file with two attributes automatically means both must be satisfied to decrypt.

For step-by-step instructions on creating these mappings, see the Subject Mappings reference and our (draft!) comprehensive guide (work in progress!!): Subject Mapping Guide (PR preview) — PR #182 -- would love any feedback here if this works for you, or not, as we are actively refining documentation.

Using a non-Keycloak OIDC IdP

Yes, there is documentation for this — see the Entity Resolution Service docs for an overview of all three supported ERS modes, and the platform Configuring.md for the full configuration field reference.

For a non-Keycloak OIDC IdP, use the Claims ERS (mode: claims). Instead of calling the Keycloak Admin API, the Claims ERS passes JWT claims through as-is — it works with any standards-compliant OIDC provider.

Two things to configure:

1. Platform auth — set server.auth.issuer and server.auth.audience to your IdP's values (these are standard OIDC fields, not Keycloak-specific)
2. ERS mode — switch to claims mode (and remove any Keycloak-specific fields like clientid, clientsecret, and realm from your config):

services:
  entityresolution:
    mode: claims

With claims mode, your subject mapping selectors target JWT claims directly — the exact selector depends on how your IdP structures the token. Use otdfctl dev selectors generate --subject "<your-jwt>" to see all valid selectors for a token from your IdP before writing your subject mappings.

See the Entity Resolution Service docs for a full comparison of ERS modes, including the Multi-Strategy ERS (preview) which supports SQL, LDAP, and JWT backends if you need richer identity lookups beyond what's in the token.

[mm192010]

Thanks Mary. I will try out. Currently I use AuthorizationGrant to pass username password for user in keycloak.

1. How to use this for external IDP? I can get token externally, but how to pass to SDK ?

        SDKBuilder.newBuilder()
                .platformEndpoint(config.platformEndpoint)
                .clientSecret(config.clientId, config.clientSecret)
                .authorizationGrant(
                        new ResourceOwnerPasswordCredentialsGrant(username, new Secret(password))
                )
                .useInsecurePlaintextConnection(false)
                .sslFactory(config.sslFactory)
                .build();

2. I also want to test this with otdfctl. pls give me sample command.

Regards
Max

[marythought]

Happy to help with both!

Q1 — Passing an externally obtained token to the Java SDK

The SDKBuilder has a .tokenExchange(String jwt) method for this. It performs an OAuth 2.0 Token Exchange (RFC 8693): it presents your external token to the platform's token endpoint to obtain a DPoP-bound token. Use it in place of ResourceOwnerPasswordCredentialsGrant:

String externalToken = "..."; // your externally obtained access token

SDK sdk = SDKBuilder.newBuilder()
    .platformEndpoint(platformEndpoint)
    .clientSecret(clientId, clientSecret)  // still required to identify the OAuth client
    .tokenExchange(externalToken)          // exchanges your external token at the platform token endpoint
    .useInsecurePlaintextConnection(false)
    .sslFactory(sslFactory)
    .build();

Note: Token exchange requires the platform's IdP (Keycloak) to be configured to accept tokens issued by your external IdP — this is a Keycloak identity brokering / token exchange policy configuration, not something the SDK handles. If Keycloak isn't configured to trust the external IdP, the exchange will fail.

The tokenExchange method is available in the SDK source (SDKBuilder.java) but is not yet documented on the docs site — if this is blocking you or unclear, let me know and I can prioritize getting that documented.

---

Q2 — Testing with otdfctl

The otdfctl CLI supports a few auth options depending on what you have available:

Option A — pass a token directly (if you already have one in hand):

otdfctl --host https://your-platform:8443 \
  --with-access-token "$TOKEN" \
  decrypt file.tdf

Option B — use client credentials (if your service client exists in the external IdP):

otdfctl --host https://your-platform:8443 \
  --with-client-creds='{"clientId":"myClient","clientSecret":"mySecret"}' \
  decrypt file.tdf

You can also set up a named profile once and reuse it, using the otdfctl auth client-credentials command:

otdfctl profile create --host https://your-platform:8443 my-profile
otdfctl auth client-credentials myClientId myClientSecret
otdfctl decrypt file.tdf

All auth flags (--with-access-token, --with-client-creds, --with-client-creds-file, --profile) are listed on the CLI reference page.

[mm192010]

Thank you Mary. To summarize my understanding, keycloak is mandatory for the platform setup, need to configure the external IDP with keycloak and do token exchange. let me try out.