Amazon Cloud Directory

(1)

Amazon Cloud Directory

Developer Guide

(2)

Amazon Cloud Directory: Developer Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What Is Amazon Cloud Directory?

Amazon Cloud Directory is a highly available multi-tenant directory-based store in AWS. These directories scale automatically to hundreds of millions of objects as needed for applications. This lets operations staﬀ focus on developing and deploying applications that drive the business, not managing directory infrastructure. Unlike traditional directory systems, Cloud Directory does not limit organizing directory objects in a single ﬁxed hierarchy.

With Cloud Directory, you can organize directory objects into multiple hierarchies to support many organizational pivots and relationships across directory information. For example, a directory of users may provide a hierarchical view based on reporting structure, location, and project aﬃliation. Similarly, a directory of devices may have multiple hierarchical views based on its manufacturer, current owner, and physical location.

At its core, Cloud Directory is a specialized graph-based directory store that provides a foundational building block for developers. With Cloud Directory, developers can do the following:

• Create directory-based applications easily and without having to worry about deployment, global scale, availability, and performance

• Build applications that provide user and group management, permissions or policy management, device registry, customer management, address books, and application or product catalogs

• Deﬁne new directory objects or extend existing types to meet their application needs, reducing the code they need to write

• Reduce the complexity of layering applications on top of Cloud Directory

• Manage the evolution of schema information over time, ensuring future compatibility for consumers

Cloud Directory includes a set of API operations to access various objects and policies stored in your Cloud Directory-based directories. For a list of available operations, see Amazon Cloud Directory API Actions. For a list of operations and the permissions required to perform each API action, see Amazon Cloud Directory API Permissions: Actions, Resources, and Conditions Reference (p. 56).

For a list of supported Cloud Directory regions, see the AWS Regions and Endpoints documentation. For additional resources, see Cloud Directory Resources (p. 70).

What Cloud Directory Is Not

Cloud Directory is not a directory service for IT Administrators who want to manage or migrate their directory infrastructure.

(6)

Create a Schema

Getting Started

In this getting started exercise, you create a schema. You then choose to create a directory from that same schema or from any of the sample schemas that are available in the AWS Directory Service console. Although not required, we recommend that you review Understanding Key Cloud Directory Concepts (p. 6) before you begin using the console so that you are familiar with the core features and terminology.

Topics

• Create a Schema (p. 2)

• Create an Amazon Cloud Directory (p. 3)

• Using Cloud Directory Interface VPC Endpoints (p. 3)

Create a Schema

Amazon Cloud Directory supports uploading of a compliant JSON ﬁle for schema creation. To create a new schema, you can either create your own JSON ﬁle from scratch or download one of the existing schemas listed in the console. Then upload it as a custom schema. For more information, see Custom Schemas (p. 19).

You can also create, delete, download, list, publish, update and upgrade schemas using the Cloud Directory APIs. For more information about schema API operations, see the Amazon Cloud Directory API Reference Guide.

Choose either of the procedures below, depending on your preferred method.

To create a custom schema

1. In the AWS Directory Service console navigation pane, under Cloud Directory, choose Schemas.

2. Create a JSON file with all of your new schema definitions. For more information about how to format a JSON file, see JSON Schema Format (p. 23).

3. In the console, choose Upload new schema.

4. In the Upload new schema dialog, type a name for the schema.

5. Select Choose ﬁle, select the new JSON ﬁle that you just created, and then choose Open.

6. Choose Upload. This adds a new schema to your schema library and places it in the Development state. For more information about schema states, see Schema Lifecycle (p. 10).

To create a custom schema based on an existing one in the console

1. In the AWS Directory Service console navigation pane, under Cloud Directory, choose Schemas.

2. In the table listing the schemas, select the option near the schema you want to copy.

3. Choose Actions.

4. Choose Download schema.

5. Rename the JSON file, edit it as needed, and then save the file. For more information about how to format a JSON file, see JSON Schema Format (p. 23).

6. In the console, choose Upload new schema, select the JSON ﬁle that you just edited, and then choose Open.

This adds a new schema to your schema library and places it in the Development state. For more information about schema states, see Schema Lifecycle (p. 10).

(7)

Create a Directory

Create an Amazon Cloud Directory

Before you can create a directory in Amazon Cloud Directory, AWS Directory Service requires that you ﬁrst apply a schema to it. A directory cannot be created without a schema and typically has one schema applied to it. However, you use Cloud Directory API operations to apply additional schemas to a directory. For more information, see ApplySchema in the Amazon Cloud Directory API Reference Guide.

To create a Cloud Directory

1. In the AWS Directory Service console navigation pane, under Cloud Directory, choose Directories.

2. Choose Set up Cloud Directory.

3. Under Choose a schema to apply to your new directory, type the friendly name of your directory, such as User Repository, and then choose one of the following options:

• Managed schema

• Sample schema

• Custom schema

Sample schemas and custom schemas are placed in the Development state, by default. For more information about schema states, see Schema Lifecycle (p. 10). Before a schema can be applied to a directory, it must be converted into the Published state. To successfully publish a sample schema using the console, you must have permissions to the following actions:

• clouddirectory:Get*

• clouddirectory:List*

• clouddirectory:CreateSchema

• clouddirectory:CreateDirectory

• clouddirectory:PutSchemaFromJson

• clouddirectory:PublishSchema

• clouddirectory:DeleteSchema

Since sample schemas are read-only templates provided by AWS, they cannot be published directly.

Instead, when you choose to create a directory based on a sample schema, the console creates a temporary copy of the sample schema you selected and places it in the Development state. It then creates a copy of that development schema and places it in the Published state. Once published, the development schema is deleted, which is why the DeleteSchema action is necessary when publishing a sample schema.

4. Choose Next.

5. Review the directory information and make any necessary changes. When the information is correct, choose Create.

Using Cloud Directory Interface VPC Endpoints

If you use Amazon Virtual Private Cloud (Amazon VPC) to host your AWS resources, you can establish a private connection between your VPC and Cloud Directory. You can use this connection to enable Cloud Directory to communicate with your resources on your VPC without going through the public internet.

Amazon VPC is an AWS service that you can use to launch AWS resources in a virtual network that you deﬁne. With a VPC, you have control over your network settings, such as the IP address range, subnets, route tables, and network gateways. To connect your VPC to Cloud Directory, you deﬁne an interface VPC

(8)

Availability

endpoint for Cloud Directory. The endpoint provides reliable, scalable connectivity to Cloud Directory without requiring an internet gateway, network address translation (NAT) instance, or VPN connection.

For more information, see What Is Amazon VPC? in the Amazon VPC User Guide.

Interface VPC endpoints are powered by AWS PrivateLink, an AWS technology that enables private communication between AWS services using an elastic network interface with private IP addresses. For more information, see AWS PrivateLink for AWS Services.

The following steps are for users of Amazon VPC. For more information, see Getting Started with Amazon VPC in the Amazon VPC User Guide.

Availability

Cloud Directory currently supports VPC endpoints in the following Regions:

• US East (Ohio)

• US East (N. Virginia)

• US West (Oregon)

• Asia Paciﬁc (Singapore)

• Asia Paciﬁc (Sydney)

• Canada (Central)

• Europe (Frankfurt)

• Europe (Ireland)

• Europe (London)

• AWS GovCloud (US-West)

Create a VPC for Cloud Directory

To start using Cloud Directory with your VPC, use the Amazon VPC console to create an interface VPC endpoint for Cloud Directory. For more information, see Creating an Interface Endpoint.

• For Service Category, choose AWS services.

• For Service Name, choose com.amazonaws.region.clouddirectory. This creates a VPC endpoint for Cloud Directory operations.

For general information, see What is Amazon VPC? in the Amazon VPC User Guide.

Control Access to Your Cloud Directory VPC Endpoint

A VPC endpoint policy is an IAM resource policy that you attach to an endpoint when you create or modify the endpoint. If you don't attach a policy when you create an endpoint, we attach a default policy for you that allows full access to the service. An endpoint policy doesn't override or replace IAM user policies or service-speciﬁc policies. It's a separate policy for controlling access from the endpoint to the speciﬁed service.

Endpoint policies must be written in JSON format. For more information, see Controlling Access to Services with VPC Endpoints in the Amazon VPC User Guide.

The following is an example of an endpoint policy for Cloud Directory. This policy enables users connecting to Cloud Directory through the VPC to list directories and prevents them from performing other Cloud Directory actions.

{

(9)

Create a VPC for Cloud Directory

"Statement": [ {

"Sid": "ReadOnly", "Principal": "*", "Action": [

"clouddirectory:ListDirectories"

],

"Effect": "Allow", "Resource": "*"

} ] }

To modify the VPC endpoint policy for Cloud Directory

1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

2. In the navigation pane, choose Endpoints.

3. If you have not already created the endpoint for Cloud Directory, choose Create Endpoint. Then select com.amazonaws.region.clouddirectory and choose Create endpoint.

4. Select the com.amazonaws.region.clouddirectory endpoint and choose the Policy tab in the lower half of the screen.

5. Choose Edit Policy and make the changes to the policy.

For more information, see Controlling Access to Services with VPC Endpoints in the Amazon VPC User Guide.

(10)

Schema

Understanding Key Cloud Directory Concepts

Amazon Cloud Directory is a directory-based data store that can create various types of objects in a schema-oriented fashion.

Topics

• Schema (p. 6)

• Directory (p. 6)

• Directory Structure (p. 8)

Schema

A schema is a collection of facets that deﬁne what objects can be created in a directory and how they are organized. A schema also enforces data integrity and interoperability. A single schema can be applied to more than one directory at a time. For more information, see Schemas (p. 10).

Facets

A facet is a collection of attributes, constraints, and links defined within a schema. Combined together, facets define the objects in a directory. For example, Person and Device can be facets to define corporate employees with association of multiple devices. For more information, see Facets (p. 12).

Managed Schemas

A schema provided to make it easier to quickly develop and maintain your applications. For more information, see Managed Schema (p. 13).

Sample Schemas

The set of sample schemas provided by default in the AWS Directory Service console. For example, Person, Organization, and Device are all sample schemas. For more information, see Sample Schemas (p. 15).

Custom Schemas

One or more schemas deﬁned by a user that can be uploaded from the Schemas section or during the Cloud Directory creation process of the AWS Directory Service console, or created by API calls.

Objects

Objects are a structured data entity in a directory. An object in a directory is intended to capture metadata (or attributes) about a physical or logical entity usually for the purpose of information discovery and enforcing policies. For example users, devices, applications, AWS accounts, EC2 instances and Amazon S3 buckets can all be represented as diﬀerent types of objects in a directory.

An object’s structure and type information is expressed as a collection of facets. You can use Path or ObjectIdentifier to access objects. Objects can also have attributes, which are a user-deﬁned unit of metadata. For example, the user object can have an attribute called email-address. Attributes are always associated with an object.

Policies

Policies are a specialized type of object that are useful for storing permissions or capabilities. Policies oﬀer the LookupPolicy API action. The lookup policy action takes a reference to any object as its starting input. It then walks up the directory all the way to the root. The action collects any policy objects that it encounters on each path to the root. Cloud Directory does not interpret any of these policies in any way. Instead, Cloud Directory users interpret policies using their own specialized business logic.

For example, imagine a system that stores employee information. Employees are grouped together by job function. We want to establish diﬀerent permissions for members of the Human Resources Group and the Accounting group. Members of the Human Resources group will have access to payroll information and the Accounting group will have access to ledger information. To establish these permissions, we attach policy objects to each of these groups. When it is time to evaluate a user’s permissions, we can use the LookupPolicy API action on that user’s object. The LookupPolicy API action walks the tree from the speciﬁed policy's object up to the root. It stops at each node and checks for any attached policies and returns those.

Policy Attachments

Policies can be attached to other objects in two ways: normal parent-child attachments and special policy attachments. Using normal parent-child attachments, a policy can be attached to a parent node. This is often useful to provide an easy mechanism to locate policies within your data directory.

Policies cannot have children. Policies attached via parent-child attachments will not be returned during LookupPolicy API calls.

Policy objects can also be attached to other objects via policy attachments. You can manage these policy attachments using the AttachPolicy and DetachPolicy API actions. Policy attachments allow policy nodes to be located when you use the LookupPolicy API.

Policy Schema Speciﬁcation

In order to start using policies, you must ﬁrst add a facet to your schema that support creating policies.

To accomplish this, create a facet setting the objectType of the facet to POLICY. Creating objects using a facet with the type POLICY ensures that the object has policy capabilities.

Policy facets inherit two attributes in addition to any attributes you add to the deﬁnition:

(12)

Directory Structure

• policy_type (String, Required) – This is an identifier you can provide to distinguish between different policy uses. If your policies logically fall into clear categories, we encourage setting the policy type attribute appropriately. The LookupPolicy API returns the policy type of attached policies (see PolicyAttachment). This allows easy filtering of the specific policy type that you are looking for. It also allows you to use policy_type to decide how the document should be processed or interpreted.

• policy_document (Binary, Required) – You can store application speciﬁc data in this attribute, such as permission grants associated with the policy. You can also store application-related data in normal attributes on your facet, if you prefer.

Policy API Overview

A variety of specialized API actions are available for working with policies. For a list of available operations, see Amazon Cloud Directory Actions.

To create a policy object, use the CreateObject API action with an appropriate facet:

• To attach or detach a policy from an object, use the actions AttachPolicy and DetachPolicy respectively.

• To ﬁnd policies that are attached to objects up the tree, use the LookupPolicy API action.

• To list the policies that are attached to a particular object, use the ListObjectPolicies API action.

For a list of operations and the permissions required to perform each API action, see Amazon Cloud Directory API Permissions: Actions, Resources, and Conditions Reference (p. 56).

Directory Structure

Data in a directory is structured hierarchically in a tree pattern consisting of nodes, leaf nodes, and links between the nodes, as shown in the following illustration. This is useful in application development to model, store, and quickly traverse hierarchical data.

Root Node

The root is the top node in a directory that is used to organize the parent and child nodes in the hierarchy. This is similar to how folders in a ﬁle system can contain subfolders and ﬁles.

Node

A node represents an object that can have child objects. For example, a node can logically represent a group of managers whereby various user objects are the children, or leaf nodes. A node object can only have one parent.

(13)

Leaf Node

A leaf node represents an object with no children that may or may not be directly connected to a parent node. For example, a user or device object. A leaf node object can have multiple parents. While leaf node objects are not required to be connected to a parent node, it is strongly recommended that you do so, since without a path from the root, the object can only be accessed by it’s NodeId. If you misplace the id of such an Object, you will have no way to locate it again.

Node Link

The connection between one node and another. Cloud Directory supports a variety of link types between nodes, including parent-child links, policy links, and index attribute links.

(14)

Schema Lifecycle

Schemas

With Amazon Cloud Directory, schemas define what types of objects can be created within a directory (users, devices, and organizations), enforce validation of data for each object class, and handle changes to the schema over time. More specifically, a schema defines the following:

• One or more types of facets that may be mapped to objects within a directory (such as Person, Organization_Person)

• Attributes that may be mapped to objects within a directory (such as Name, Description). Attributes can be required or made optional on various types of facets, and are deﬁned within the context of a facet.

• Constraints that may be enforced on object attributes (such as Required, Integer, String)

When a schema has been applied to a directory, all data within that directory must then conform to that applied schema. In this way, the schema deﬁnition is essentially a blueprint that can be used to construct multiple directories with applied schemas. Once built, those applied schemas may vary from the original blueprint, each in diﬀerent ways.

Applied schemas can later be updated using versioning and then reapplied to all the directories that use it. For more information, see In-Place Schema Upgrade (p. 12).

Cloud Directory provides API operations to create, read, update, and delete schemas. This allows the contents of the schema to be easily consumed by programmatic agents. Such agents access the directory to discover the full set of facets, attributes, and constraints that apply to data within the directory. For more information about the schema APIs, see the Amazon Cloud Directory API Reference Guide.

Cloud Directory supports uploading a compliant JSON ﬁle for schema creation. You can also create and manage schemas using the AWS Directory Services console. For more information, see Create an Amazon Cloud Directory (p. 3).

Topics

• Schema Lifecycle (p. 10)

• Facets (p. 12)

• In-Place Schema Upgrade (p. 12)

• Managed Schema (p. 13)

• Sample Schemas (p. 15)

• Custom Schemas (p. 19)

• Attribute References (p. 19)

• Attribute Rules (p. 22)

• Format Speciﬁcation (p. 23)

Schema Lifecycle

Cloud Directory offers a schema lifecycle to help with the development of schemas. This lifecycle consists of three states: Development, Published, and Applied. These states are designed to facilitate construction and distribution of schemas. Each of these states has different features aiding this effort.

The following diagram depicts possible transitions and verbiage. All schema transitions are copy-on- write. For example, publishing a development schema does not alter or remove the development schema.

(15)

Development State

You can delete a schema when it is in either the Development or Published state. Deleting a schema cannot be undone nor can it be restored once it has been deleted.

Schemas in Development, Published and Applied states have ARNs that represent them. These ARNs are used in API operations to describe the schema that the API operates on. It is easy to discern the state of a schema by looking at a schema ARN.

• Development: arn:aws:clouddirectory:us-east-1:1234567890:schema/

development/SchemaName

• Published: arn:aws:clouddirectory:us-east-1:1234567890:schema/

published/SchemaName/Version

• Applied: arn:aws:clouddirectory:us-east-1:1234567890:directory/directoryid/

schema/SchemaName/Version

Development State

Schemas are initially created in the development state. Schemas in this state are fully mutable. You can freely add or remove facets and attributes. The majority of schema design occurs in this state. Schemas in this state have a name but no version.

Published State

The published schema state stores schemas that are ready to be applied to data directories. Schemas are published from the development state into the published state. You cannot change schemas in the published state. You can apply published schemas to any number of data directories.

Published and applied schemas must have a version associated with them. For more information about versions, see Schema Versioning (p. 12).

Applied State

A published schema can be applied to data directories. A schema that has been applied to a data directory is said to be applied. Once you apply a schema to a data directory, you can use the schema's facets when creating objects. You can apply multiple schemas to the same data directory. Only the following changes are permitted on an applied schema.

• Add a facet to an applied schema

• Add a non-required attribute to an applied schema

(16)

Facets

Facets are the most basic abstraction within a schema. They represent a set of attributes that can be associated with an object in the directory and are similar in concept to LDAP object classes. Each directory object may have up to a certain number of facets associated with it. For more information, see Amazon Cloud Directory Limits (p. 68).

Each facet maintains its own independent set of attributes. Each facet consists of fundamental

metadata, such as the facet name, version information, and behaviors. The combination of schema ARNs, facets, and attributes deﬁne uniqueness on the object.

The set of object facets, their constraints, and the relationships between them constitute an abstract schema deﬁnition. Schema facets are used to deﬁne constraints over the following things:

1. Attributes allowed in an object

2. Policy types allowed to apply to an object

Once you have added the necessary facets to your schema, you can apply the schema to your directory and create the applicable objects. For example, you can deﬁne a device schema by adding facets such as computers, phones, and tablets. You can then use these facets to create computer objects, phone objects, and tablet objects in the directory to which the schema applies.

Cloud Directory’s schema support makes it easy to add or modify facets and attributes without worrying about breaking applications. For more information, see In-Place Schema Upgrade (p. 12).

In-Place Schema Upgrade

Cloud Directory oﬀers the updating of existing schema attributes and facets to help integrate your applications with AWS provided services. Schemas that are in either the published or applied states have versions and cannot be changed. For more information, see Schema Lifecycle (p. 10).

Schema Versioning

A schema version indicates a unique identifier for a schema that developers can specify when programming their applications to conform to certain rules and formatting of data. Two key differentiators in the way versioning works with Cloud Directory are important for developers to understand. These differentiators—major version and minor version—can determine how future schema upgrades impact your application.

Major Version

Major version is the version identifier used for tracking major version changes for a schema. It can be up to 10 characters in length. Different versions of the same schema are completely independent. For example, two schemas with the same name and different versions are treated as completely different schemas, which have their own namespaces.

Backward incompatible changes

We recommend making changes to the major version only when schemas are incompatible. For example, when changing the data type of an existing attribute (such as changing from string to integer) or dropping a mandatory attribute from your schema. Backward-incompatible changes require directory data migration from a previous schema version to the new schema version.

(17)

Using the Schema Upgrade API Operations

Minor Version

Minor version is the version identiﬁer used for in-place upgrading of schemas or when you want to make backward-compatible upgrades such as adding additional attributes or adding facets. An upgraded schema using a minor version can be applied in place across all directories that use it without breaking any running applications. This includes directories that are used in production environments. For an example use case, see “How to Easily Apply Amazon Cloud Directory Schema Changes with In-Place Schema Upgrades” in the Cloud Directory Blog.

The minor version information and history is saved along with the other schema information in the schema metadata repository. No minor version information is retained in the objects. The advantage of introducing minor version is that client code works seamlessly as long as the major version is not changed.

Minor Version Limits

Cloud Directory retains and therefore limits up to ﬁve minor versions. However, minor version limits are enforced diﬀerently for published and applied schemas in the following ways:

• Applied schemas: Once the minor version limit has been exceeded, Cloud Directory deletes the oldest minor version automatically.

• Published schemas: Once the minor version limit has been exceeded, Cloud Directory does not delete any of the minor versions but it does inform the user via a LimitExceededException that the limit has been exceeded. Once you exceed the minor version limits, you can either delete the schema by using the DeleteSchema API or request a limit raise.

Using the Schema Upgrade API Operations

You can use the UpgradePublishedSchema API call to upgrade published schemas. Schema upgrades are applied in place to the directories that rely on it using the UpgradeAppliedSchema API call. You can also fetch the major and minor version of an applied schema by calling GetAppliedSchemaVersions.

Or view the associated schema ARNs and schema revision history for a directory by calling

ListAppliedSchemaArns. Cloud Directory maintains the ﬁve most recent versions of applied schema changes.

For an illustrative example, see “How to Easily Apply Amazon Cloud Directory Schema Changes with In- Place Schema Upgrades” in the Cloud Directory Blog. The blog post will demonstrate how you perform an in-place schema upgrade and use schema versions in Cloud Directory. It covers how to add additional attributes to an existing facet, add a new facet to a schema, publish the new schema, and apply it to running directories to complete the upgrading of a schema in-place. It also shows how to view the version history of a directory schema, which helps to ensure the directory ﬂeet is running the same version of the schema and has the correct history of schema changes applied to it.

Managed Schema

Cloud Directory makes it easy for you to rapidly develop applications by using a managed schema. With a managed schema, you can create a directory and start creating and retrieving objects from it at a faster pace. For more information, see Create Your Directory (p. 45).

Currently, there is one managed schema, called the QuickStartSchema. You can build a rich hierarchical data model and establish relationships across objects by using constructs such as Typed Links (p. 30). You can then query for any information in your data by traversing the hierarchy.

The QuickStartSchema managed schema is represented by the following JSON:

(18)

Facet Styles

QuickStartSchema: { "facets": {

"DynamicObjectFacet": { "facetStyle": "DYNAMIC"

},

"DynamicTypedLinkFacet": { "facetAttributes": {

"DynamicTypedLinkAttribute": { "attributeDefinition": { "attributeRules": {}, "attributeType": "VARIANT", "isImmutable": false

},

"requiredBehavior": "REQUIRED_ALWAYS"

} },

"identityAttributeOrder": [ "DynamicAttribute"

] } } }

QuickStartSchema ARN

The QuickStartSchema managed schema uses the following ARN:

String QUICK_START_SCHEMA_ARN = "arn:aws:clouddirectory:::schema/managed/

quick_start/1.0/001" ;

For example, you could use this ARN to create a directory called ExampleDirectory as shown below:

CreateDirectoryRequest createDirectoryRequest = new CreateDirectoryRequest() .withName("ExampleDirectory") // Directory name

.withSchemaArn(QUICK_START_SCHEMA_ARN);

Facet Styles

There are two diﬀerent styles that you can deﬁne on any given facet, Static and Dynamic.

Static Facets

Static facets are the best choice when you have all the details of your data model for your directory, such as a list of attributes with their data types, and you also want to deﬁne constraints for your attributes such as mandatory or unique ﬁelds. Cloud Directory will enforce the data constraints and rule checking during your object creation or change.

Dynamic Facets

You can use a dynamic facet when you need ﬂexibility to change the number of attributes or change the data values being stored within your attributes. Cloud Directory does not enforce any data constraints and rule checking during your object creation or change.

After creating a schema with dynamic facets, you can deﬁne any attributes that you need while creating objects. Cloud Directory will accept the attributes as key-value pairs and store them on their provided objects.

You can add a dynamic facet to a new or existing schema. You can also combine the static and dynamic facets within a single schema to get beneﬁts for each style of facet within your directory.

(19)

Sample Schemas

When you create any attribute using Dynamic facet, they are created as Variant data type. To store values for the attribute deﬁned as a Variant data type, you can use values of any of the primitive data types supported in Cloud Directory, such as String or Binary. Over time, you can also change the value of the attribute to another datatype. There is no enforcement of data validation.

You can use dynamic facets to deﬁne objects of the following type:

• NODE

• LEAF_NODE

• POLICY

For additional details about managed schemas, dynamic facets or variant data types and to see example use cases, see How to rapidly develop applications on Amazon Cloud Directory using AWS Managed Schema in the Amazon Cloud Directory blog.

Sample Schemas

Cloud Directory comes ready with sample schemas for Organizations, Persons, and Devices. The following section lists the various sample schemas and lists the diﬀerences for each.

Organizations

The following tables list the facets that are included in the Organizations sample schema.

"Organization" Facet Data Type Length Required

Behavior?Description

account_id String 1024 N Unique id for Organization

account_name String 1024 N Name of Organization

organization_status String 1024 N Status such as 'active', 'suspended', 'inactive', 'closed'

mailing_address (street1) String 1024 N A physical mailing address for this company/entity

mailing_address (street2) String 1024 N A physical mailing address for this company/entity

mailing_address (city) String 1024 N A physical mailing address for this company/entity

mailing_address (state) String 1024 N A physical mailing address for this company/entity

mailing_address (country) String 1024 N A physical mailing address for this company/entity

mailing_address

(postal_code) String 1024 N A physical mailing address for this company/entity

email String 1024 N Email id for Organization

web_site String 1024 N Website URL

(20)

Person

"Organization" Facet Data Type Length Required

Behavior?Description

telephone_number String 1024 N Telephone number for Organization

description String 1024 N Description for Organization

"Legal_Entity" Facet Data

Type Length Required

Behavior?Description registered_company_name String 1024 N Legal entity name

mailing_address (street1) String 1024 N A physical registered address for this company/entity

mailing_address (street2) String 1024 N A physical registered address for this company/entity

mailing_address (city) String 1024 N A physical registered address for this company/entity

mailing_address (state) String 1024 N A physical registered address for this company/entity

mailing_address (country) String 1024 N A physical registered address for this company/entity

mailing_address

(postal_code) String 1024 N A physical registered address for this company/entity

industry_vertical String 1024 N Industry Segment

billing_currency String 1024 N Billing currency

tax_id String 1024 N Tax identiﬁcation number

Person

The following tables list the facets that are included in the Person sample schema.

"Person" Facet Data Type Length Required

Behavior? Description

display_name String 1024 N The name of the user, suitable

for display to end-users.

ﬁrst_name String 1024 N The given name of the User,

or ﬁrst name in most western languages

last_name String 1024 N The family name of the User,

or last name in most western languages

(21)

Person

"Person" Facet Data Type Length Required

middle_name String 1024 N The middle name(s) of the

User

nickname String 1024 N The casual way to address the

user in real life, such as, "Bob"

or "Bobby" instead of "Robert"

email String 1024 N Email address for the user

mobile_phone_number String 1024 N Phone number for the user

home_phone_number String 1024 N Phone number for the user

username String 1024 Y unique identiﬁer for the user

proﬁle String 1024 N A URI that is a uniform

resource locator and that points to a location representing the user's online proﬁle (such as a webpage)

picture String 1024 N A URI that is a uniform

resource locator that points to a resource location

representing the user's image.

website String 1024 N URL

timezone String 1024 N The User's time zone

locale String 1024 N Used to indicate the User's

default location for purposes of localizing such items as currency, date time format, or numerical representations.

address (street1) String 1024 N A physical mailing address for this user.

address (street2) String 1024 N A physical mailing address for

this user.

address (city) String 1024 N A physical mailing address for

this user.

address (state) String 1024 N A physical mailing address for

this user.

address (country) String 1024 N A physical mailing address for

this user.

address (postal_code) String 1024 N A physical mailing address for

this user.

user_status String 1024 N Value indicating the user's

administrative status

(22)

Device

"Organization_Person"

Facet Data Type Length Required

title String 1024 N Title in organization

preferred_language String 1024 N Indicates the user's preferred

written or spoken languages and is generally used for selecting a localized user interface.

employee_id String 1024 N A string identiﬁer, typically

numeric or alphanumeric, assigned to a person

cost_center Integer 1024 N Identiﬁes the cost center

department String 1024 N Identiﬁes the name of a

department

manager String 1024 N The user's manager

company_name String 1024 N Identiﬁes the name of an

organization

company_address (street1) String 1024 N A physical mailing address for the organization

company_address (street2) String 1024 N A physical mailing address for the organization

company_address (city) String 1024 N A physical mailing address for the organization

company_address (state) String 1024 N A physical mailing address for the organization

company_address (country) String 1024 N A physical mailing address for the organization

company_address

(postalCode) String 1024 N A physical mailing address for

the organization

Device

The following table lists the facet that is included in the Device sample schema.

"Device" Facet Data

device_id String 1024 N Alpha-numeric unique device

id

name String 1024 N Friendly name for device

description String 1024 N Description for device

(23)

Custom Schemas

"Device" Facet Data

X.509_certiﬁcates String 1024 N X.509 Certiﬁcate

device_version String 1024 N Device version

device_os_type String 1024 N Operating System on device

device_os_version String 1024 N Operating System version

number on device

serial_number String 1024 N Serial number of device

device_status String 1024 N Status for device (such

as active, not_active, suspended, shutdown, oﬀ)

Custom Schemas

The first step in creating a custom schema is to define exactly what fields you must index. These required fields form your schema's skeleton elements, to which you add your own fields. Map the name and type of each field (such as string, integer, Boolean) to your object's structure. You can define a schema with types and constraints and then apply them to a directory. Once defined, Cloud Directory performs validation for attributes.

For more information, see Create a Schema (p. 2).

Attribute References

Amazon Cloud Directory facets contain attributes. Attributes can be either an attribute definition or an attribute reference. Attribute definitions are attributes that declare their name and primitive type (string, binary, Boolean, DateTime, or number). They can also optionally declare their required behavior, default value, immutable flag, and attribute rules (such as min/max length).

Attribute references are attributes that derive their primitive type, default value, immutable flag and attribute rules from another preexisting attribute definition. Attribute references do not have their own primitive type, default values, immutable flag or rules, since those properties come from the target attribute definition.

Attribute references may override the required behavior of a target deﬁnition (more details about this below).

When you create an attribute reference, you provide only an attribute name and the target attribute definition (which includes the facet name and attribute name of the target attribute definition). Attribute references may not refer to other attribute references. Also, at this time, attribute references may not target attribute definitions from a different schema.

You can use an attribute reference when you want two or more attributes on an object to refer to the same storage location. For example, imagine an object that has a User facet and an EnterpriseUser facet applied. The User facet has a FirstName attribute deﬁnition, while the EnterpriseUser facet has an attribute reference pointing at User.FirstName. Since both FirstName attributes refer to the same storage location on the object, any change to either the User.FirstName or the EnterpriseUser.FirstName has the same eﬀect.

(24)

API Example

The following example demonstrates the use of attribute references using the Cloud Directory API.

In this example, a base facet contains an attribute deﬁnition, and another facet contains an attribute referring to an attribute in the base facet. Note that the reference attribute can be marked Required while the base facet is Not Required.

// create base facet

CreateFacetRequest req1 = new CreateFacetRequest() .withSchemaArn(devSchemaArn)

.withName("baseFacet") .withAttributes(List(

new FacetAttribute() .withName("baseAttr")

.withRequiredBehavior(RequiredAttributeBehavior.NOT_REQUIRED) .withAttributeDefinition(new

FacetAttributeDefinition().withType(FacetAttributeType.STRING)))) .withObjectType(ObjectType.DIRECTORY)

cloudDirectoryClient.createFacet(req1)

// create another facet that refers to the base facet CreateFacetRequest req2 = new CreateFacetRequest() .withSchemaArn(devSchemaArn)

.withName("facetA") .withAttributes(List(

new FacetAttribute() .withName("ref")

.withRequiredBehavior(RequiredAttributeBehavior.REQUIRED_ALWAYS) .withAttributeReference(new FacetAttributeReference()

.withTargetFacetName("baseFacet") .withTargetAttributeName("baseAttr")))) .withObjectType(ObjectType.DIRECTORY)

cloudDirectoryClient.createFacet(req2)

JSON Example:

The following example demonstrates the use of attribute references in a JSON model. The schema represented by this model is identical to the model above.

{ "facets" : { "baseFacet" : {

"facetAttributes" : { "baseAttr" : {

"attributeDefinition" : { "attributeType" : "STRING"

},

"requiredBehavior" : "NOT_REQUIRED"

} },

"objectType" : "DIRECTORY"

},

"facetA" : {

"facetAttributes" : { "ref" : {

"attributeReference" : {

"targetFacetName" : "baseFacet", "targetAttributeName" : "baseAttr"

},

"requiredBehavior" : "REQUIRED_ALWAYS"

}

(25)

JSON Example:

},

" objectType" : "DIRECTORY"

} }

Attribute reference considerations

Attribute references must target a preexisting attribute deﬁnition in the same schema.

• Attribute references may target a preexisting attribute deﬁnition in the same facet or a diﬀerent facet.

• Attribute references may not target other attribute references.

• Facets containing attribute deﬁnitions that are the target of another facet's attribute reference cannot be deleted until all references have been deleted.

You can use attribute references the same way that you use traditional attribute deﬁnitions, by creating objects or applying facets to existing objects.

NoteYou can apply facets with references to other facets but are not required to apply the target facets directly. When the target facet is not applied, there is no change to the behavior of the attribute reference. (You need to apply target facets only when you want the other attributes on that facet to exist on the object.)

Setting Attribute Reference Values

You can call the UpdateObjectAttributes API action when you want to change the value of an attribute.

Updating (or deleting) either the definition or any other reference to that same definition on that object has the same effect.

Getting Attribute Reference Values

You can call the ListObjectAttributes API action to retrieve storage aliases. This call returns a list of tuples, each of which contains an attribute key and its associated value. The attribute keys correspond to the list of storage aliases present on that object.

NoteIt is possible for an attribute key to be returned for a facet that was not explicitly applied to an object. This can happen when attribute references target facets that are not applied to the object.

For example, imagine that you have a User facet and an EnterpriseUser facet. The

EnterpriseUser.FirstName attribute refers to User.FirstName. You then apply both the User and

EnterpriseUser facets to an object, set User.FirstName to Robert, and later set EnterpriseUser.FirstName to Bob. When you call ListObjectAttributes you see only "User.FirstName = Bob" since there is only one storage alias for both FirstName attributes.

Using Indexes with Attribute References

You can can create indexes with an attribute definition only, not a reference. Listing an index does not return attribute keys for attribute references. But it does return attribute keys for any attribute definitions that are targeted by references existing on the indexed object. In other words, at the index layer, attribute references are treated merely as an alternative identifier for an attribute, which gets resolved to the correct attribute definition identifier at runtime.

For example, imagine you have an Index for facet User attribute FirstName. You attach an object with only the EnterpriseUser facet applied. You then set the value for that object's EnterpriseUser.FirstName attribute to Bob. Finally, you call ListIndex action. The results contain only "User.FirstName = Bob".

(26)

Attribute Rules

Required Behavior for Attribute References

An attribute references can have a required behavior that is diﬀerent from its target attribute deﬁnition.

This allows a base deﬁnition to be optional, while a reference to that same deﬁnition can be required.

When an object has a base definition and one or more references to the same base definition, the base definition and all references must adhere to the strongest required behavior present across all related attributes.

• As with attribute deﬁnitions, you must provide values for any required attribute deﬁnitions when you create the object or when you add a facet to an existing object.

• As a convenience, when more than one attribute on an object refers to the same storage location, you only need to provide a value for one of the attributes for that storage location.

• Similarly, if you do provide multiple values for the same storage location, the values must be equal.

Attribute Rules

Rules describe permissible values of an attribute type and constrain the values that are allowed for any particular attribute. You must specify rules as part of an attribute deﬁnition when you create a facet.

Cloud Directory supports the following rule types:

• String length

• Binary length

• String from set

• Number comparison

String length

Constrains the length of a string attribute value.

Allowed rule parameter keys: min, max Allowed rule parameter values: number Binary length

Constrains the byte array length of a binary attribute value.

Allowed rule parameter keys: min, max Allowed rule parameter values: number String from set

Constrains the value of a string attribute to the allowed set of speciﬁed strings.

Allowed rule parameter keys: allowedValues

Allowed rule parameter values: Set of strings with each string to be UTF-8 encoded

Allowed values are comma delimited and can be wrapped in quotes. This is useful when allowed values include comma’s. For example:

• One,two,three = matches One two or three

• “with,comma”,”withoutcomma” = matches “with,comma” or “withoutcomma”

(27)

Format Speciﬁcation

• with”quote,withoutquote matches ‘with”quote’ or ‘withoutquote’

Number comparison

Constraints the numeric value allowed for a number attribute.

Allowed rule parameter keys: min, max Allowed rule parameter values: number

Format Speciﬁcation

A Cloud Directory schema adds structure to the data in your data directories. Cloud Directory provides two mechanisms for you to deﬁne your schema. Developers can use speciﬁc API operations to construct a schema or they can upload a schema entirely using schema upload capabilities. Schema documents can be uploaded via API calls or through the console. This section describes the format to use when you upload entire schema documents.

JSON Schema Format

A schema document is a JSON document in the following overall format.

{ "facets": {

"facet name": {

"facetAttributes": {

"attribute name": Attribute JSON Subsection }

} } }

A schema document contains a map of facet names to facets. Each facet in turn contains a map

containing attributes. All facet names within a schema must be unique. All attribute names within a facet must be unique.

Attribute JSON Subsection

Facets contain attributes. Each attribute deﬁnes the type of value that can be stored on an attribute. The following JSON format describes an attribute.

{

"attributeDefinition": Attribute Definition Subsection, "attributeReference": Attribute Reference Subsection, "requiredBehavior": "REQUIRED_ALWAYS" or "NOT_REQUIRED"

}

You must provide either an attribute deﬁnition or an attribute reference. See related subsections for more information about each.

The required behavior ﬁeld indicates whether this attribute is required or not. You must provide this ﬁeld. Possible values are as follows:

• REQUIRED_ALWAYS: This attribute must be provided when the object is created or a facet is added to the object. You cannot remove this attribute.

(28)

JSON Schema Format

• NOT_REQUIRED: This attribute may or may not be present.

Attribute Deﬁnition Subsection

An attribute deﬁnes the type and the rules associated with an attribute value. The following JSON layout describes the format.

{ "attributeType": One of "STRING", "NUMBER", "BINARY", "BOOLEAN" or "DATETIME", "defaultValue": Default Value Subsection,

"isImmutable": true or false,

"attributeRules": "Attribute Rules Subsection"

}

Default Value Subsection

Specify exactly one of the following default values. Long values and Boolean values should be provided outside of quotes (as their respective Javascript types instead of strings). Binary values are provided using a URL-safe Base64 encoded string (as described in RFC 4648). Datetimes are provided in the number of milliseconds since the epoch (00:00:00 UTC on Jan 1, 1970).

{

"stringValue": "a string value", "longValue": an integer value, "booleanValue": true or false,

"binaryValue": a URL-safe Base64 encoded string,

"datetimeValue": an integer value representing milliseconds since epoch }

Attribute Rules Subsection

Attributes rules deﬁne constraints on attribute values. You can deﬁne multiple rules for each attribute.

Attribute rules contain a rule type and a set of parameters for the rule. You can ﬁnd more details in the Attribute Rules (p. 22) section.

{ "rule name": { "parameters": {

"rule parameter key 1": "value", "rule parameter key 2": "value"

},

"ruleType": "rule type value"

} }

Attribute Reference Subsection

Attribute references are an advanced feature. They allow multiple facets to share an attribute deﬁnition and stored value. See the Attribute References (p. 19) section for more information. You can deﬁne an attribute reference in JSON schema with the following template.

{ "targetSchemaArn": "schema ARN"

"targetFacetName": "facet name"

"targetAttributeName": "attribute name"

}

(29)

Schema Document Examples

The following are samples of schema documents that show valid JSON formatting.

NoteAll values expressed in the allowedValues string must be comma separated and be without spaces. For example, "SENSITIVE,CONFIDENTIAL,PUBLIC".

Basic Schema Document

{

"facets": { "Employee": {

"facetAttributes": { "Name": {

"attributeDefinition": { "attributeType": "STRING", "isImmutable": false, "attributeRules": { "NameLengthRule": { "parameters": { "min": "3", "max": "100"

},

"ruleType": "STRING_LENGTH"

} } },

},

"EmailAddress": {

"attributeDefinition": { "attributeType": "STRING", "isImmutable": true, "attributeRules": {

"EmailAddressLengthRule": { "parameters": {

"min": "3", "max": "100"

},

"ruleType": "STRING_LENGTH"

} } },

},

"Status": {

"attributeDefinition": { "attributeType": "STRING", "isImmutable": false, "attributeRules": { "rule1": {

"parameters": {

"allowedValues": "ACTIVE,INACTIVE,TERMINATED"

},

"ruleType": "STRING_FROM_SET"

} } },

} },

"objectType": "LEAF_NODE"

(30)

},

"DataAccessPolicy": { "facetAttributes": { "AccessLevel": {

"attributeDefinition": { "attributeType": "STRING", "isImmutable": true, "attributeRules": { "rule1": {

"parameters": {

"allowedValues": "SENSITIVE,CONFIDENTIAL,PUBLIC"

},

"ruleType": "STRING_FROM_SET"

} } },

} },

"objectType": "POLICY"

},

"Group": {

"facetAttributes": { "Name": {

"attributeDefinition": { "attributeType": "STRING", "isImmutable": true },

} },

"objectType": "NODE"

} } }

Schema Document with Typed Links

{

"sourceSchemaArn": "", "facets": {

"employee_facet": { "facetAttributes": { "employee_login": {

"attributeDefinition": { "attributeType": "STRING", "isImmutable": true, "attributeRules": {}

},

"employee_id": {

},

"employee_name": {

(31)

},

"employee_role": {

},

} },

"objectType": "LEAF_NODE"

},

"device_facet": { "facetAttributes": { "device_id": {

},

"device_type": {

},

} },

},

"region_facet": {

"facetAttributes": {}, "objectType": "NODE"

},

"group_facet": {

"facetAttributes": { "group_type": {

},

} },

},

"office_facet": { "facetAttributes": { "office_id": {

},

"office_type": {

"attributeDefinition": { "attributeType": "STRING", "isImmutable": true,

(32)

"attributeRules": {}

},

"office_location": {

},

} },

"typedLinkFacets": { "device_association": { "facetAttributes": { "device_type": {

"attributeDefinition": { "attributeType": "STRING", "isImmutable": false, "attributeRules": {}

},

"device_label": {

"attributeDefinition": { "attributeType": "STRING", "isImmutable": false, "attributeRules": {}

},

} },

"identityAttributeOrder": [ "device_label",

"device_type"

] } } }

(33)

Links

Directory Objects

Developers model directory objects using extensible schemas to enforce data correctness constraints automatically, making it easier to program for. Amazon Cloud Directory oﬀers rich information lookup based on your deﬁned indexed attributes, thus enabling fast tree traversals and searches within the directory trees. Cloud Directory data is encrypted at rest and in transit.

An object is a basic element of Cloud Directory. Each object has a globally unique identifier, which is specified by the object Identifier. An object is a collection of zero or more facets with their attribute keys and values. An object can be created from one or more facets within a single applied schema or from facets of multiple applied schemas. During object creation, you must specify all required attribute values. Objects can have a limited number of facets. For more information, see Amazon Cloud Directory Limits (p. 68).

An object can be a regular object, a policy object, or an index object. An object can also be a node object or a leaf node object. The type of the object is inferred from the object type of the facets attached to it.

Topics

• Links (p. 29)

• Range Filters (p. 35)

• Access Objects (p. 36)

• Consistency Levels (p. 40)

Links

A link is a directed edge between two objects that deﬁne a relationship. Cloud Directory currently supports the following link types.

Amazon Cloud Directory

Amazon Cloud Directory

Developer Guide

Amazon Cloud Directory: Developer Guide

Table of Contents

What Is Amazon Cloud Directory?

What Cloud Directory Is Not

Getting Started

Create a Schema

Create an Amazon Cloud Directory

Using Cloud Directory Interface VPC Endpoints

Availability

Create a VPC for Cloud Directory

Control Access to Your Cloud Directory VPC Endpoint

Understanding Key Cloud Directory Concepts

Schema

Facets

Managed Schemas

Sample Schemas

Custom Schemas

Directory

Objects

Policies

Directory Structure

Root Node

Node

Leaf Node

Node Link

Schemas

Schema Lifecycle

Development State

Published State

Applied State

Facets

In-Place Schema Upgrade

Schema Versioning

Major Version

Minor Version

Using the Schema Upgrade API Operations

Managed Schema

Facet Styles

Static Facets

Dynamic Facets

Sample Schemas

Organizations

Person

Device

Custom Schemas

Attribute References

API Example

JSON Example:

Attribute reference considerations

Setting Attribute Reference Values

Getting Attribute Reference Values

Using Indexes with Attribute References

Required Behavior for Attribute References

Attribute Rules

Format Speciﬁcation

JSON Schema Format

Attribute JSON Subsection

Attribute Deﬁnition Subsection

Default Value Subsection

Attribute Rules Subsection

Attribute Reference Subsection

Schema Document Examples

Basic Schema Document

Schema Document with Typed Links

Directory Objects

Links