Beispielrichtlinien

Dieser Abschnitt enthält umfassende Beispiele für Cedar-Autorisierungspolicen für ein Versicherungsmanagementsystem. Diese Beispiele veranschaulichen verschiedene Cedar-Sprachfunktionen und Autorisierungsmuster, die Sie für Ihre eigenen Anwendungen anpassen können.

Verfügbare Tools

Die Insurance API bietet fünf Tools für die Verwaltung von Versicherungspolicen und Ansprüchen:

Autorisierungsrichtlinien

Die folgenden Richtlinien veranschaulichen die verschiedenen Sprachfunktionen und Autorisierungsmuster von Cedar. Jede Richtlinie enthält eine Beschreibung in natürlicher Sprache, den Cedar-Code und eine ausführliche Erklärung.

Richtlinie 1: Multi-action Genehmigung

Diese Richtlinie zeigt, wie mit einer einzigen Grundsatzerklärung Zugriff auf mehrere miteinander verbundene Aktionen gewährt werden kann.

Natürliche Sprache: Erlaubt allen Schulleitern, die Versicherungspolice und den Anspruchsstatus abzurufen.

Richtlinie aus Zedernholz:

permit(
  principal is AgentCore::OAuthUser,
  action in [
    AgentCore::Action::"InsuranceAPI___get_policy",
    AgentCore::Action::"InsuranceAPI___get_claim_status"
  ],
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance"
);

Erläuterung: Diese Richtlinie zeigt Genehmigungen für mehrere Aktionen, bei denen der in Betreiber in Anspruch genommen wird. Anstatt separate Richtlinien für jeden Lesevorgang zu schreiben, gewährt eine einzige Richtlinie Zugriff auf mehrere verwandte Aktionen. Dies ist nützlich, um ähnliche Vorgänge zu gruppieren, für die dieselben Autorisierungsanforderungen gelten.

Richtlinie 2: Autorisierung Scope-based

Diese Richtlinie zeigt, wie OAuth-Bereiche verwendet werden, um den Zugriff auf bestimmte Operationen zu kontrollieren.

Natürliche Sprache: Ermöglicht es Auftraggebern, deren Geltungsbereich „insurance:claim“ enthält, Ansprüche geltend zu machen.

Versicherung aus Zedernholz:

permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"InsuranceAPI___file_claim",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance"
)
when {
  principal.hasTag("scope") &&
  principal.getTag("scope") like "*insurance:claim*"
};

Erklärung: Diese Richtlinie demonstriert die Validierung des OAuth-Bereichs mithilfe von Tags. Die hasTag Methode prüft, ob das Tag existiert, und getTag ruft seinen Wert ab. Der like Operator mit Platzhaltern (*) führt einen Musterabgleich durch und ermöglicht so flexible Bereichsformate wie „insurance:claim“, „insurance:claim:write“ oder „admin insurance:claim“.

Role-based Richtlinie 3: Autorisierung mit sofern

Diese Richtlinie zeigt, wie die unless Klausel verwendet wird, um Ausnahmen von Einschränkungen zu erstellen.

Natürliche Sprache: Schulleiter daran hindern, den Versicherungsschutz zu aktualisieren, es sei denn, der Schulleiter hat die Rolle „leitender Sachbearbeiter“ oder „Manager“ inne.

Richtlinie aus Zedernholz:

forbid(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"InsuranceAPI___update_coverage",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance"
)
unless {
  principal.hasTag("role") &&
  (principal.getTag("role") == "senior-adjuster" || principal.getTag("role") == "manager")
};

Erklärung: Diese Richtlinie veranschaulicht die unless Klausel, die die Bedingungslogik umkehrt. Das Verbot gilt, es sei denn, der Benutzer hat eine der angegebenen Rollen. Dies ist nützlich, um Ausnahmen von Einschränkungen zu erstellen. Die Richtlinie zeigt auch die OR-Logik zur Überprüfung mehrerer akzeptabler Werte.

Richtlinie 4: Gleichheit von Zeichenketten mit OR-Logik

Diese Richtlinie zeigt, wie Eingabeparameter validiert und die OR-Logik für mehrere akzeptable Werte verwendet werden.

Natürliche Sprache: Ermöglicht es den Auftraggebern, Ansprüche geltend zu machen, wenn es sich bei der Schadensart um Gesundheit, Eigentum oder Auto handelt.

Richtlinie für Zedernholz:

permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"InsuranceAPI___file_claim",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance"
)
when {
  context.input has claimType &&
  (context.input.claimType == "health" ||
   context.input.claimType == "property" ||
   context.input.claimType == "auto")
};

Erklärung: Diese Richtlinie demonstriert den Zugriff auf Werkzeugeingabeparameter über die OR-Logik context.input und die Gleichheitsprüfung von Zeichenketten. Der has Operator überprüft zunächst, ob das Feld vorhanden ist, bevor er darauf zugreift. Dadurch werden Fehler vermieden, wenn optionale Felder fehlen.

Richtlinie 5: Überprüfung der Existenz eines Felds

Diese Richtlinie zeigt, wie Geschäftsregeln durchgesetzt werden können, indem optionale Felder vorgeschrieben werden.

Natürliche Sprache: Verhindern Sie die Einreichung von Ansprüchen durch Auftraggeber, sofern keine Beschreibung angegeben wird.

Richtlinie für Zedernholz:

forbid(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"InsuranceAPI___file_claim",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance"
)
unless {
  context.input has description
};

Erklärung: Diese Richtlinie zeigt, wie Pflichtfelder für optionale Parameter durchgesetzt werden. Das Beschreibungsfeld ist im Toolschema optional, aber diese Richtlinie macht es obligatorisch, da Anfragen, die es nicht enthalten, verboten werden. Dies zeigt, wie Richtlinien Geschäftsregeln hinzufügen können, die über die Schemavalidierung hinausgehen.

Richtlinie 6: Username-based Autorisierung

Diese Richtlinie zeigt, wie der Zugriff auf der Grundlage bestimmter Benutzeridentitäten gewährt wird.

Natürliche Sprache: Erlaube Schulleitern mit dem Benutzernamen „Clare“, den Versicherungsschutz zu aktualisieren.

Richtlinie für Zedernholz:

permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"InsuranceAPI___update_coverage",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance"
)
when {
  principal.hasTag("username") &&
  principal.getTag("username") == "Clare"
};

Erklärung: Diese Richtlinie demonstriert die benutzernamenbasierte Autorisierung unter Verwendung eines exakten Zeichenkettenabgleichs. In Kombination mit Richtlinie 3 entsteht dadurch eine zweiteilige Autorisierung: Benutzer müssen den Benutzernamen „insurance-agent“ haben UND die Rolle „senior-adjuster“ oder „manager“ haben, um den Versicherungsschutz zu aktualisieren.

Richtlinie 7: Musterabgleich mit ähnlichem

Diese Richtlinie demonstriert einen flexiblen Musterabgleich unter Verwendung von Platzhaltern für die kategoriebasierte Zugriffskontrolle.

Natürliche Sprache: Ermöglicht es den Schulleitern, die Prämie zu berechnen, wenn die Deckungsart „Auto“ enthält.

Versicherung aus Zedernholz:

permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"InsuranceAPI___calculate_premium",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance"
)
when {
  context.input has coverageType &&
  context.input.coverageType like "*auto*"
};

Erklärung: Diese Richtlinie demonstriert einen flexiblen Musterabgleich mit dem like Operator. Der Platzhalter * steht für alle Zeichen, sodass „auto“, „auto-liability“, „comprehensive auto“ oder „auto-collision“ alle übereinstimmen würden. Dies ist nützlich, wenn Sie einer Kategorie von Werten entsprechen möchten und nicht exakte Zeichenketten.

Richtlinie 8: Kombinierte Bedingungen mit UND

Diese Richtlinie zeigt, wie mehrere Bedingungen kombiniert werden können, um komplexe Autorisierungsregeln zu erstellen.

Natürliche Sprache: Ermöglicht es den Auftraggebern, den Versicherungsschutz zu aktualisieren, wenn die Versicherungsart „Haftung“ oder „Kollision“ lautet und ein neuer Grenzwert festgelegt wurde.

Versicherung aus Zedernholz:

permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"InsuranceAPI___update_coverage",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/insurance"
)
when {
  context.input has coverageType &&
  context.input has newLimit &&
  (context.input.coverageType == "liability" || context.input.coverageType == "collision")
};

Erklärung: Diese Richtlinie demonstriert die Kombination mehrerer Bedingungen mit der UND-Logik. Alle drei Bedingungen müssen erfüllt sein: CoverageType muss existieren, NewLimit muss existieren und CoverageType muss entweder „Haftung“ oder „Kollision“ sein. Dies funktioniert mit Richtlinie 6, um eine mehrstufige Autorisierung zu schaffen: wer kann aktualisieren (Richtlinie 6) und was kann aktualisiert werden (Richtlinie 8).

Die Autorisierungssemantik verstehen

Diese Richtlinien veranschaulichen die wichtige Semantik der Cedar-Autorisierung:

Standardmäßige Ablehnung

Wenn keine Richtlinie eine Aktion ausdrücklich zulässt, wird sie verweigert. Beispielsweise kann ein Benutzer ohne den Geltungsbereich „Versicherung:Anspruch“ keine Ansprüche geltend machen, obwohl dies in keiner Police ausdrücklich verboten ist.

Gewinne verbieten

Wenn eine der verbotenen Richtlinien zutrifft, wird die Anfrage abgelehnt, auch wenn die Genehmigungsrichtlinien ebenfalls übereinstimmen. Richtlinie 5 (Verbot ohne Beschreibung) hat Vorrang vor Richtlinie 2 (Genehmigung mit Geltungsbereich), wenn eine Beschreibung fehlt.

Bündelung von Richtlinien

Für dieselbe Anfrage können mehrere Richtlinien gelten:

Damit eine Anfrage erfolgreich ist, muss sie alle drei Kriterien erfüllen: Versicherungsvertreter sein (Police 6), die Rolle eines leitenden Sachbearbeiters oder Managers innehaben (Police 3) und Haftung oder Kollision aktualisieren (Police 8).

Testszenarien

Die folgenden Szenarien zeigen, wie die Policen in der Praxis zusammenarbeiten:

IAM-based Beispiele für Autorisierungen

Wenn Ihr AgentCore Gateway die AWS_IAM-Authentifizierung anstelle von OAuth verwendet, wird der Principal in den Cedar-Richtlinien wie folgt dargestellt. AgentCore::IamEntity Für Anrufer, die sich über angenommene Rollen authentifizieren, verwendet die Cedar-Entitäts-ID das Formatarn:aws:sts::<account>:assumed-role/<role-name>, wodurch ein stabiler Abgleich und Musterabgleich ermöglicht wird. principal == principal.id

Grundlegende IAM-Entitätsgenehmigung

Diese Richtlinie ermöglicht es jedem IAM-authenticated Anrufer, ein bestimmtes Tool zu verwenden:

permit(
  principal is AgentCore::IamEntity,
  action == AgentCore::Action::"OrderAPI___get_order",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway"
);

Erklärung: Dies ist die einfachste Form der IAM-Richtlinie. Sie ermöglicht jedem über AWS_IAM authentifizierten Anrufer, das Tool get_order aufzurufen. Verwenden Sie diese Option, wenn Sie nur überprüfen müssen, ob Anrufer keine zusätzlichen Einschränkungen haben. IAM-authenticated

Role-based Einschränkung mit exakter Hauptübereinstimmung

Beschränken Sie den Toolzugriff auf Anrufer, die eine bestimmte IAM-Rolle verwenden, indem Sie: principal ==

permit(
  principal == AgentCore::IamEntity::"arn:aws:sts::111122223333:assumed-role/MyServiceRole",
  action == AgentCore::Action::"OrderAPI___process_order",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway"
);

Erklärung: Die Cedar-Entitäts-ID für angenommene Rollen lautet. arn:aws:sts::<account>:assumed-role/<role-name> Dies ermöglicht einen stabilen principal == Abgleich unabhängig vom Sitzungsnamen, der bei der Authentifizierung verwendet wurde.

Role-based Einschränkung mit Mustervergleich

Sie können auch principal.id like für umfassendere Übereinstimmungsmuster Folgendes verwenden:

permit(
  principal is AgentCore::IamEntity,
  action == AgentCore::Action::"OrderAPI___process_order",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway"
)
when {
  principal.id like "arn:aws:sts::111122223333:assumed-role/MyServiceRole"
};

Erklärung: Dadurch wird das gleiche Ergebnis erzielt wie, es wird principal == jedoch eine when Klausel verwendet. Der Musterabgleich ist nützlich, wenn Sie einen umfassenderen Abgleich benötigen, z. B. den Abgleich mit einer beliebigen Rolle in einem Konto (principal.id like "arn:aws:sts::111122223333:assumed-role/*").

Account-based Einschränkung

Beschränken Sie den Zugriff auf das Tool auf Anrufer von bestimmten AWS Konten aus:

permit(
  principal is AgentCore::IamEntity,
  action == AgentCore::Action::"OrderAPI___process_order",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway"
)
when {
  principal.id like "*:111122223333:*"
};

Erklärung: Das Muster *:111122223333: * entspricht jedem ARN, der diese Konto-ID enthält. Dadurch wird der Zugriff nur auf Anrufer vom angegebenen Konto aus beschränkt. AWS

Multi-agent Verband

Wenn mehrere Agenten mit unterschiedlichen IAM-Rollen auf dasselbe Gateway zugreifen, erstellen Sie separate Richtlinien, um zu steuern, welche Tools jeder Agent verwenden kann:

// Agent A can only read orders
permit(
  principal == AgentCore::IamEntity::"arn:aws:sts::111122223333:assumed-role/AgentA-Role",
  action == AgentCore::Action::"OrderAPI___get_order",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway"
);

// Agent B can read and process orders
permit(
  principal == AgentCore::IamEntity::"arn:aws:sts::111122223333:assumed-role/AgentB-Role",
  action in [
    AgentCore::Action::"OrderAPI___get_order",
    AgentCore::Action::"OrderAPI___process_order"
  ],
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway"
);

Erklärung: Dieses Muster ist für Architekturen mit mehreren Agenten nützlich, bei denen verschiedene Agenten unterschiedliche IAM-Rollen haben und unterschiedliche Ebenen des Toolzugriffs haben sollten. Jede Richtlinie verwendet die principal == Entitäts-ID der jeweiligen Rolle. Die tools/list Antwort für jeden Agenten umfasst nur die Tools, zu deren Verwendung er berechtigt ist.

IAM mit Eingabevalidierung

Kombinieren Sie den IAM-Prinzipalabgleich mit der Validierung der Tool-Eingaben:

permit(
  principal == AgentCore::IamEntity::"arn:aws:sts::111122223333:assumed-role/RefundProcessorRole",
  action == AgentCore::Action::"RefundAPI___process_refund",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/refund-gateway"
)
when {
  context.input has amount &&
  context.input.amount < 1000
};

Erklärung: Diese Richtlinie kombiniert den exakten Prinzipalabgleich mit der Eingabevalidierung. Rückerstattungen können nur RefundProcessorRole von Anrufern bearbeitet werden, die von dem angegebenen Konto ausgehen, und nur, wenn der Rückerstattungsbetrag unter 1000$ liegt.

Bestimmte Konten verbieten

Sperren Sie Anrufern von bestimmten AWS Konten den Zugriff auf vertrauliche Tools:

forbid(
  principal is AgentCore::IamEntity,
  action == AgentCore::Action::"AdminAPI___delete_resource",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/admin-gateway"
)
when {
  principal.id like "*:444455556666:*"
};

Erklärung: Diese Verbotsrichtlinie verhindert, dass alle Anrufer über ein Drittanbieter-Konto (444455556666) administrative Löschungen vornehmen. Aufgrund der Semantik, die Gewinne verbieten, hat dies Vorrang vor allen Genehmigungsrichtlinien.

Verbieten Sie bestimmte Rollen bei sensiblen Vorgängen

Sperren Sie Anrufer, die nur Leserollen verwenden, an der Ausführung von Schreibvorgängen:

forbid(
  principal == AgentCore::IamEntity::"arn:aws:sts::111122223333:assumed-role/ReadOnlyAgentRole",
  action in [
    AgentCore::Action::"OrderAPI___process_order",
    AgentCore::Action::"OrderAPI___cancel_order"
  ],
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/order-gateway"
);

Erklärung: Diese Verbotsrichtlinie verhindert, dass Anrufer, die die verwenden, Schreibvorgänge ausführen, unabhängig ReadOnlyAgentRole von Genehmigungsrichtlinien, die sie andernfalls zulassen könnten.