Skip to content

Improve authorization SDK documentation and fix API version inconsistencies #140

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

Merged
jp-ayyappan merged 18 commits into from
Aug 25, 2025
Merged

Improve authorization SDK documentation and fix API version inconsistencies #140

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
d53b54b
Improve authorization SDK documentation and fix API version inconsist…
jp-ayyappan Aug 11, 2025
180d3e5
Address review comments: fix missing imports and undefined variable
jp-ayyappan Aug 11, 2025
b6ce8fe
Update getEntitlements examples to use realistic email-based user
jp-ayyappan Aug 11, 2025
88ac723
Address all remaining review comments: improve code quality and consi…
jp-ayyappan Aug 11, 2025
9315721
Standardize platform endpoints across all code samples to http://loca…
jp-ayyappan Aug 11, 2025
24e969e
Address PR review feedback from Gemini Code Assist
jp-ayyappan Aug 11, 2025
50b74e1
Fix protobuf getter usage in Token-based authentication example
jp-ayyappan Aug 12, 2025
8257d8b
Add obligation handling to authorization examples
jp-ayyappan Aug 12, 2025
33ea993
Fix OpenTDF Authorization SDK documentation with accurate v1/v2 API e…
jp-ayyappan Aug 15, 2025
b17b219
fix(docs): Fix authorization SDK examples for API consistency
jp-ayyappan Aug 15, 2025
5e28100
fix(docs): Add missing Entity_CategorySchema import in JavaScript exa…
jp-ayyappan Aug 15, 2025
75b6cc2
Update code_samples/authorization/get_decision.mdx
jp-ayyappan Aug 19, 2025
c518f86
Updated ts code
jp-ayyappan Aug 22, 2025
ea4e4cf
Merge remote-tracking branch 'origin/main' into docs/improve-authoriz…
jp-ayyappan Aug 22, 2025
9cef662
Update architecture documentation
jp-ayyappan Aug 23, 2025
b8a2227
docs(architecture): revise diagram to focus on OpenTDF components
jp-ayyappan Aug 25, 2025
057617d
feat(docs): overhaul architecture page for clarity and usability
jp-ayyappan Aug 25, 2025
073283b
Merge branch 'main' into docs/improve-authorization-sdk-documentation
jp-ayyappan Aug 25, 2025
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
158 changes: 110 additions & 48 deletions code_samples/authorization/get_decision.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,14 @@ import (
"log"

"github.com/opentdf/platform/protocol/go/authorization"
"github.com/opentdf/platform/protocol/go/entity"
"github.com/opentdf/platform/protocol/go/policy"
"github.com/opentdf/platform/sdk"
)

func main() {

platformEndpoint := "http://localhost:9002"
platformEndpoint := "http://localhost:8080"

// Create a new client
client, err := sdk.New(
Expand All @@ -32,47 +33,40 @@ func main() {
log.Fatal(err)
}

// Get Entitlements

decision := &authorization.GetDecisionsRequest{
DecisionRequests: []*authorization.DecisionRequest{
{
Actions: []*policy.Action{
{
Value: &policy.Action_Standard{
Standard: policy.Action_STANDARD_ACTION_DECRYPT,
},
},
},
EntityChains: []*authorization.EntityChain{
// Get Decision using v2 API
decisionReq := &authorization.GetDecisionRequest{
EntityIdentifier: &authorization.EntityIdentifier{
EntityChain: &entity.EntityChain{
Entities: []*entity.Entity{
{
Id: "entity-chain-1",
Entities: []*authorization.Entity{
{
Id: "entity-1",
EntityType: &authorization.Entity_ClientId{
ClientId: "opentdf",
},
},
Id: "entity-1",
EntityType: &entity.Entity_ClientId{
ClientId: "opentdf",
},
},
},
ResourceAttributes: []*authorization.ResourceAttribute{
{
ResourceAttributesId: "resource-attribute-1",
AttributeValueFqns: []string{"https://opentdf.io/attr/role/value/developer"},
},
},
},
},
Action: &policy.Action{
Name: "decrypt",
},
Resource: &authorization.Resource{
AttributeValues: &authorization.Resource_AttributeValues{
Fqns: []string{"https://opentdf.io/attr/role/value/developer"},
},
},
}

decisions, err := client.Authorization.GetDecisions(context.Background(), decision)
decision, err := client.Authorization.GetDecision(context.Background(), decisionReq)
if err != nil {
log.Fatal(err)
}

log.Printf("Decisions: %v", decisions.GetDecisionResponses())
decisionResult := decision.GetDecision()
log.Printf("Decision: %v", decisionResult.GetDecision())
if decisionResult.GetDecision() == authorization.Decision_DECISION_PERMIT && len(decisionResult.GetObligations()) > 0 {
log.Printf("Obligations: %v", decisionResult.GetObligations())
}
}
```

Expand All @@ -86,35 +80,54 @@ import io.opentdf.platform.sdk.*;
import java.util.concurrent.ExecutionException;

import io.opentdf.platform.authorization.*;
import io.opentdf.platform.policy.Action;
import io.opentdf.platform.entity.*;
import io.opentdf.platform.policy.*;

import java.util.List;

public class GetDecisions {
public class GetDecision {
public static void main(String[] args) throws ExecutionException, InterruptedException{

String clientId = "opentdf";
String clientSecret = "secret";
String platformEndpoint = "localhost:8080";
String platformEndpoint = "http://localhost:8080";

SDKBuilder builder = new SDKBuilder();
SDK sdk = builder.platformEndpoint(platformEndpoint)
.clientSecret(clientId, clientSecret).useInsecurePlaintextConnection(true)
.build();

GetDecisionsRequest request = GetDecisionsRequest.newBuilder()
.addDecisionRequests(DecisionRequest.newBuilder()
.addEntityChains(EntityChain.newBuilder().setId("ec1").addEntities(Entity.newBuilder().setId("entity-1").setClientId("opentdf")))
.addActions(Action.newBuilder().setStandard(Action.StandardAction.STANDARD_ACTION_DECRYPT))
.addResourceAttributes(ResourceAttribute.newBuilder().setResourceAttributesId("resource-attribute-1")
.addAttributeValueFqns("https://mynamespace.com/attr/test/value/test1"))
).build();

GetDecisionsResponse resp = sdk.getServices().authorization().getDecisions(request).get();

List<DecisionResponse> decisions = resp.getDecisionResponsesList();

System.out.println(DecisionResponse.Decision.forNumber(decisions.get(0).getDecisionValue()));
// Get Decision using v2 API
GetDecisionRequest request = GetDecisionRequest.newBuilder()
.setEntityIdentifier(
EntityIdentifier.newBuilder()
.setEntityChain(
EntityChain.newBuilder()
.addEntities(
Entity.newBuilder()
.setId("entity-1")
.setClientId("opentdf")
)
)
)
.setAction(
Action.newBuilder()
.setName("decrypt")
)
.setResource(
Resource.newBuilder()
.setAttributeValues(
Resource.AttributeValues.newBuilder()
.addFqns("https://opentdf.io/attr/role/value/developer")
)
)
.build();

GetDecisionResponse resp = sdk.getServices().authorization().getDecision(request).get();

Decision decision = resp.getDecision();
System.out.println("Decision: " + decision.getDecision());
if (decision.getDecision() == Decision.DECISION_PERMIT && decision.getObligationsCount() > 0) {
System.out.println("Obligations: " + decision.getObligationsList());
}
}
}
```
Expand All @@ -123,6 +136,55 @@ public class GetDecisions {
<TabItem value="js" label="Javascript">

```javascript
const { AuthzClient } = require('@opentdf/client');

async function main() {
const platformEndpoint = 'http://localhost:8080';
const clientId = 'opentdf';
const clientSecret = 'secret';

// Create a new client
const client = new AuthzClient({
endpoint: platformEndpoint,
auth: {
clientId,
clientSecret
}
});

// Get Decision using v2 API
const request = {
entityIdentifier: {
entityChain: {
entities: [{
id: 'entity-1',
clientId: 'opentdf'
}]
}
},
action: {
name: 'decrypt'
},
resource: {
attributeValues: {
fqns: ['https://opentdf.io/attr/role/value/developer']
}
}
};

try {
const response = await client.getDecision(request);

console.log('Decision:', response.decision.decision);
if (response.decision.decision === 'DECISION_PERMIT' && response.decision.obligations?.length > 0) {
console.log('Obligations:', response.decision.obligations);
}
} catch (error) {
console.error('Error:', error);
}
}

main();
```

</TabItem>
Expand Down
42 changes: 30 additions & 12 deletions code_samples/authorization/get_entitlements.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,13 @@ import (
"log"

"github.com/opentdf/platform/protocol/go/authorization"
"github.com/opentdf/platform/protocol/go/entity"
"github.com/opentdf/platform/sdk"
)

func main() {

platformEndpoint := "http://localhost:9002"
platformEndpoint := "http://localhost:8080"

// Create a new client
client, err := sdk.New(
Expand All @@ -31,14 +32,17 @@ func main() {
log.Fatal(err)
}

// Get Entitlements

// Get Entitlements using v2 API
entitlementReq := &authorization.GetEntitlementsRequest{
Entities: []*authorization.Entity{
{
Id: "entity-1",
EntityType: &authorization.Entity_ClientId{
ClientId: "opentdf",
EntityIdentifier: &authorization.EntityIdentifier{
EntityChain: &entity.EntityChain{
Entities: []*entity.Entity{
{
Id: "entity-1",
EntityType: &entity.Entity_ClientId{
ClientId: "opentdf",
},
},
},
},
},
Expand All @@ -63,6 +67,7 @@ import io.opentdf.platform.sdk.*;
import java.util.concurrent.ExecutionException;

import io.opentdf.platform.authorization.*;
import io.opentdf.platform.entity.*;

import java.util.List;

Expand All @@ -71,22 +76,35 @@ public class GetEntitlements {

String clientId = "opentdf";
String clientSecret = "secret";
String platformEndpoint = "localhost:8080";
String platformEndpoint = "http://localhost:8080";

SDKBuilder builder = new SDKBuilder();
SDK sdk = builder.platformEndpoint(platformEndpoint)
.clientSecret(clientId, clientSecret).useInsecurePlaintextConnection(true)
.build();

// Get Entitlements using v2 API
GetEntitlementsRequest request = GetEntitlementsRequest.newBuilder()
.addEntities(Entity.newBuilder().setId("entity-1").setClientId("opentdf"))
.build();
.setEntityIdentifier(
EntityIdentifier.newBuilder()
.setEntityChain(
EntityChain.newBuilder()
.addEntities(
Entity.newBuilder()
.setId("entity-1")
.setClientId("opentdf")
)
)
)
.build();

GetEntitlementsResponse resp = sdk.getServices().authorization().getEntitlements(request).get();

List<EntityEntitlements> entitlements = resp.getEntitlementsList();

System.out.println(entitlements.get(0).getAttributeValueFqnsList());
for (EntityEntitlements entitlement : entitlements) {
System.out.println("Entitled to: " + entitlement.getActionsPerAttributeValueFqnMap());
}
}
}
```
Expand Down
4 changes: 2 additions & 2 deletions code_samples/policy_code/create_attribute.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ import (

func main() {

platformEndpoint := "http://localhost:9002"
platformEndpoint := "http://localhost:8080"

// Create a new client
client, err := sdk.New(
Expand Down Expand Up @@ -83,7 +83,7 @@ public class CreateAttribute {

String clientId = "opentdf";
String clientSecret = "secret";
String platformEndpoint = "localhost:8080";
String platformEndpoint = "http://localhost:8080";

SDKBuilder builder = new SDKBuilder();
SDK sdk = builder.platformEndpoint(platformEndpoint)
Expand Down
4 changes: 2 additions & 2 deletions code_samples/policy_code/create_namespace.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ import (

func main() {

platformEndpoint := "http://localhost:9002"
platformEndpoint := "http://localhost:8080"

// Create a new client
client, err := sdk.New(
Expand Down Expand Up @@ -59,7 +59,7 @@ public class CreateNamespace {

String clientId = "opentdf";
String clientSecret = "secret";
String platformEndpoint = "localhost:8080";
String platformEndpoint = "http://localhost:8080";

SDKBuilder builder = new SDKBuilder();
SDK sdk = builder.platformEndpoint(platformEndpoint)
Expand Down
4 changes: 2 additions & 2 deletions code_samples/policy_code/create_subject_condition_set.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ import (

func main() {

platformEndpoint := "http://localhost:9002"
platformEndpoint := "http://localhost:8080"

// Create a new client
client, err := sdk.New(
Expand Down Expand Up @@ -88,7 +88,7 @@ public class CreateSubjectConditionSet {

String clientId = "opentdf";
String clientSecret = "secret";
String platformEndpoint = "localhost:8080";
String platformEndpoint = "http://localhost:8080";

SDKBuilder builder = new SDKBuilder();
SDK sdk = builder.platformEndpoint(platformEndpoint)
Expand Down
4 changes: 2 additions & 2 deletions code_samples/policy_code/create_subject_mapping.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ import (

func main() {

platformEndpoint := "http://localhost:9002"
platformEndpoint := "http://localhost:8080"

// Create a new client
client, err := sdk.New(
Expand Down Expand Up @@ -70,7 +70,7 @@ public class CreateSubjectMapping {

String clientId = "opentdf";
String clientSecret = "secret";
String platformEndpoint = "localhost:8080";
String platformEndpoint = "http://localhost:8080";

SDKBuilder builder = new SDKBuilder();
SDK sdk = builder.platformEndpoint(platformEndpoint)
Expand Down
4 changes: 2 additions & 2 deletions code_samples/policy_code/list_attributes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ import (

func main() {

platformEndpoint := "http://localhost:9002"
platformEndpoint := "http://localhost:8080"

// Create a new client
client, err := sdk.New(
Expand Down Expand Up @@ -68,7 +68,7 @@ public class ListAttributes {

String clientId = "opentdf";
String clientSecret = "secret";
String platformEndpoint = "localhost:8080";
String platformEndpoint = "http://localhost:8080";

SDKBuilder builder = new SDKBuilder();
SDK sdk = builder.platformEndpoint(platformEndpoint)
Expand Down
Loading