io.github.cdklabs.cdk.verified.permissions.package-info Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of cdk-verified-permissions Show documentation
Show all versions of cdk-verified-permissions Show documentation
L2 AWS CDK Constructs for Amazon Verified Permissions
/**
* Amazon Verified Permissions L2 CDK Construct
*
* This repo contains the implementation of an L2 CDK Construct for Amazon Verified Permissions
*
*
Project Stability
*
* This construct is still versioned with alpha/v0 major version and we could introduce breaking changes even without a major version bump. Our goal is to keep the API stable & backwards compatible as much as possible but we currently cannot guarantee that. Once we'll publish v1.0.0 the breaking changes will be introduced via major version bumps.
*
*
Getting Started
*
*
Policy Store
*
* Define a Policy Store with defaults (No description, No schema & Validation Settings Mode set to OFF):
*
*
* PolicyStore test = new PolicyStore(scope, "PolicyStore");
*
*
* Define a Policy Store without Schema definition (Validation Settings Mode must be set to OFF):
*
*
* Map<String, ValidationSettingsMode> validationSettingsOff = Map.of(
* "mode", ValidationSettingsMode.OFF);
* PolicyStore test = PolicyStore.Builder.create(scope, "PolicyStore")
* .validationSettings(validationSettingsOff)
* .build();
*
*
* Define a Policy Store with Description and Schema definition (a STRICT Validation Settings Mode is strongly suggested for Policy Stores with schemas):
*
*
* Map<String, ValidationSettingsMode> validationSettingsStrict = Map.of(
* "mode", ValidationSettingsMode.STRICT);
* Map<String, Map<String, Map<String, Map<String, Object>>>> cedarJsonSchema = Map.of(
* "PhotoApp", Map.of(
* "entityTypes", Map.of(
* "User", Map.of(),
* "Photo", Map.of()),
* "actions", Map.of(
* "viewPhoto", Map.of(
* "appliesTo", Map.of(
* "principalTypes", List.of("User"),
* "resourceTypes", List.of("Photo"))))));
* Map<String, String> cedarSchema = Map.of(
* "cedarJson", JSON.stringify(cedarJsonSchema));
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .schema(cedarSchema)
* .validationSettings(validationSettingsStrict)
* .description("PolicyStore description")
* .build();
*
*
*
Schemas
*
* If you want to have type safety when defining a schema, you can accomplish this only in typescript. Simply use the Schema type exported by the @cedar-policy/cedar-wasm.
*
* You can also generate simple schemas using the static functions schemaFromOpenApiSpec or schemaFromRestApi in the PolicyStore construct. This functionality replicates what you can find in the AWS Verified Permissions console.
*
* Generate a schema from an OpenAPI spec:
*
*
* Map<String, ValidationSettingsMode> validationSettingsStrict = Map.of(
* "mode", ValidationSettingsMode.STRICT);
* Map<String, Map<String, Object>> cedarJsonSchema = PolicyStore.schemaFromOpenApiSpec("path/to/swaggerfile.json", "UserGroup");
* Map<String, String> cedarSchema = Map.of(
* "cedarJson", JSON.stringify(cedarJsonSchema));
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .schema(cedarSchema)
* .validationSettings(validationSettingsStrict)
* .description("Policy store with schema generated from API Gateway")
* .build();
*
*
* Generate a schema from a RestApi construct:
*
*
* Map<String, ValidationSettingsMode> validationSettingsStrict = Map.of(
* "mode", ValidationSettingsMode.STRICT);
* Map<String, Map<String, Object>> cedarJsonSchema = PolicyStore.schemaFromRestApi(
* new RestApi(scope, "RestApi"), "UserGroup");
* Map<String, String> cedarSchema = Map.of(
* "cedarJson", JSON.stringify(cedarJsonSchema));
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .schema(cedarSchema)
* .validationSettings(validationSettingsStrict)
* .description("Policy store with schema generated from RestApi construct")
* .build();
*
*
*
Identity Source
*
* Define Identity Source with Cognito Configuration and required properties:
*
*
* UserPool userPool = new UserPool(scope, "UserPool"); // Creating a new Cognito UserPool
* Map<String, ValidationSettingsMode> validationSettingsStrict = Map.of(
* "mode", ValidationSettingsMode.STRICT);
* Map<String, Map<String, Map<String, Map<String, Object>>>> cedarJsonSchema = Map.of(
* "PhotoApp", Map.of(
* "entityTypes", Map.of(
* "User", Map.of(),
* "Photo", Map.of()),
* "actions", Map.of(
* "viewPhoto", Map.of(
* "appliesTo", Map.of(
* "principalTypes", List.of("User"),
* "resourceTypes", List.of("Photo"))))));
* Map<String, String> cedarSchema = Map.of(
* "cedarJson", JSON.stringify(cedarJsonSchema));
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .schema(cedarSchema)
* .validationSettings(validationSettingsStrict)
* .build();
* IdentitySource.Builder.create(scope, "IdentitySource")
* .configuration(IdentitySourceConfiguration.builder()
* .cognitoUserPoolConfiguration(CognitoUserPoolConfiguration.builder()
* .userPool(userPool)
* .build())
* .build())
* .policyStore(policyStore)
* .build();
*
*
* Define Identity Source with Cognito Configuration and all properties:
*
*
* Map<String, ValidationSettingsMode> validationSettingsStrict = Map.of(
* "mode", ValidationSettingsMode.STRICT);
* Map<String, Map<String, Map<String, Map<String, Object>>>> cedarJsonSchema = Map.of(
* "PhotoApp", Map.of(
* "entityTypes", Map.of(
* "User", Map.of(),
* "Photo", Map.of()),
* "actions", Map.of(
* "viewPhoto", Map.of(
* "appliesTo", Map.of(
* "principalTypes", List.of("User"),
* "resourceTypes", List.of("Photo"))))));
* Map<String, String> cedarSchema = Map.of(
* "cedarJson", JSON.stringify(cedarJsonSchema));
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .schema(cedarSchema)
* .validationSettings(validationSettingsStrict)
* .build();
* String cognitoGroupEntityType = "test";
* UserPool userPool = new UserPool(scope, "UserPool"); // Creating a new Cognito UserPool
* // Creating a new Cognito UserPool
* IdentitySource.Builder.create(scope, "IdentitySource")
* .configuration(IdentitySourceConfiguration.builder()
* .cognitoUserPoolConfiguration(CognitoUserPoolConfiguration.builder()
* .clientIds(List.of("&ExampleCogClientId;"))
* .userPool(userPool)
* .groupConfiguration(CognitoGroupConfiguration.builder()
* .groupEntityType(cognitoGroupEntityType)
* .build())
* .build())
* .build())
* .policyStore(policyStore)
* .principalEntityType("PETEXAMPLEabcdefg111111")
* .build();
*
*
* Define Identity Source with OIDC Configuration and Access Token selection config:
*
*
* Map<String, ValidationSettingsMode> validationSettingsStrict = Map.of(
* "mode", ValidationSettingsMode.STRICT);
* Map<String, Map<String, Map<String, Map<String, Object>>>> cedarJsonSchema = Map.of(
* "PhotoApp", Map.of(
* "entityTypes", Map.of(
* "User", Map.of(),
* "Photo", Map.of()),
* "actions", Map.of(
* "viewPhoto", Map.of(
* "appliesTo", Map.of(
* "principalTypes", List.of("User"),
* "resourceTypes", List.of("Photo"))))));
* Map<String, String> cedarSchema = Map.of(
* "cedarJson", JSON.stringify(cedarJsonSchema));
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .schema(cedarSchema)
* .validationSettings(validationSettingsStrict)
* .build();
* String issuer = "https://iamanidp.com";
* String principalIdClaim = "sub";
* String entityIdPrefix = "prefix";
* String groupClaim = "group";
* String groupEntityType = "GroupType";
* IdentitySource.Builder.create(scope, "IdentitySource")
* .configuration(IdentitySourceConfiguration.builder()
* .openIdConnectConfiguration(OpenIdConnectConfiguration.builder()
* .issuer(issuer)
* .entityIdPrefix(entityIdPrefix)
* .groupConfiguration(OpenIdConnectGroupConfiguration.builder()
* .groupClaim(groupClaim)
* .groupEntityType(groupEntityType)
* .build())
* .accessTokenOnly(OpenIdConnectAccessTokenConfiguration.builder()
* .audiences(List.of("testAudience"))
* .principalIdClaim(principalIdClaim)
* .build())
* .build())
* .build())
* .policyStore(policyStore)
* .principalEntityType("TestType")
* .build();
*
*
* Define Identity Source with OIDC Configuration and Identity Token selection config:
*
*
* Map<String, ValidationSettingsMode> validationSettingsStrict = Map.of(
* "mode", ValidationSettingsMode.STRICT);
* Map<String, Map<String, Map<String, Map<String, Object>>>> cedarJsonSchema = Map.of(
* "PhotoApp", Map.of(
* "entityTypes", Map.of(
* "User", Map.of(),
* "Photo", Map.of()),
* "actions", Map.of(
* "viewPhoto", Map.of(
* "appliesTo", Map.of(
* "principalTypes", List.of("User"),
* "resourceTypes", List.of("Photo"))))));
* Map<String, String> cedarSchema = Map.of(
* "cedarJson", JSON.stringify(cedarJsonSchema));
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .schema(cedarSchema)
* .validationSettings(validationSettingsStrict)
* .build();
* String issuer = "https://iamanidp.com";
* String entityIdPrefix = "prefix";
* String groupClaim = "group";
* String groupEntityType = "UserGroup";
* String principalIdClaim = "sub";
* IdentitySource.Builder.create(scope, "IdentitySource")
* .configuration(IdentitySourceConfiguration.builder()
* .openIdConnectConfiguration(OpenIdConnectConfiguration.builder()
* .issuer(issuer)
* .entityIdPrefix(entityIdPrefix)
* .groupConfiguration(OpenIdConnectGroupConfiguration.builder()
* .groupClaim(groupClaim)
* .groupEntityType(groupEntityType)
* .build())
* .identityTokenOnly(OpenIdConnectIdentityTokenConfiguration.builder()
* .clientIds(List.of())
* .principalIdClaim(principalIdClaim)
* .build())
* .build())
* .build())
* .policyStore(policyStore)
* .build();
*
*
*
Policy
*
* Load all the .cedar files in a given folder and define Policy objects for each of them. All policies will be associated with the same policy store.
*
*
* Map<String, ValidationSettingsMode> validationSettingsStrict = Map.of(
* "mode", ValidationSettingsMode.STRICT);
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .validationSettings(validationSettingsStrict)
* .build();
* policyStore.addPoliciesFromPath("/path/to/my-policies");
*
*
* Define a Policy and add it to a specific Policy Store:
*
*
* String statement = "permit(\n principal,\n action in [MyFirstApp::Action::\"Read\"],\n resource\n) when {\n true\n};";
*
* String description = "Test policy assigned to the test store";
* Map<String, ValidationSettingsMode> validationSettingsOff = Map.of(
* "mode", ValidationSettingsMode.OFF);
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .validationSettings(validationSettingsOff)
* .build();
*
* // Create a policy and add it to the policy store
* Policy policy = Policy.Builder.create(scope, "MyTestPolicy")
* .definition(PolicyDefinitionProperty.builder()
* .static(StaticPolicyDefinitionProperty.builder()
* .statement(statement)
* .description(description)
* .build())
* .build())
* .policyStore(policyStore)
* .build();
*
*
* Define a policy with a template linked definition:
*
*
* Map<String, ValidationSettingsMode> validationSettingsOff = Map.of(
* "mode", ValidationSettingsMode.OFF);
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .validationSettings(validationSettingsOff)
* .build();
* String policyTemplateStatement = "\npermit (\n principal == ?principal,\n action in [TinyTodo::Action::\"ReadList\", TinyTodo::Action::\"ListTasks\"],\n resource == ?resource\n);";
* PolicyTemplate template = PolicyTemplate.Builder.create(scope, "PolicyTemplate")
* .statement(policyTemplateStatement)
* .policyStore(policyStore)
* .build();
*
* Policy policy = Policy.Builder.create(scope, "MyTestPolicy")
* .definition(PolicyDefinitionProperty.builder()
* .templateLinked(TemplateLinkedPolicyDefinitionProperty.builder()
* .policyTemplate(template)
* .principal(EntityIdentifierProperty.builder()
* .entityId("exampleId")
* .entityType("exampleType")
* .build())
* .resource(EntityIdentifierProperty.builder()
* .entityId("exampleId")
* .entityType("exampleType")
* .build())
* .build())
* .build())
* .policyStore(policyStore)
* .build();
*
*
* Define a Policy with a statement from file:
* PLEASE NOTE: You can specify the description of the policy directly inside the Policy file, using the annotation @cdkDescription
*
*
* String description = "Test policy assigned to the test store";
* Map<String, ValidationSettingsMode> validationSettingsOff = Map.of(
* "mode", ValidationSettingsMode.OFF);
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .validationSettings(validationSettingsOff)
* .build();
*
* // Create a policy and add it to the policy store
* Map<String, Object> policyFromFileProps = Map.of(
* "policyStore", policyStore,
* "path", "/path/to/policy-statement.cedar",
* "description", "the policy description");
* Policy policy = Policy.fromFile(scope, "MyTestPolicy", policyFromFileProps);
*
*
*
Policy Template
*
* Define a Policy Template referring to a Cedar Statement in local file:
*
*
* Map<String, ValidationSettingsMode> validationSettingsOff = Map.of(
* "mode", ValidationSettingsMode.OFF);
* PolicyStore policyStore = PolicyStore.Builder.create(scope, "PolicyStore")
* .validationSettings(validationSettingsOff)
* .build();
* Map<String, Object> templateFromFileProps = Map.of(
* "policyStore", policyStore,
* "path", "/path/to/template-statement.cedar",
* "description", "Allows sharing photos in full access mode");
* PolicyTemplate template = PolicyTemplate.fromFile(scope, "PolicyTemplate", templateFromFileProps);
*
*
*
Notes
*
*
* - This project is following the AWS CDK Official Design Guidelines (see https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) and the AWS CDK New Constructs Creation Guide (see here https://github.com/aws/aws-cdk/blob/main/docs/NEW_CONSTRUCTS_GUIDE.md).
* - Feedback is a gift: if you find something wrong or you've ideas to improve please open an issue or a pull request
*
*/
@software.amazon.jsii.Stability(software.amazon.jsii.Stability.Level.Experimental)
package io.github.cdklabs.cdk.verified.permissions;