# Getting started with AWS RAM With AWS Resource Access Manager, you can share resources that you own with other individual AWS accounts. If your account is managed by AWS Organizations, you can also share resources with the other accounts in your organization. You can also use resources that were shared with you by other AWS accounts. If you don't enable sharing within AWS Organizations, you can't share resources with your organization or with the organizational units (OU) in your organization. However, you can still share resources with individual AWS accounts in your organization. For [supported resource types](shareable.md), you can also share resources with individual AWS Identity and Access Management (IAM) roles or users in your organization. In this case, these principals are treated as if they were external accounts, rather than as part of your organization. They receive an invitation to join the resource share, and they must accept the invitation to gain access to the shared resources. **Topics** + [Terms and concepts](getting-started-terms-and-concepts.md) + [Sharing your resources](getting-started-sharing.md) + [Using shared resources](getting-started-shared.md) # Terms and concepts for AWS RAM The following concepts help explain how you can use AWS Resource Access Manager (AWS RAM) to share your resources. ## Resource share You share resources using AWS RAM by creating a *resource share*. A resource share has the following three elements: + A list of one or more AWS resources to be shared. + A list of one or more [principals](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#Principal_specifying) to whom access to the resources is granted. + A [managed permission](#term-managed-permission) for each type of resource that you include in the share. Each managed permission applies to all resources of that type in that resource share. After you use AWS RAM to create a resource share, the principals specified in the resource share can be granted access to the share's resources. + If you turn on AWS RAM sharing with AWS Organizations, and your principals that you share with are in the same organization as the sharing account, those principals can receive access as soon as their account administrator grants them permissions to use the resources using an AWS Identity and Access Management (IAM) permission policy. + If you don't turn on AWS RAM sharing with Organizations, you can still share resources with individual AWS accounts that are in your organization. The administrator in the consuming account receives an invitation to join the resource share, and they must accept the invitation before the principals specified in the resource share can access the shared resources. + You can also share with accounts outside of your organization, if the resource type supports it. The administrator in the consuming account receives an invitation to join the resource share, and they must accept the invitation before the principals specified in the resource share can access the shared resources. For information about which resource types support this type of sharing, see [Shareable AWS resources](shareable.md) and view the **Can share with accounts outside its organization** column. ## Sharing account The *sharing account* contains the resource that is shared and in which the AWS RAM administrator creates the AWS resource share by using AWS RAM. An AWS RAM administrator is an IAM principal who has permissions to create and configure resource shares in the AWS account. Because AWS RAM works by attaching a resource-based policy to the resources in a resource share, the AWS RAM administrator also must have permissions to call the `PutResourcePolicy` operation in the AWS service for each resource type included in a resource share. ## Consuming principals The *consuming account* is the AWS account to which a resource is shared. The resource share can specify an entire account as the principal, or for some resource types, individual roles or users in the account. For information about which resource types support this type of sharing, see [Shareable AWS resources](shareable.md) and view the **Can share with IAM roles & users** column. AWS RAM also supports service principals as consumers of resource shares. For information about which resource types support this type of sharing, see [Shareable AWS resources](shareable.md) and view the **Can share with service principals** column. The principals in the consuming account can perform only those actions allowed by ***both*** of the following permissions: + The managed permissions attached to the resource share. These specify the *maximum* permissions that can be granted to the principals in the consuming account. + The IAM identity-based policies attached to individual roles or users by the IAM administrator in the consuming account. Those policies must grant `Allow` access to specified actions and to the [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) of a resource in the sharing account. AWS RAM supports the following IAM principal types as consumers of resource shares: + **Another AWS account** – The resource share makes the included resources in the sharing account available to the consuming account. + **Individual IAM roles or users in another account** – Some resource types support sharing directly with individual IAM roles or users. Specify this principal type by its ARN. + **IAM role** – `arn:aws:iam::123456789012:role/rolename` + **IAM user** – `arn:aws:iam::123456789012:user/username` + **Service principal** – Share a resource with an AWS service to grant the service access to a resource share. Service principal sharing allows an AWS service to take actions on your behalf to ease the operational burden. To share with a service principal, choose to allow sharing with anyone, and then, under **Select principal type**, choose **Service principal** from the dropdown list. Specify the service principal's name in the following format: + `service-id.amazonaws.com` To mitigate the risk of confused deputy, the resource policy shows the resource owner's account ID in the `aws:SourceAccount` condition key. + **Accounts in an organization** – If the sharing account is managed by AWS Organizations, then the resource share can specify the organization’s ID to share with all of the accounts in the organization. The resource share can alternatively specify an organizational unit (OU) ID to share with all of the accounts in that OU. A sharing account can share only with its own organization or OU IDs within its own organization. Specify accounts in an organization by the ARN of the organization or the OU. + **All accounts in an organization** – Following is an example ARN of an organization in AWS Organizations: `arn:aws:organizations::123456789012:organization/o-` + **All accounts in an organizational unit**– Following is an example ARN of an OU ID: `arn:aws:organizations::123456789012:organization/o-/ou--` **Important** When you share with an organization or an OU, and that scope includes the account that owns the resource share, all principals in the sharing account automatically get access to the resources in the share. The access granted is defined by the managed permissions associated with the share. This is because the resource-based policy that AWS RAM attaches to each resource in the share uses `"Principal": "*"`. For more information, see [Implications of using "Principal": "\$1" in a resource-based policy](#term-principal-star). Principals in the other consuming accounts don't immediately get access to the share's resources. The other accounts' administrators must first attach identity-based permission policies to the appropriate principals. Those policies must grant `Allow` access to the ARNs of individual resources in the resource share. The permissions in those policies can't exceed those specified in the managed permission associated with the resource share. ## Resource-based policy Resource-based policies are JSON text documents that implement the IAM policy language. Unlike identity-based policies that you attach to the principal, such as an IAM role or user, you attach resource-based policies to the resource. AWS RAM authors resource-based policies on your behalf based on the information you provide for your resource share. You must specify a `Principal` policy element that determines who can access the resource. For more information, see [Identity-based policies and resource-based policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html) in the *IAM User Guide*. The resource-based policies generated by AWS RAM are evaluated along with all other IAM policy types. This includes any IAM identity-based policies attached to the principals who are attempting to access the resource, and service control policies (SCPs) for AWS Organizations that might apply to the AWS account. Resource-based policies generated by AWS RAM participate in the same policy evaluation logic as all other IAM policies. For complete details of policy evaluation and how to determine the resulting permissions, see [Policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html) in the *IAM User Guide*. AWS RAM provides a simple and secure resource sharing experience by providing easy-to-use abstraction resource-based policies. For those resource types that support resource-based policies, AWS RAM automatically constructs and manages the resource-based policies for you. For a given resource, AWS RAM builds the resource-based policy by combining the information from all of the resource shares that include that resource. For example, consider an Amazon SageMaker AI pipeline that you share by using AWS RAM and include in two different resource shares. You could use one resource share to provide read-only access to your entire organization. You could then use the other resource share to grant only SageMaker AI execution permissions to a single account. AWS RAM automatically combines those two different sets of permissions into a single resource policy with multiple statements. It then attaches the combined resource-based policy to the pipeline resource. You can view this underlying resource policy by calling the [https://docs.aws.amazon.com/ram/latest/APIReference/API_GetResourcePolicies.html](https://docs.aws.amazon.com/ram/latest/APIReference/API_GetResourcePolicies.html) operation. AWS services then use that resource-based policy to authorize any principal who attempts to perform an action on the shared resource. Although you can manually create the resource-based policies and attach them to your resources by calling `PutResourcePolicy`, we recommend that you use AWS RAM because it provides the following advantages: + **Discoverability for share consumers** – If you share resources by using AWS RAM, users can see all of the resources shared with them directly in the resource owning service's console and API operations as if those resources were directly in the user's account. For example, if you share an AWS CodeBuild project with another account, users in the consuming account can see the project in the CodeBuild console and in the results of CodeBuild API operations performed. Resources shared by directly attaching a resource-based policy aren't visible this way. Instead, you must discover and explicitly refer to the resource by its ARN. + **Manageability for share owners** – If you share resources by using AWS RAM, resource owners in the sharing account can centrally see which other accounts have access to their resources. If you share a resource using a resource-based policy, you can see the consuming accounts only by examining the policy for individual resources in the relevant service console or API. + **Efficiency** – If you share resources by using AWS RAM, you can share multiple resources and manage them as a unit. Resources shared by using only resource-based policies require individual policies attached to every resource that you share. + **Simplicity** – With AWS RAM, you don't need to understand the JSON-based IAM policy language. AWS RAM provides ready-to-use AWS managed permissions that you can choose from to attach to your resource shares. By using AWS RAM, you can even share some resource types that don’t support resource-based policies yet. For such resource types, AWS RAM automatically generates a resource-based policy as a representation of the actual permissions. Users can view this representation by calling [https://docs.aws.amazon.com/ram/latest/APIReference/API_GetResourcePolicies.html](https://docs.aws.amazon.com/ram/latest/APIReference/API_GetResourcePolicies.html). This includes the following resource types: + Amazon Aurora – DB clusters + Amazon EC2 – capacity reservations and dedicated hosts + AWS License Manager – License configurations + AWS Outposts – Local gateway route tables, outposts, and sites + Amazon Route 53 – Forwarding rules + Amazon Virtual Private Cloud – Customer-owned IPv4 addresses, prefix lists, subnets, traffic mirror targets, transit gateways, and transit gateway multicast domains ### Examples of AWS RAM generated resource-based policies If you share an EC2 Image Builder image resource with an individual ***account***, AWS RAM generates a policy that looks like the following example and attaches it to any image resources that are included in the resource share. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:root" }, "Action": [ "imagebuilder:GetImage", "imagebuilder:ListImages" ], "Resource": "arn:aws:imagebuilder:us-east-1:123456789012:image/testimage/1.0.0/44" } ] } ``` ------ If you share an EC2 Image Builder image resource with an ***IAM role or user*** in a different AWS account, AWS RAM generates a policy that looks like the following example and attaches it to any image resources that are included in the resource share. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:role/MySampleRole" }, "Action": [ "imagebuilder:GetImage", "imagebuilder:ListImages" ], "Resource": "arn:aws:imagebuilder:us-east-1:123456789012:image/testimage/1.0.0/44" } ] } ``` ------ If you share an EC2 Image Builder image resource with all of the accounts in an organization or with the accounts an OU, AWS RAM generates a policy that looks like the following example and attaches it to any image resources that are included in the resource share. **Note** This policy uses `"Principal": "*"` and then uses the `"Condition"` element to restrict permissions to identities that match the specified `PrincipalOrgID`. For more information, see [Implications of using "Principal": "\$1" in a resource-based policy](#term-principal-star). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": [ "imagebuilder:GetImage", "imagebuilder:ListImages" ], "Resource": "arn:aws:imagebuilder:us-east-1:123456789012:image/testimage/1.0.0/44", "Condition": { "StringEquals": { "aws:PrincipalOrgID": "o-123456789" } } } ] } ``` ------ ### Implications of using "Principal": "\$1" in a resource-based policy When you include `"Principal": "*"` in a resource-based policy, the policy grants access to all IAM principals in the account that contains the resource, subject to any restrictions imposed by a `Condition` element, if it exists. Explicit `Deny` statements in any policy that applies to the calling principal overrides the permissions granted by this policy. However, an ***implicit*** `Deny` (meaning the lack of an *explicit * `Allow`) in any applicable identity policies, permissions boundary policies, or session policies does ***not*** result in a `Deny` to the principals granted access to an action by such a resource-based policy. If this behavior isn’t desirable for your scenario, then you can limit this behavior by adding an ***explicit*** `Deny` statement to an identity policy, permissions boundary, or session policy that affects the relevant roles and users. ## Managed permissions Managed permissions define what actions principals can perform under which conditions on supported resource types in a resource share. When you create a resource share, you must specify which managed permission to use for each resource type included in the resource share. A managed permission lists the set of `actions` and *conditions* that principals can perform with the resource shared using AWS RAM. You can attach only one managed permission for each resource type in a resource share. You can't create a resource share in which some resources of a certain type use one managed permission and other resources of the same type use a different managed permission. To do that, you would need to create two different resource shares and split the resources among them, giving each set a different managed permission. There are two different types of managed permissions: **AWS managed permissions** AWS managed permissions are created and maintained by AWS and grant permissions for common customer scenarios. AWS RAM defines at least one AWS managed permission for every supported resource type. Some resource types support more than one AWS managed permission, with one managed permission designated as the AWS default. The [default AWS managed permission](security-ram-permissions.md#permissions-types) is associated unless you specify otherwise. **Customer managed permissions** Customer managed permissions are managed permissions that you author and maintain by precisely specifying which actions can be performed under which conditions with resources shared using AWS RAM. For example, you want to limit read access for your Amazon VPC IP Address Manager (IPAM) pools, which help you manage your IP addresses at scale. You can create customer managed permissions for your developers to assign IP addresses, but not view the range of IP addresses other developer accounts assign. You can follow the best practice of least privilege, granting only the permissions required to perform tasks on shared resources. You define your own permission for a resource type in a resource share with the option to add conditions such as [ Global Context Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) and [ service specific keys](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html) to specify the conditions under which principals have access to the resource. These permissions can be used in one or more AWS RAM shares. Customer managed permissions are Region specific. AWS RAM takes managed permissions as an input to author the [resource-based policies](#term-resource-based-policy) for the resources you share. ## Managed permission version Any change to a managed permission is represented as a new version of that managed permission. The new version is the default for all new resource shares. Each managed permission always has one version designated as the default version. When you or AWS creates a new managed permission version, you must explicitly update the managed permission for each existing resource share. You can evaluate the changes before you apply them to your resource share in this step. All new resource shares will automatically use the new version of the managed permission for the corresponding resource type. **AWS managed permission versions** AWS handles all changes to AWS managed permissions. Such changes address new functionality or remove discovered shortcomings. You can only apply the default managed permission version to your resource shares. **Customer managed permission versions** You handle all changes to customer managed permissions. You can create a new default version, set an older version as the default, or delete versions that are no longer associated with any resource shares. Each customer managed permission can have up to five versions. When you create or update a resource share, you can attach only the default version of the specified managed permission. For more information, see [Updating AWS managed permissions to a newer version](working-with-sharing-update-permissions.md). # Sharing your AWS resources To share a resource that you own by using AWS RAM, do the following: + [Enable resource sharing within AWS Organizations](#getting-started-sharing-orgs) (optional) + [Create a resource share](#getting-started-sharing-create) **Notes** Sharing a resource with principals outside of the AWS account that owns the resource doesn't change the permissions or quotas that apply to the resource within the account that created it. AWS RAM is a Regional service. The principals that you share with can access resource shares in only the AWS Regions in which the resources were created. Some resources have special considerations and prerequisites for sharing. For more information, see [Shareable AWS resources](shareable.md). ## Enable resource sharing within AWS Organizations When your account is managed by AWS Organizations, you can take advantage of that to share resources more easily. With or without Organizations, a user can share with individual accounts. However, if your account is in an organization, then you can share with individual accounts, or with all accounts in the organization or in an OU without having to enumerate each account. To share resources within an organization, you must first use the AWS RAM console or AWS Command Line Interface (AWS CLI) to enable sharing with AWS Organizations. When you share resources in your organization, AWS RAM doesn't send invitations to principals. Principals in your organization gain access to shared resources without exchanging invitations. When you enable resource sharing within your organization, AWS RAM creates a service-linked role called `AWSServiceRoleForResourceAccessManager`. This role can be assumed by only the AWS RAM service, and grants AWS RAM permission to retrieve information about the organization it is a member of, by using the AWS managed policy `AWSResourceAccessManagerServiceRolePolicy`. **Note** By default, when you enable sharing with AWS Organizations, resource sharing within your organization restricts access to consumers within the same organization. If a consumer account leaves the organization, that account loses access to resources in the resource share. This restriction applies whether you share resources with an OU, the entire organization, or an individual account in the organization. For account-to-account sharing within your organization, you can retain sharing access when accounts leave by setting `RetainSharingOnAccountLeaveOrganization` to `True` when you create a new resource share. With this setting enabled, AWS RAM sends an invitation to the consuming account (similar to sharing with external accounts). The account retains access to shared resources even if it leaves the organization. The `RetainSharingOnAccountLeaveOrganization` setting has the following requirements and limitations: Requires `allowExternalPrincipals` to be `True` Can only be set when creating new resource shares Does not apply to sharing with OUs or the entire organization When `RetainSharingOnAccountLeaveOrganization` is set to `True`, you cannot use resource shares to share resources that [can only be shared within an organization](shareable.html). If you no longer need to share resources with your entire organization or OUs, you can disable resource sharing. For more information, see [Disabling resource sharing with AWS Organizations](security-disable-sharing-with-orgs.md). **Minimum permissions** To run the procedures below, you must sign in as a principal in the organization's management account that has the following permissions: + `ram:EnableSharingWithAwsOrganization` + `iam:CreateServiceLinkedRole` + `organizations:enableAWSServiceAccess` + `organizations:DescribeOrganization` **Requirements** + You can perform these steps only while signed in as a principal in the organization's management account. + The organization must have all features enabled. For more information, see [ Enabling all features in your organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_support-all-features.html) in the *AWS Organizations User Guide*. **Important** You must enable sharing with AWS Organizations by using the AWS RAM console or the [enable-sharing-with-aws-organization](https://docs.aws.amazon.com/cli/latest/reference/ram/enable-sharing-with-aws-organization.html) AWS CLI command. This ensures that the `AWSServiceRoleForResourceAccessManager` service-linked role is created. If you enable trusted access with AWS Organizations by using the AWS Organizations console or the [ enable-aws-service-access](https://docs.aws.amazon.com/cli/latest/reference/organizations/enable-aws-service-access.html) AWS CLI command, the `AWSServiceRoleForResourceAccessManager` service-linked role isn't created, and you can't share resources within your organization. ------ #### [ Console ] **To enable resource sharing within your organization** 1. Open the **[Settings](https://console.aws.amazon.com/ram/home#Settings:)** page in the AWS RAM console. 1. Choose **Enable sharing with AWS Organizations**, and then choose **Save settings**. ------ #### [ AWS CLI ] **To enable resource sharing within your organization** Use the [enable-sharing-with-aws-organization](https://docs.aws.amazon.com/cli/latest/reference/ram/enable-sharing-with-aws-organization.html) command. This command can be used in any AWS Region, and it enables sharing with AWS Organizations in all Regions in which AWS RAM is supported. ``` $ aws ram enable-sharing-with-aws-organization { "returnValue": true } ``` ------ ## Create a resource share To share resources that you own, create a resource share. Here's an overview of the process: 1. Add the resources that you want to share. 1. For each resource type that you include in the share, specify the [managed permission](getting-started-terms-and-concepts.md#term-managed-permission) to use for that resource type. + You can choose from one of the available AWS managed permissions, an existing customer managed permission, or create a new customer managed permission. + AWS managed permissions are created by AWS to cover standard use cases. + Customer managed permissions allow you to tailor your own managed permissions to meet your security and business needs. **Note** If the selected managed permission has multiple versions, then AWS RAM automatically attaches the default version. You can attach ***only*** the version that is designated as the default. 1. Specify the principals that you want to have access to the resources. **Considerations** + If you later need to delete an AWS resource that you included in a share, we recommend that you first either remove the resource from any resource share that includes it, or delete the resource share. + The resource types that you can include in a resource share are listed at [Shareable AWS resources](shareable.md). + You can share a resource only if you [own](getting-started-terms-and-concepts.md#term-sharing-account) it. You can't share a resource that's shared with you. + AWS RAM is a Regional service. When you share a resource with principals in other AWS accounts, those principals must access each resource from the same AWS Region that it was created in. For supported global resources, you can access those resources from any AWS Region that's supported by that resource's service console and tools. You can view such resource shares and their global resources in the AWS RAM console and tools only in the designated home Region, US East (N. Virginia), `us-east-1`. For more information about AWS RAM and global resources, see [Sharing Regional resources compared to global resources](working-with-regional-vs-global.md). + If the account you're sharing from is part of an organization in AWS Organizations and sharing within your organization is enabled, any principals in the organization that you share with are automatically granted access to the resource shares without the use of invitations. A principal in an account with whom you share outside of the context of an organization receives an invitation to join the resource share and is granted access to the shared resources only after they accept the invitation. + If you share with a service principal, you can't associate any other principals with the resource share. + If the sharing is between accounts or principals that are part of an organization, then any changes to organization membership dynamically affect access to the resource share. + If you add an AWS account to the organization or an OU that has access to a resource share, then that new member account automatically gets access to the resource share. The administrator of the account you shared with can then grant individual principals in that account access to the resources in that share. + If you remove an account from the organization or an OU that has access to a resource share, then any principals in that account automatically lose access to resources that were accessed through that resource share. + If you shared directly with a member account or with IAM roles or users in the member account and then remove that account from the organization, then any principals in that account lose access to the resources that were accessed through that resource share. **Important** When you share with an organization or an OU, and that scope includes the account that owns the resource share, all principals in the sharing account automatically get access to the resources in the share. The access granted is defined by the managed permissions associated with the share. This is because the resource-based policy that AWS RAM attaches to each resource in the share uses `"Principal": "*"`. For more information, see [Implications of using "Principal": "\$1" in a resource-based policy](getting-started-terms-and-concepts.md#term-principal-star). Principals in the other consuming accounts don't immediately get access to the share's resources. The other accounts' administrators must first attach identity-based permission policies to the appropriate principals. Those policies must grant `Allow` access to the ARNs of individual resources in the resource share. The permissions in those policies can't exceed those specified in the managed permission associated with the resource share. + You can add only the organization your account is a member of, and OUs from that organization to your resource shares. You can't add OUs or organizations from outside your own organization to a resource share as principals. However, you can add individual AWS accounts or, for supported services, IAM roles and users from outside your organization as principals to a resource share. **Note** Not all resource types can be shared with IAM roles and users. For information about resources that you can share with these principals, see [Shareable AWS resources](shareable.md). + For the following resource types you have seven days to accept the invitation to join the share for the following resource types. If you don't accept the invitation before it expires, the invitation is automatically declined. **Important** For shared resource types **not** on the following list, you have **12 hours** to accept the invitation to join the resource share. After 12 hours, the invitation expires and the end user principal in the resource share is disassociated. The invitation can no longer be accepted by end users. + Amazon Aurora – DB clusters + Amazon EC2 – capacity reservations and dedicated hosts + AWS License Manager – License configurations + AWS Outposts – Local gateway route tables, outposts, and sites + Amazon Route 53 – Forwarding rules + Amazon VPC – Customer-owned IPv4 addresses, prefix lists, subnets, traffic mirror targets, transit gateways, transit gateway multicast domains ------ #### [ Console ] **To create a resource share** 1. Open the [AWS RAM console](https://console.aws.amazon.com/ram/home). 1. Because AWS RAM resource shares exist in specific AWS Regions, choose the appropriate AWS Region from the dropdown list in the upper-right corner of the console. To see resource shares that contain global resources, you must set the AWS Region to US East (N. Virginia), (`us-east-1`). For more information about sharing global resources, see [Sharing Regional resources compared to global resources](working-with-regional-vs-global.md). If you want to include global resources in the resource share, then you must choose the designated home Region, US East (N. Virginia), `us-east-1`. 1. If you're new to AWS RAM, choose **Create a resource share** from the home page. Otherwise, choose **Create resource share** from the **[Shared by me : Resource shares](https://console.aws.amazon.com/ram/home#OwnedResourceShares:)** page. 1. In **Step 1: Specify resource share details**, do the following: 1. For **Name**, enter a descriptive name for the resource share. The name can contain alphabetic characters, numbers, spaces, periods (.), and hyphens (-). It must be fewer than 256 characters. 1. Under **Resources**, choose resources to add to the resource share as follows: + For **Select resource type**, choose the type of resource to share. This filters the list of shareable resources to only those resources of the selected type. + In the resulting list of resources, select the checkboxes next to the individual resources that you want to share. The selected resources move under **Selected resources**. If you're sharing resources that are associated with a specific availability zone, then using the Availability Zone ID (AZ ID) helps you determine the relative location of these resources across accounts. For more information, see [Availability Zone IDs for your AWS resources](working-with-az-ids.md). 1. (Optional) To [attach tags](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html) to the resource share, under **Tags**, enter a tag key and value. Add others by choosing **Add new tag**. Repeat this step as needed. These tags apply to only the resource share itself, not to the resources in the resource share. 1. Choose **Next**. 1. In **Step 2: Associate a managed permission with each resource type**, you can choose to associate a managed permission created by AWS with the resource type, choose an existing customer managed permission, or you can create your own customer managed permission for supported resource types. For more information, see [Types of managed permissions](security-ram-permissions.md#permissions-types). Choose **Create customer managed permission** to construct a customer managed permission that meets the requirements of your sharing use case. For more information see [Create a customer managed permission](create-customer-managed-permissions.md#create_cmp). After completing the process, choose ![\[Refresh icon\]](http://docs.aws.amazon.com/ram/latest/userguide/images/refresh_icon.PNG) and then you can select your new customer managed permission from the **Managed permissions** dropdown list. **Note** If the selected managed permission has multiple versions, then AWS RAM automatically attaches the default version. You can attach ***only*** the version designated as the default. To display the actions that the managed permission allows, expand **View the policy template for this managed permission**. 1. Choose **Next**. 1. In **Step 3: Grant access to principals**, do the following: 1. By default, **Allow sharing with anyone** is selected, which means that, for those resource types that support it, you can share resources with AWS accounts that are outside of your organization. This doesn't affect resource types that can be shared *only* within an organization, such as Amazon VPC subnets. You can also share some [supported resource types](shareable.md) with IAM roles and users. To restrict resource sharing to only accounts and principals in your organization, choose **Allow sharing only within your organization**. 1. For **Principals**, do the following: + To add the organization, an organizational unit (OU), or an AWS account that is part of an organization, turn on **Display organizational structure**. This displays a tree view of your organization. Then, select the checkbox next to each principal that you want to add. **Important** When you share with an organization or an OU, and that scope includes the account that owns the resource share, all principals in the sharing account automatically get access to the resources in the share. The access granted is defined by the managed permissions associated with the share. This is because the resource-based policy that AWS RAM attaches to each resource in the share uses `"Principal": "*"`. For more information, see [Implications of using "Principal": "\$1" in a resource-based policy](getting-started-terms-and-concepts.md#term-principal-star). Principals in the other consuming accounts don't immediately get access to the share's resources. The other accounts' administrators must first attach identity-based permission policies to the appropriate principals. Those policies must grant `Allow` access to the ARNs of individual resources in the resource share. The permissions in those policies can't exceed those specified in the managed permission associated with the resource share. + If you select the organization (the ID begins with `o-`), then principals in all AWS accounts in the organization can access the resource share. + If you select an OU (the ID begins with `ou-`), then principals in all AWS accounts in that OU and its child OUs can access the resource share. + If you select an individual AWS account, then only principals in that account can access the resource share. **Note** The **Display organizational structure **toggle appears only if sharing with AWS Organizations is enabled and you're signed in to the management account for the organization. You can't use this method to specify an AWS account outside your organization, or an IAM role or user. Instead, you must turn off **Display organizational structure** and use the drop down list and text box to enter the ID or ARN. + To specify a principal by ID or ARN, including principals that are outside of the organization, then for each principal, select the principal type. Next, enter the ID (for an AWS account, organization, or OU) or ARN (for an IAM role or user), and then choose **Add**. The available principal types and ID and ARN formats are as follows: + **AWS account** – To add an AWS account, enter the 12-digit account ID. For example: `123456789012` + **Organization** – To add all of the AWS accounts in your organization, enter the ID of the organization. For example: `o-abcd1234` + **Organizational unit (OU)** – To add an OU, enter the ID of the OU. For example: `ou-abcd-1234efgh` + **IAM role** – To add an IAM role, enter the ARN of the role. Use the following syntax: `arn:partition:iam::account:role/role-name` For example: `arn:aws:iam::123456789012:role/MyS3AccessRole` **Note** To obtain the unique ARN for an IAM role, [view the list of roles in the IAM console](https://console.aws.amazon.com/iamv2/home?#/roles), use the [get-role](https://docs.aws.amazon.com/cli/latest/reference/iam/get-role.html) AWS CLI command or the [GetRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetRole.html) API action. + **IAM user** – To add an IAM user, enter the ARN of the user. Use the following syntax: `arn:partition:iam::account:user/user-name` For example: `arn:aws:iam::123456789012:user/bob` **Note** To obtain the unique ARN for an IAM user, [view the list of users in the IAM console](https://console.aws.amazon.com/iamv2/home?#/users), use the [https://docs.aws.amazon.com/cli/latest/reference/iam/get-user.html](https://docs.aws.amazon.com/cli/latest/reference/iam/get-user.html) AWS CLI command, or the [https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetUser.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetUser.html) API action. + **Service principal** – To add a service principal, choose **Service principal** from the **Select principal type** dropbox. Enter the AWS service principal's name. Use the following syntax: + `service-id.amazonaws.com` For example: `pca-connector-ad.amazonaws.com` 1. For **Selected principals**, verify that the principals you specified appear in the list. 1. Choose **Next**. 1. In **Step 4: Review and create**, review the configuration details for your resource share. To change the configuration for any step, choose the link that corresponds to the step you want to go back to and make the required changes. 1. After you finish reviewing the resource share, choose **Create resource share**. It can take a few minutes for the resource and principal associations to complete. Allow this process to complete before you try to use the resource share. 1. You can add and remove resources and principals or apply custom tags to your resource share at any time. You can change the managed permission for resource types that are included in your resource share, for those types that support more than the default managed permission. You can delete your resource share when you no longer want to share the resources. For more information, see [Share AWS resources owned by you](working-with-sharing.md). ------ #### [ AWS CLI ] **To create a resource share** Use the [https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command. The following command creates a resource share that is shared with all of the AWS accounts in the organization. The share contains an AWS License Manager license configuration, and it grants the default managed permissions for that resource type. **Note** If you want to use a customer managed permission with a resource type in this resource share, you can either use an existing customer managed permission or create a new customer managed permission. Make note of the ARN for the customer managed permission, and then create the resource share. For more information, see [Create a customer managed permission](create-customer-managed-permissions.md#create_cmp). ``` $ aws ram create-resource-share \ --region us-east-1 \ --name MyLicenseConfigShare \ --permission-arns arn:aws:ram::aws:permission/AWSRAMDefaultPermissionLicenseConfiguration \ --resource-arns arn:aws:license-manager:us-east-1:123456789012:license-configuration:lic-abc123 \ --principals arn:aws:organizations::123456789012:organization/o-1234abcd { "resourceShare": { "resourceShareArn": "arn:aws:ram:us-east-1:123456789012:resource-share/12345678-abcd-09876543", "name": "MyLicenseConfigShare", "owningAccountId": "123456789012", "allowExternalPrincipals": true, "status": "ACTIVE", "creationTime": "2021-09-14T20:42:40.266000-07:00", "lastUpdatedTime": "2021-09-14T20:42:40.266000-07:00" } } ``` ------ # Using shared AWS resources To start using resources that were shared with your account using AWS Resource Access Manager, complete the following tasks. **Topics** + [ ## Respond to the resource share invitation ](#getting-started-shared-respond-invitation) + [ ## Use the resources that are shared with you ](#getting-started-shared-use-resources) ## Respond to the resource share invitation If you receive an invitation to join a resource share, you must accept it to gain access to the shared resources. Invitations aren't used in the following scenarios: + If you're part of an organization in AWS Organizations and sharing in your organization is enabled, then principals in the organization automatically get access to the shared resources without invitations. + If you share with the AWS account that owns the resource, then the principals in that account automatically get access to the shared resources without invitations. ------ #### [ Console ] **To respond to invitations** 1. Open the **[Shared with me : Resource shares](https://console.aws.amazon.com/ram/home#SharedResourceShares:)** page in the AWS RAM console. **Note** A resource share is visible in only the AWS Region in which it was created. If an expected resource share doesn't appear in the console, you might need to switch to a different AWS Region using the drop-down control in the upper-right corner. 1. Review the list of resource shares to which you have been granted access. The **Status** column indicates your current participation status for the resource share. The `Pending` status indicates that you have been added to a resource share, but you have not yet accepted or rejected the invitation. 1. To respond to the resource share invitation, select the resource share ID and choose **Accept resource share** to accept the invitation, or **Reject resource share** to decline the invitation. If you reject the invitation, you don't get access to the resources. If you accept the invitation, you gain access to the resources. ------ #### [ AWS CLI ] To start, get a list of the resource share invitations that are available to you. The following example command was run in the `us-west-2` Region, and shows one resource share is available in the `PENDING` state. ``` $ aws ram get-resource-share-invitations { "resourceShareInvitations": [ { "resourceShareInvitationArn": "arn:aws:ram:us-west-2:111122223333:resource-share-invitation/1234abcd-ef12-9876-5432-aaaaaa111111", "resourceShareName": "MyNewResourceShare", "resourceShareArn": "arn:aws:ram:us-west-2:111122223333:resource-share/1234abcd-ef12-9876-5432-bbbbbb222222", "senderAccountId": "111122223333", "receiverAccountId": "444455556666", "invitationTimestamp": "2021-09-15T15:00:32.568000-07:00", "status": "PENDING" } ] } ``` You can use the Amazon Resource Name (ARN) of the invitation from the previous command as a parameter in the next command to accept that invitation. ``` $ aws ram accept-resource-share-invitation \ --resource-share-invitation-arn arn:aws:ram:us-west-2:111122223333:resource-share-invitation/1234abcd-ef12-9876-5432-aaaaaa111111 { "resourceShareInvitation": { "resourceShareInvitationArn": "arn:aws:ram:us-west-2:111122223333:resource-share-invitation/1234abcd-ef12-9876-5432-aaaaaa111111", "resourceShareName": "MyNewResourceShare", "resourceShareArn": "arn:aws:ram:us-west-2:111122223333:resource-share/1234abcd-ef12-9876-5432-bbbbbb222222", "senderAccountId": "111122223333", "receiverAccountId": "444455556666", "invitationTimestamp": "2021-09-15T15:14:12.580000-07:00", "status": "ACCEPTED" } } ``` The output shows that the `status` has changed to `ACCEPTED`. The resources that are included in that resource share are now available to principals in the accepting account. ------ ## Use the resources that are shared with you After you accept the invitation to join a resource share, you can perform specific actions on the shared resources. These actions vary by resource type. For more information, see [Shareable AWS resources](shareable.md). The resources are available directly in each resource's service console and API/CLI operations. If the resource is regional, then you must use the correct AWS Region in the service console or API/CLI command. If the resource is global, then you must use the designated home Region, US East (N. Virginia), `us-east-1` To view the resource in AWS RAM, you must open the AWS RAM console to the AWS Region that the resource share was created in.