New OpenTDF quickstart guides!

[marythought]

👋 Hello all, Mary here -- I'm so happy to join the Virtru team this year as a Developer Experience Engineer. In this new-to-the-company role, I'll be focused on helping developers succeed with OpenTDF SDKs and other Virtru products.

I've spent some time streamlining the OpenTDF installation steps into a multi-operating system friendly script, and adding relevant business context to help developers new to the services understand OpenTDF concepts. We also added a quickstart for the Go and Java SDKs, so if you haven't dug into those yet, now's a great time.

Give them a try and let us know your thoughts!

🚀 Setup guide: https://opentdf.io/quickstart <-- start here unless you already have a working OpenTDF platform
🛠️ SDK guide: https://opentdf.io/sdks/quickstart

Please drop a comment and let us know what worked, what didn't work, how long this took you to get running. We are here to help!

[mm192010]

These guides are great but only on a beginner level. Please give some examples on

• how different users can login using sdk?
• how user attributes are set in keycloak and utilized
• complex subject mapping,

Thanks
Max

[marythought]

thanks Max! We're in the process of a few of these, I'll link back when I have more to share. Do you have an example of a complex subject mapping you'd like to dig into?

[mm192010]

i was looking for

1. Run TDF Server without Keycloak, connect to external DB and IDP can be some other source
2. Custom Client will authenticate using another IDP, pass token to SDK and SDK connect to TDF Server and perform access request

Let me know in case you some draft document atleast

[marythought]

Hi Max, making sure you saw we just published two new guides that cover these topics:

Subject Mapping Guide covers:

• How user attributes in Keycloak (and other IdPs) flow into authorization decisions
• ERS modes: Keycloak mode (.attributes.department[]) vs Claims mode (.department)
• Complex subject mapping examples — multi-condition AND/OR logic, pattern-based matching with IN_CONTAINS, multi-attribute files
• IdP integration examples with Keycloak (realm roles, groups, combined claims)
• Step-by-step walkthrough for creating subject condition sets and mappings
• Troubleshooting common issues

Authentication Decision Guide covers:

• How different users/clients can authenticate via the SDK — client credentials, OIDC login flow, token exchange, certificate exchange, and custom token sources
• A decision flowchart and scenario matrix to pick the right method
• Development vs production configuration

Regarding your follow-up about running without Keycloak and connecting to an external IdP: OpenTDF is designed to work with any OIDC-compatible identity provider — Keycloak is the reference implementation but not a requirement. The authentication guide's Custom Token Source and Token Exchange sections are most relevant to that use case. If you have a specific IdP in mind, let us know and we can point you in the right direction.

We'd love to hear if these guides help with what you're working on!

[mm192010]

Thanks Mary, much appreciated on the new guides

Here is my scenario

1. Azure Entra ID is added as external IDP to our application IDP
2. User authenticates and get token from our application IDP (Internally it does the token exchange with EntraID)
3. User call decrypt doc call and passes JWT in header
4. Application backend call TDS Server passing the JWT

I am using standard deployment with keycloak behind the platform.
And to test the token exchange and authorizationGrant, i called and got token from Azure

Test 1. Custom Token Source - Did not work
Pass the JWT token in below code

        var jwtExchangeGrant = new TokenExchangeGrant(new BearerAccessToken(tokenFromAzure), TokenTypeURI.JWT);
                 SDK sdk = new SDKBuilder()
                .platformEndpoint(config.platformEndpoint)
                .clientSecret(config.clientId, config.clientSecret)
                .useInsecurePlaintextConnection(false)
                .authorizationGrant(jwtExchangeGrant)
                .sslFactory(config.sslFactory)
                .build();

Test 2. did not work
SDK sdk = new SDKBuilder()
.platformEndpoint(config.platformEndpoint)
.clientSecret(config.clientId, config.clientSecret)
.useInsecurePlaintextConnection(false)
.tokenExchange(tokenFromAzure)
.sslFactory(config.sslFactory)
.build();

Should i be also updated the opentdf.yaml audience and issuer ?

services:
  kas:
    eccertid: e1
    rsacertid: r1
  entityresolution:
    mode: claims
server:
  port: 8080
  auth:
    enabled: true
    enforceDPoP: false
    audience: "<Azure.ClientID>" 
    issuer: https://login.microsoftonline.com/<Azure.TenantID>/v2.0

Also for policy section,

    policy:
      username_claim: email
      groups_claim: # realm_access.roles
      client_id_claim: # azp

If i remove the keycloak from the setup., where to configure my IDP in platform settings so that the other authentication methods work,

[CRTified]

Hello, I'm trying to follow the quick-start guide for evaluating opentdf. It appears that there is a problem regarding the x-wing key generation, as the healthz endpoint fails with a 502:

The end of docker logs platform-platform-1 --tail 100 then points to said X-Wing key:

Setup was done on a fresh Ubuntu 26.04 LTS arm64 VM on an aarch64-darwin host using UTM (qemu) for virtualisation.

I am not sure whether I am doing anything wrong here, but I would assume that the health check should work after installation. Any pointers are appreciated :)

[marythought]

hi @CRTified ! Thanks for reporting this. We had a recent breaking change updating the hybrid key PEM format, and it looks like the quickstart has a version mismatch that means it was impacted.

We're tracking the fix in opentdf/docs#352. Hopefully will have this up and running again quickly.

[marythought]

Pushed a fix -- we have a test for this that failed on main with the same error you reported above, but it only runs on docs changes. I'll set that up to run nightly so we can catch any issues faster next time. :) Thanks again!

[CRTified]

Thank you for resolving this so quickly!