# Cross-account data sharing in Lake Formation Lake Formation cross-account capabilities allow users to securely share distributed data lakes across multiple AWS accounts, AWS organizations or directly with IAM principals in another account providing fine-grained access to the Data Catalog metadata and underlying data. Large enterprises typically use multiple AWS accounts, and many of those accounts might need access to a data lake managed by a single AWS account. Users and AWS Glue extract, transform, and load (ETL) jobs can query and join tables across multiple accounts and still take advantage of Lake Formation table-level and column-level data protections. When you grant Lake Formation permissions on a Data Catalog resource to an external account or directly to an IAM principal in another account, Lake Formation uses the AWS Resource Access Manager (AWS RAM) service to share the resource. If the grantee account is in the same organization as the grantor account, the shared resource is available immediately to the grantee. If the grantee account is not in the same organization, AWS RAM sends an invitation to the grantee account to accept or reject the resource grant. Then, to make the shared resource available, the data lake administrator in the grantee account must use the AWS RAM console or AWS CLI to accept the invitation. Lake Formation supports sharing Data Catalog resources with external accounts in hybrid access mode. Hybrid access mode provides the flexibility to selectively enable Lake Formation permissions for databases and tables in your AWS Glue Data Catalog.
 With the Hybrid access mode, you now have an incremental path that allows you to set Lake Formation permissions for a specific set of users without interrupting the permission policies of other existing users or workloads. For more information, see [Hybrid access mode](hybrid-access-mode.md). **Direct cross-account share** Authorized principals can share resources explicitly with an IAM principal in an external account. This feature is useful when an account owner wants to have control over who in the external account can access the resources. The permissions the IAM principal receives will be a union of direct grants and the account level grants that is cascaded down to the principals. Only the recipient of the permission grant can view the direct cross-account grants. The principal who receives the resource share cannot share the resource with other principals. **Methods for sharing Data Catalog resources** With a single Lake Formation grant operation, you can grant cross-account permissions on the following Data Catalog resources. + A database + An individual table (with optional column filtering) + A few selected tables + All tables in a database (by using the All Tables wildcard) There are two options for sharing your databases and tables with another AWS account or IAM principals in another account. + Lake Formation tag-based access control (LF-TBAC) (recommended) Lake Formation tag-based access control is an authorization strategy that defines permissions based on attributes. You can use tag-based access control to share Data Catalog resources (databases, tables, and columns) with external IAM principals, AWS accounts, Organizations and organizational units (OUs). In Lake Formation, these attributes are called LF-tags. For more information, see [Managing a data lake using Lake Formation tag-based access control](https://docs.aws.amazon.com/lake-formation/latest/dg/managing-dl-tutorial.html). **Note** The LF-TBAC method of granting Data Catalog permissions use AWS Resource Access Manager for cross-account grants. Lake Formation now supports granting cross-account permissions to Organizations and organizational units using LF-TBAC method. To enable this capability, you need to update the **Cross account version settings** to **Version 3** or above. For more information, see [Updating cross-account data sharing version settings](optimize-ram.md). + Lake Formation named resources The Lake Formation cross-account data sharing using named resource method allows you to grant Lake Formation permissions with a grant option on Data Catalog tables and databases to external AWS accounts, IAM principals, organizations, or organizational units. The grant operation automatically shares those resources. **Note** You can also allow the AWS Glue crawler to access a data store in a different account using Lake Formation credentials. For more information, see [Cross-account crawling](https://docs.aws.amazon.com/glue/latest/dg/crawler-configuration.html#cross-account-crawling) in AWS Glue Developer Guide. Integrated services such as Athena and Amazon Redshift Spectrum require resource links to be able to include shared resources in queries. For more information about resource links, see [How resource links work in Lake Formation](resource-links-about.md). For considerations and limitation, see [Cross-account data sharing best practices and considerations](cross-account-notes.md). **Topics** + [Prerequisites](cross-account-prereqs.md) + [Updating cross-account data sharing version settings](optimize-ram.md) + [Sharing Data Catalog tables and databases across AWS accounts or IAM principals from external accounts](cross-account-data-share-steps.md) + [Granting permissions on a database or table shared with your account](regranting-shared-resources.md) + [Granting resource link permissions](granting-link-permissions.md) + [Accessing the underlying data of a shared table](cross-account-read-data.md) + [Cross-account CloudTrail logging](cross-account-logging.md) + [Managing cross-account permissions using both AWS Glue and Lake Formation](hybrid-cross-account.md) + [Viewing all cross-account grants using the GetResourceShares API operation](cross-account-getresourcepolicies.md) **Related topics** [Overview of Lake Formation permissions](lf-permissions-overview.md) [Accessing and viewing shared Data Catalog tables and databases](viewing-shared-resources.md) [Creating resource links](creating-resource-links.md) [Troubleshooting cross-account access](troubleshooting.md#trouble-cross-account) # Prerequisites Before your AWS account can share Data Catalog resources (catalogs, databases and tables) with another account or principals in another account, and before you can access the resources shared with your account, the following prerequisites must be met. **General cross-account data sharing requirements** + To share Data Catalog databases and tables in hybrid access mode and share objects in the federated catalogs, you need to update the **Cross account version settings** to **Version 4**. + Before granting cross-account permissions on a Data Catalog resource, you must revoke all Lake Formation permissions from the `IAMAllowedPrincipals` group for the resource. If the calling principal has cross account permissions to access a resource and the `IAMAllowedPrincipals` permission exists on the resource, then Lake Formation throws `AccessDeniedException`. This requirement is applicable only when you register the underlying data location in Lake Formation mode. If you register the data location in hybrid mode, the `IAMAllowedPrincipals` group permissions can exist on the shared database or table. + For databases that contain tables that you intend to share, you must prevent new tables from having a default grant of `Super` to `IAMAllowedPrincipals`. On the Lake Formation console, edit the database and turn off **Use only IAM access control for new tables in this database** or enter the following AWS CLI command, replacing `database` with the name of the database. If the underlying data location is registered in hybrid access mode, you don't need to change this default setting. In hybrid access mode, Lake Formation allows you to selectively enforce Lake Formation permissions and IAM permissions policies for Amazon S3 and AWS Glue on the same resource. ``` aws glue update-database --name database --database-input '{"Name":"database","CreateTableDefaultPermissions":[]}' ``` + To grant cross-account permissions, the grantor must have the required AWS Identity and Access Management (IAM) permissions on AWS Glue and AWS RAM service. The AWS managed policy `AWSLakeFormationCrossAccountManager` grants the required permissions. Data lake administrators in accounts that receive resource shares using AWS RAM must have the following additional policy. It allows the administrator to accept AWS RAM resource share invitations. It also allows the administrator to enable resource sharing with organizations. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ram:AcceptResourceShareInvitation", "ram:RejectResourceShareInvitation", "ec2:DescribeAvailabilityZones", "ram:EnableSharingWithAwsOrganization" ], "Resource": "*" } ] } ``` ------ + If you want to share Data Catalog resources with AWS Organizations or organizational units, sharing with organizations must be enabled in AWS RAM. For information on how to enable sharing with organizations, see [Enable sharing with AWS organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-orgs) in the *AWS RAM User Guide*. You must have the `ram:EnableSharingWithAwsOrganization` permission to enable sharing with organizations. + To share resources directly with an IAM principal in another account, you need to update the **Cross account version settings** to **Version 3**. This setting is available on the **Data catalog settings** page. If you are using **Version 1**, see instructions to update the setting [Updating cross-account data sharing version settings](optimize-ram.md). + You cannot share Data Catalog resources encrypted with AWS Glue service managed key with another account. You can share only Data Catalog resources encrypted with customer's encryption key, and the account receiving the resource share must have permissions on the Data Catalog encryption key to decrypt the objects. **Cross-account data sharing using LF-TBAC requirements** + To share Data Catalog resources with AWS Organizations and organizational units (OUs), you need to update the **Cross account version settings** to **Version 3**or above. + To share Data Catalog resources with version 3 of the **Cross account version settings**, the grantor requires to have the IAM permissions defined in the AWS managed policy `AWSLakeFormationCrossAccountManager` in your account. + If you are using version 1 or version 2 of the **Cross account version settings**, you must have a Data Catalog resource policy (`glue:PutResourcePolicy`) that enables LF-TBAC. For more information, see [Managing cross-account permissions using both AWS Glue and Lake Formation](hybrid-cross-account.md). + If you're currently using an AWS Glue Data Catalog resource policy to share resources, and you want to grant cross-account permissions using version 3 of the **Cross account version settings**, you must add the `glue:ShareResource` permission in the Data Catalog Settings using the `glue:PutResourcePolicy` API operation as shown in the [Managing cross-account permissions using both AWS Glue and Lake Formation](hybrid-cross-account.md) section. This policy is not required if your account has made no cross-account grants using the AWS Glue Data Catalog resource policy (version 1 and version 2 use `glue:PutResourcePolicy` permission) to grant cross-account access. ``` { "Effect": "Allow", "Action": [ "glue:ShareResource" ], "Principal": {"Service": [ "ram.amazonaws.com" ]}, "Resource": [ "arn:aws:glue:::table/*/*", "arn:aws:glue:::database/*", "arn:aws:glue:::catalog" ] } ``` + If your account has made cross-account shares using AWS Glue Data Catalog resource policy, and you are currently using named resource method or LF-TBAC with **Cross account settings** version 3 to share resources, which uses AWS RAM to share resources, you must set the `EnableHybrid` argument to `'true'` when you invoke the `glue:PutResourcePolicy` API operation. For more information, see [Managing cross-account permissions using both AWS Glue and Lake Formation](hybrid-cross-account.md). **Setup required in each account that accesses the shared resource** + If you are sharing resources with AWS accounts, at least one user in the consumer account must be a data lake administrator to view shared resources. For information on how to create a data lake administrator, see [Create a data lake administrator](initial-lf-config.md#create-data-lake-admin). The data lake administrator can grant Lake Formation permissions on the shared resources to other principals in the account. Other principals can't access shared resources until the data lake administrator grants them permissions on the resources. + Integrated services such as Athena and Redshift Spectrum require resource links to be able to include shared resources in queries. Principals need to create a resource link in their Data Catalog to a shared resource from another AWS account. For more information about resource links, see [How resource links work in Lake Formation](resource-links-about.md). + When a resource is shared directly with an IAM principal, to query the table using Athena, the principal needs to create a resource link. To create a resource link, the principal needs the Lake Formation `CREATE_TABLE` or `CREATE_DATABASE` permission, and the `glue:CreateTable` or `glue:CreateDatabase` IAM permission. If the producer account shares a different table under the same database with the same or another principal, that principal can immediately query the table. **Note** For the data lake administrator and for principals whom the data lake administrator has granted permissions to, shared resources appear in the Data Catalog as if they are local (owned) resources. Extract, transform, and load (ETL) jobs can access the underlying data of shared resources. For shared resources, the **Tables** and **Databases** pages on the Lake Formation console display the owner's account ID. When the underlying data of a shared resource is accessed, CloudTrail log events are generated in both the shared resource recipient's account and the resource owner's account. The CloudTrail events can contain the ARN of the principal that accessed the data, but only if the recipient account opts in to include the principal ARN in the logs. For more information, see [Cross-account CloudTrail logging](cross-account-logging.md). # Updating cross-account data sharing version settings From time to time, AWS Lake Formation updates the cross-account data sharing settings to distinguish the changes made to the AWS RAM usage and to support updates made to the cross-account data sharing feature. When Lake Formation does this, it creates a new version of the **Cross account version settings**. ## Main differences between cross-account version settings For more information about how cross-account data sharing works under different **Cross account version settings**, see the following sections. **Note** To share data with another account, the grantor must have `AWSLakeFormationCrossAccountManager` managed IAM policy permissions. This is a prerequisite for all versions. Updating the **Cross account version settings** does not impact the permissions the recipient has on shared resources. This is applicable when updating from version 1 to version 2, version 2 to version 3, and version 1 to version 3. See the considerations listed below when updating versions. **Version 1** *Named resource method: *Maps each cross-account Lake Formation permission grant to one AWS RAM resource share. User (grantor role or principal) does not require additional permissions. *LF-TBAC method: *Cross-account Lake Formation permission grants don't use AWS RAM to share data. User must have `glue:PutResourcePolicy` permission. *Benefits from updating versions: *Initial version - not applicable. *Considerations when updating versions: *Initial version - not applicable **Version 2** *Named resource method: * Optimizes the number of AWS RAM resource shares by mapping multiple cross-account permission grants with one AWS RAM resource share. User does not require additional permissions. *LF-TBAC method: *Cross-account Lake Formation permission grants don't use AWS RAM to share data. User must have `glue:PutResourcePolicy` permission. *Benefits from updating versions: *Scalable cross-account setup by optimal utilization of AWS RAM capacity. *Considerations when updating versions: *Users who want to grant cross-account Lake Formation permissions must have the permissions in the `AWSLakeFormationCrossAccountManager` AWS managed policy. Otherwise, you need to have `ram:AssociateResourceShare` and `ram:DisassociateResourceShare` permissions to successfully share resources with another account. **Version 3** *Named resource method: * Optimizes the number of AWS RAM resource shares by mapping multiple cross-account permission grants with one AWS RAM resource share. User does not require additional permissions. *LF-TBAC method: * Lake Formation uses AWS RAM for cross-account grants. User must add glue:ShareResource statement to the `glue:PutResourcePolicy` permission. The recipient must accept resource share invitations from AWS RAM. *Benefits from updating versions: *Supports the following capabilities: + Allows sharing resources explicitly with an IAM principal in an external account. For more information, see [Granting permissions on Data Catalog resources](granting-catalog-permissions.md). + Enables cross-account shares using LF-TBAC method to Organizations or organizational units (OUs). + Removes the overhead of maintaining additional AWS Glue policies for cross-account grants. *Considerations when updating versions:* When you use LF-TBAC method to share resources, if the grantor uses a version lower than version 3, and the recipient is using version 3 or higher, the grantor receives the following error message: "Invalid cross account grant request. Consumer account has opt-in to cross account version: v3. Please update `CrossAccountVersion` in `DataLakeSetting` to minimal version v3 (Service: AmazonDataCatalog; Status Code: 400; Error Code: InvalidInputException)". However, if the grantor uses version 3 and the recipient is using version 1 or version 2, the cross-account grants using LF-Tags go through successfully. Cross-account grants made using the named resource method are compatible across different versions. Even if the grantor account is using an older version (version 1 or 2) and the recipient account is using a newer version (version 3 or higher), the cross-account access functionality operates seamlessly without any compatibility issues or errors. To share resources directly with IAM principals in another account, only the grantor needs to use version 3. Cross-account grants made using LF-TBAC method require users to have an AWS Glue Data Catalog resource policy in the account. When you update to version 3, LF-TBAC grants uses AWS RAM. To allow AWS RAM based cross-account grants to succeed, you must add the `glue:ShareResource` statement to your existing Data Catalog resource policies as shown in the [Managing cross-account permissions using both AWS Glue and Lake Formation](hybrid-cross-account.md) section. **Version 4** The grantor needs version 4 or higher to share Data Catalog resources in hybrid access mode or share objects in a federated catalog. **Version 5** Cross Account Version 5 enhances cross-account resource sharing enabling you to share unlimited number of tables to another account, eliminating previous resource association limits per resource type. To get started, upgrade to cross-account version 5 through the Lake Formation console or API. Any new cross-account permission grants will automatically use wildcard patterns in the resource share instead of individual resource associations. All existing cross-account shares continue to function, and all existing Lake Formation APIs remain compatible. *Benefits from updating versions: *Cross-account v5 enhances cross-account sharing, allowing you to share hundreds of thousands of tables across accounts. *Considerations when updating versions: *New grants after version 5 upgrade will add wildcard resource patterns to existing AWS Resource Manager resource shares or create new shares with wildcard patterns. Once upgraded to version 5, downgrade is not supported. ## Optimize AWS RAM resource shares New versions (version 2 and above) of cross-account grants optimally utilize AWS RAM capacity to maximize cross account usage. When you share a resource with an external AWS account or an IAM principal, Lake Formation may create a new resource share or associate the resource with an existing share. By associating with existing shares, Lake Formation reduces the number of resource share invitations a consumer needs to accept. Version 5 further optimizes RAM usage by using wildcard-based resource patterns instead of individual resource associations, thereby significantly reducing resource associations per resource share. ## Enable AWS RAM shares via TBAC or share resources directly to principals To share resources directly with IAM principals in another account or to enable TBAC cross-account shares to Organizations or organizational units, you need to update the **Cross account version settings** to version 3. For more information about AWS RAM resource limits, see [Cross-account data sharing best practices and considerations](cross-account-notes.md). ### Required permissions for updating cross-account version settings If a cross-account permission grantor has `AWSLakeFormationCrossAccountManager` managed IAM policy permissions, then there is no extra permission setup required for the cross-account permission grantor role or principal. However, if the cross-account grantor is not using the managed policy, then the grantor role or principal should have following IAM permissions granted for the new version of the cross-account grant to be successful. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor1", "Effect": "Allow", "Action": [ "ram:AssociateResourceShare", "ram:DisassociateResourceShare", "ram:GetResourceShares" ], "Resource": "*", "Condition": { "StringLike": { "ram:ResourceShareName": "LakeFormation*" } } } ] } ``` ------ ## To enable the new version Follow these steps to update **Cross account version settings** through the AWS Lake Formation console or the AWS CLI. ------ #### [ Console ] 1. Choose **Version 2**, **Version 3**, **Version 4**, or **Version 5** under **Cross account version settings** on the **Data catalog settings** page. If you select **Version 1**, Lake Formation will use the default resource sharing mode. ![\[The screen shows the permissions for all LF-Tags in the account.\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/cross-account-version-setting.png) 1. Choose **Save**. ------ #### [ AWS Command Line Interface (AWS CLI) ] Use the `put-data-lake-settings` AWS CLI command to set the `CROSS_ACCOUNT_VERSION` parameter. Accepted values are 1, 2, 3, 4, and 5. ``` aws lakeformation put-data-lake-settings --region us-east-1 --data-lake-settings file://settings { "DataLakeAdmins": [ { "DataLakePrincipalIdentifier": "arn:aws:iam::111122223333:user/test" } ], "CreateDatabaseDefaultPermissions": [], "CreateTableDefaultPermissions": [], "Parameters": { "CROSS_ACCOUNT_VERSION": "3" } } ``` ------ **Important** Once you choose **Version 2** or **Version 3**, all new **named resource** grants will go through the new cross-account grant mode. To optimally use AWS RAM capacity for your existing cross-account shares, we recommend you to revoke the grants that were made with the older version, and re-grant in the new mode. # Sharing Data Catalog tables and databases across AWS accounts or IAM principals from external accounts This section includes instructions on how to grant cross-account permissions on Data Catalog resources to an external AWS account, IAM principal, AWS organization, or organizational unit. The grant operation automatically shares those resources. **Topics** + [Data sharing using tag-based access control](cross-account-TBAC.md) + [Cross-account data sharing using the named resource method](cross-account-named-resource.md) # Data sharing using tag-based access control AWS Lake Formation tag-based access control (LF-TBAC) is an authorization strategy that defines permissions based on attributes. The following steps explain how to grant cross-account permissions by using LF-Tags. **Set up required on the producer/grantor account** 1. Add LF-Tags. 1. Sign in to Lake Formation console as a data lake administrator or a LF-Tag creator. 1. In the left navigation bar, choose **Permissions**, and **LF-Tags and permissions**. 1. Choose **Add LF-Tag**. For detailed instructions to create LF-Tags, see [Creating LF-Tags](TBAC-creating-tags.md). 1. Grant **Describe** and/or **Associate** permissions **LF-Tag key-value** pairs to IAM principals in your account or external accounts. Granting permissions on **LF-Tag key-value** pairs enables the principals to view the LF-Tags, and assign them to Data Catalog resources (databases, tables, and columns). 1. Next, the data lake administrator or an IAM principal with **Associate** permission can assign the LF-Tag to databases, tables, or columns. For more information, see [Assigning LF-Tags to Data Catalog resources](TBAC-assigning-tags.md). 1. Next, grant data permission to external accounts using LF-Tag expressions. This enables the grantee or recipient of the permissions to access the Data Catalog resource(s) that are tagged with the same key(s) and value(s). 1. In the navigation pane, choose **Permissions** and **Data permissions**. 1. Choose **Grant**. 1. On the **Grant permissions** page, for **Principals**, choose **External accounts**, and enter the grantee AWS account ID or the IAM role of the principal or the Amazon Resource Name (ARN) for the principal (principal ARN) if making a direct cross-account grant to an external principal. You need to press **Enter** after entering the account ID. ![\[The grant permission screen with external account and LF-Tag key-value pairs specified.\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/cross-acct-grant-tags.png) 1. For **LF-Tags or catalog resources**, choose **Resources matched by LF-Tags (recommended)**. 1. Choose the option **LF-Tag key-value pairs** or **Saved LF-Tag expressions** . 1. **If you choose, **LF-Tag key-value pairs**, enter the key and value(s)** of the **LF-Tag** that is associated with the Data Catalog resource being shared with the grantee account. The grantee is granted permissions on the Data Catalog resources that were assigned a matching LF-Tag in the LF-Tag expression. If the LF-Tag expression specifies multiple values per tag key, any one of the tag values can be a match. 1. Choose the database-level or table-level permissions to grant on resources that match the LF-Tag expression. **Important** Because the data lake administrator must grant permissions on shared resources to the principals in the grantee account, you must always grant cross-account permissions with the grant option. For more information, see [Granting LF-Tag permissions using the console](TBAC-granting-tags-console.md). **Note** Principals who receive direct cross-account grants will not have the **Grantable permissions** option. **Set up required on the receiving/grantee account** 1. Sign in to Lake Formation console as a data lake administrator of the consumer account. 1. Next, receive the resource share in the consumer account. 1. Open the AWS RAM console. 1. In the navigation pane, under **Shared with me**, choose **Resource shares**. 1. Select the resource shares, choose **Accept resource share**. 1. When you share a resource with another account, the resource still belongs to the producer account and is not visible within the Athena console. To make the resource visible in the Athena console, you need to create a resource link pointing to the shared resource. For instructions on creating a resource link, see [Creating a resource link to a shared Data Catalog table](create-resource-link-table.md) and [Creating a resource link to a shared Data Catalog database](create-resource-link-database.md) 1. Choose **Databases** or **Tables** under the Data Catalog. 1. On the Databases/Tables page, choose **Create**, **Resource link** . 1. Enter the following information for a database resource link: + **Resource link name** – A unique name for the resource link. + **Destination catalog** – The catalog where you're creating the resource link. + **Shared database Region** – The Region of the database shared with you if you are creating the resource link in a different Region. + **Shared database** – Choose the shared database. + **Shared database’s catalog ID** – Enter the catalog ID for the shared database. 1. Choose **Create**. You can see the newly created resource link in the databases list. Similarly, you can create a resource link to a shared table. 1. Now grant **Describe** permission on the resource link to the IAM principals that you are sharing the resource. 1. On the **Databases/Tables** page, select the resource link, and on the **Actions** menu, choose **Grant**. 1. In the **Grant permissions** section, select **IAM users and roles**. 1. Choose the IAM role that you want to grant access to the resource link. 1. In the **Resource link** permissions section, select **Describe**. 1. Choose **Grant**. 1. Next, grant **LF-Tag key-value permissions** to the principals in the consumer account. You should be able to find the LF-Tags that are shared with you in the consumer account on the Lake Formation console, under **Permissions**, **LF-Tags and permissions**. You can associate tags shared from grantor on resources shared from grantor account that includes: databases, tables, and columns. You can further grant permissions on the resources to other principals. ![\[The screen shows the permissions for LF-Tags in the account.\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/lf-tag-permissions.png) 1. In the navigation pane, under **Permissions**, **Data permissions**, choose **Grant**. 1. On the **Grant permissions** page, choose **IAM users and roles**. 1. Next, choose the IAM users and roles in your account to grant access to the shared databases/tables. 1. Next, for **LF-Tags or catalog resources**, choose **Resources matched by LF-Tags**. 1. Next, choose the key and values of the LF-Tag that is shared with you. 1. Next, choose the database and table permissions that you want to grant to the IAM users and roles. You can also choose **Grantable permissions** that enables the IAM users and roles to grant permissions to other users/roles. 1. Choose **Grant**. 1. You can view the permission grants under **Data permissions** on the Lake Formation console. # Cross-account data sharing using the named resource method You can grant permissions to directly to principals in the another AWS account, or to external AWS accounts or AWS Organizations. Granting Lake Formation permissions to Organizations or organizational units is equivalent to granting the permission to every AWS account in that organization or organizational unit. When you grant permissions to external accounts or organizations, you must include the **Grantable permissions** option. Only the data lake administrator in the external account can access the shared resources until the administrator grants permissions on the shared resources to other principals in the external account. **Note** **Grantable permissions** option is not supported when granting permissions directly to IAM principals from external accounts. Follow instructions in [Granting database permissions using the named resource method](granting-database-permissions.md) to grant cross-account permissions using the named resource method. The following video demonstrates how to share data with an AWS organization using Lake Formation. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/S-Mdcmq6oPM?controls=0&/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/S-Mdcmq6oPM?controls=0&) # Granting permissions on a database or table shared with your account After a Data Catalog resource belonging to another AWS account is shared with your AWS account, as a data lake administrator, you can grant permissions on the shared resource to other principals in your account. You can't, however, grant permissions on the resource to other AWS accounts or organizations. You can use the AWS Lake Formation console, the API, or the AWS Command Line Interface (AWS CLI) to grant the permissions. **To grant permissions on a shared database (named resource method, console)** + Follow the instructions in [Granting database permissions using the named resource method](granting-database-permissions.md). In the **Database** list under **LF-Tags or catalog resources**, ensure that you select the database in the external account, not a resource link for the database. If you don't see the database in the list of databases, ensure that you have accepted the AWS Resource Access Manager (AWS RAM) resource share invitation for the database. For more information, see [Accepting a resource share invitation from AWS RAM](accepting-ram-invite.md). Also, for the `CREATE_TABLE` and `ALTER` permissions, follow the instructions in [Granting data location permissions (same account)](granting-location-permissions-local.md), and be sure to enter the owning account ID in the **Registered account location** field. **To grant permissions on a shared table (named resource method, console)** + Follow the instructions in [Granting table permissions using the named resource method](granting-table-permissions.md). In the **Database** list under **LF-Tags or catalog resources**, ensure that you select the database in the external account, not a resource link for the database. If you don't see the table in the list of tables, ensure that you have accepted the AWS RAM resource share invitation for the table. For more information, see [Accepting a resource share invitation from AWS RAM](accepting-ram-invite.md). Also, for the `ALTER` permission, follow the instructions in [Granting data location permissions (same account)](granting-location-permissions-local.md), and be sure to enter the owning account ID in the **Registered account location** field. **To grant permissions on shared resources (LF-TBAC method, console)** + Follow the instructions in [Granting Data Catalog permissions](granting-catalog-perms-TBAC.md#granting-cat-perms-TBAC-console). In the **LF-Tags or catalog resources** section, grant the exact LF-Tag expression that the external account granted to your account, or a subset of that expression. For example, if an external account granted the LF-Tag expression `module=customers AND environment=production` to your account with the grant option, as a data lake administrator, you can grant that same expression, or `module=customers` or `environment=production` to a principal in your account. You can grant only the same or a subset of the Lake Formation permissions (for example, `SELECT`, `ALTER`, and so on) that were granted on resources through the LF-Tag expression. **To grant permissions on a shared table (named resource method, AWS CLI)** + Enter a command similar to the following. In this example: + Your AWS account ID is 1111-2222-3333. + The account that owns the table and that granted it to your account is 1234-5678-9012. + The `SELECT` permission is being granted on the shared table `pageviews` to user `datalake_user1`. That user is a principal in your account. + The `pageviews` table is in the `analytics` database, which is owned by account 1234-5678-9012. ``` aws lakeformation grant-permissions --principal DataLakePrincipalIdentifier=arn:aws:iam::111122223333:user/datalake_user1 --permissions "SELECT" --resource '{ "Table": {"CatalogId":"123456789012", "DatabaseName":"analytics", "Name":"pageviews"}}' ``` Note that the owning account must be specified in the `CatalogId` property in the `resource` argument. # Granting resource link permissions Follow these steps to grant AWS Lake Formation permissions on one or more resource links to a principal in your AWS account. After you create a resource link, only you can view and access it. (This assumes that **Use only IAM access control for new tables in this database** is not enabled for the database.) To permit other principals in your account to access the resource link, grant at least the `DESCRIBE` permission. **Important** Granting permissions on a resource link doesn't grant permissions on the target (linked) database or table. You must grant permissions on the target separately. You can grant permissions by using the Lake Formation console, the API, or the AWS Command Line Interface (AWS CLI). ------ #### [ console ] **To grant resource link permissions using the Lake Formation console** 1. Do one of the following: + For database resource links, follow the steps in [Granting database permissions using the named resource method](granting-database-permissions.md). to do the following: 1. Select the resource link from the databases list under Data Catalog, **Databases**. 1. Choose **Grant** to open the **Grant permissions** page. 1. Specify principals to grant permissions. 1. The **Catalogs** and **Databases ** fields are populated. + For table resource links, follow the steps in [Granting table permissions using the named resource method](granting-table-permissions.md) to do the following: 1. Select the resource link from the tables list under Data Catalog, **Tables**. 1. Open the **Grant permissions** page. 1. Specify principals. 1. The **Catalogs**, **Databases **, **Tables** fields are populated. 1. Specify principals. 1. Under **Permissions**, select the permissions to grant. Optionally, select grantable permissions. ![\[The Permissions section contains a single tile. The tiles has a group of check boxes for resource link permissions to grant. Check boxes include Drop and Describe. Below that group is another group of the same check boxes for grantable permissions.\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/grant-resource-link-permissions-TBAC.png) 1. Choose **Grant**. ------ #### [ AWS CLI ] **To grant resource link permissions using AWS CLI** + Run the `grant-permissions` command, specifying a resource link as the resource. **Example** This example grants `DESCRIBE` to user `datalake_user1` on the table resource link `incidents-link` in the database `issues` in AWS account 1111-2222-3333. ``` 1. aws lakeformation grant-permissions --principal DataLakePrincipalIdentifier=arn:aws:iam::111122223333:user/datalake_user1 --permissions "DESCRIBE" --resource '{ "Table": {"DatabaseName":"issues", "Name":"incidents-link"}}' ``` ------ **See Also:** [Creating resource links](creating-resource-links.md) [Lake Formation permissions reference](lf-permissions-reference.md) # Accessing the underlying data of a shared table Assume that AWS account A shares a Data Catalog table with account B—for example, by granting `SELECT` with the grant option on the table to account B. For a principal in account B to be able to read the shared table's underlying data, the following conditions must be met: + The data lake administrator in account B must accept the share. (This isn't necessary if accounts A and B are in the same organization or if the grant was made with the Lake Formation tag-based access control method.) + The data lake administrator must re-grant to the principal the Lake Formation `SELECT` permission that account A granted on the shared table. + The principal must have the following IAM permissions on the table, the database that contains it, and the account A Data Catalog. **Note** In the following IAM policy: Replace ** with the AWS account ID of account A. Replace ** with a valid Region. Replace ** with the name of the database in account A that contains the shared table. Replace ** with the name of the shared table. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:GetTable", "glue:GetTables", "glue:GetPartition", "glue:GetPartitions", "glue:BatchGetPartition", "glue:GetDatabase", "glue:GetDatabases" ], "Resource": [ "arn:aws:glue:us-east-1:111122223333:table//
", "arn:aws:glue:us-east-1:111122223333:database/", "arn:aws:glue:us-east-1:111122223333:catalog" ] }, { "Effect": "Allow", "Action": [ "lakeformation:GetDataAccess" ], "Resource": [ "*" ] } ] } ``` ------ **See Also:** [Accepting a resource share invitation from AWS RAM](accepting-ram-invite.md) # Cross-account CloudTrail logging Lake Formation provides a centralized audit trail of all cross-account access to data in your data lake. When a recipient AWS account accesses data in a shared table, Lake Formation copies the CloudTrail event to the owning account's CloudTrail logs. Copied events include queries against the data by integrated services such as Amazon Athena and Amazon Redshift Spectrum, and data accesses by AWS Glue jobs. CloudTrail events for cross-account operations on Data Catalog resources are similarly copied. As a resource owner, if you enable object-level logging in Amazon S3, you can run queries that join S3 CloudTrail events with Lake Formation CloudTrail events to determine the accounts that have accessed your S3 buckets. **Topics** + [Including principal identities in cross-account CloudTrail logs](#cross-account-logging-optin) + [Querying CloudTrail logs for Amazon S3 cross-account access](#cross-account-logging-s3) ## Including principal identities in cross-account CloudTrail logs By default, cross-account CloudTrail events added to the shared resource recipient's logs and copied to resource owner's logs contain only the AWS principal ID of the external account principal—not the human-readable Amazon Resource Name (ARN) of the principal (principal ARN). When sharing resources within trusted boundaries, such as within the same organization or team, you can opt in to include the principal ARN in the CloudTrail events. Resource owner accounts can then track the principals in recipient accounts that access their owned resources. **Important** As a shared resource recipient, to see the principal ARN in events in your own CloudTrail logs, you must opt in to share the principal ARN with the owner account. If the data access occurs through a resource link, two events are logged in the shared resource recipient account: one for the resource link access and one for the target resource access. The event for the resource link access *does* include the principal ARN. The event for the target resource access does not include the principal ARN without the opt-in. The resource link access event is not copied to the owner account. The following is an excerpt from a default cross-account CloudTrail event (without opt-in). The account performing the data access is 1111-2222-3333. This is the log that is shown in both the calling account and the resource owner account. Lake Formation populates logs in both accounts in the cross-account case. ``` { "eventVersion": "1.05", "userIdentity": { "type": "AWSAccount", "principalId": "AROAQGFTBBBGOBWV2EMZA:GlueJobRunnerSession", "accountId": "111122223333" }, "eventSource": "lakeformation.amazonaws.com", "eventName": "GetDataAccess", ... ... "additionalEventData": { "requesterService": "GLUE_JOB", "lakeFormationRoleSessionName": "AWSLF-00-GL-111122223333-G13T0Rmng2" }, ... } ``` As a shared resource consumer, when you opt in to include the principal ARN, the excerpt becomes the following. The `lakeFormationPrincipal` field represents the end role or user performing the query through Amazon Athena, Amazon Redshift Spectrum, or AWS Glue jobs. ``` { "eventVersion": "1.05", "userIdentity": { "type": "AWSAccount", "principalId": "AROAQGFTBBBGOBWV2EMZA:GlueJobRunnerSession", "accountId": "111122223333" }, "eventSource": "lakeformation.amazonaws.com", "eventName": "GetDataAccess", ... ... "additionalEventData": { "requesterService": "GLUE_JOB", "lakeFormationPrincipal": "arn:aws:iam::111122223333:role/ETL-Glue-Role", "lakeFormationRoleSessionName": "AWSLF-00-GL-111122223333-G13T0Rmng2" }, ... } ``` **To opt in to include principal ARNs in cross-account CloudTrail logs** 1. Open the Lake Formation console at [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/). Sign in as the `Administrator` user, or a user with the `Administrator Access` IAM policy. 1. In the navigation pane, choose **Settings**. 1. On the **Data catalog settings** page, in the **Default permissions for AWS CloudTrail** section, for **Resource owners**, enter one or more AWS resource owner account IDs. Press **Enter** after each account ID. 1. Choose **Save**. Now cross-account CloudTrail events stored in the logs for both the shared resource recipient and the resource owner contain the principal ARN. ## Querying CloudTrail logs for Amazon S3 cross-account access As a shared resource owner, you can query S3 CloudTrail logs to determine the accounts that have accessed your Amazon S3 buckets (provided that you enabled object-level logging in Amazon S3). This applies only to S3 locations that you registered with Lake Formation. If shared resource consumers opt in to include principal ARNs in Lake Formation CloudTrail logs, you can determine the roles or users that accessed the buckets. When running queries with Amazon Athena, you can join Lake Formation CloudTrail events and S3 CloudTrail events on the session name property. Queries can also filter Lake Formation events on `eventName="GetDataAccess"`, and S3 events on `eventName="Get Object"` or `eventName="Put Object"`. The following is an excerpt from a Lake Formation cross-account CloudTrail event where data in a registered S3 location was accessed. ``` { "eventSource": "lakeformation.amazonaws.com", "eventName": "GetDataAccess", .............. .............. "additionalEventData": { "requesterService": "GLUE_JOB", "lakeFormationPrincipal": "arn:aws:iam::111122223333:role/ETL-Glue-Role", "lakeFormationRoleSessionName": "AWSLF-00-GL-111122223333-B8JSAjo5QA" } } ``` The `lakeFormationRoleSessionName` key value, `AWSLF-00-GL-111122223333-B8JSAjo5QA`, can be joined with the session name in the `principalId` key of the S3 CloudTrail event. The following is an excerpt from the S3 CloudTrail event. It shows the location of the session name. ``` { "eventSource": "s3.amazonaws.com", "eventName": "Get Object" .............. .............. "principalId": "AROAQSOX5XXUR7D6RMYLR:AWSLF-00-GL-111122223333-B8JSAjo5QA", "arn": "arn:aws:sets::111122223333:assumed-role/Deformationally/AWSLF-00-GL-111122223333-B8JSAjo5QA", "session Context": { "session Issuer": { "type": "Role", "principalId": "AROAQSOX5XXUR7D6RMYLR", "arn": "arn:aws:iam::111122223333:role/aws-service-role/lakeformation.amazonaws.com/Deformationally", "accountId": "111122223333", "user Name": "Deformationally" }, .............. .............. } ``` The session name is formatted as follows: ``` AWSLF---- ``` **`version-number`** The version of this format, currently `00`. If the session name format changes, the next version will be `01`. **`query-engine-code`** Indicates the entity that accessed the data. Current values are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/lake-formation/latest/dg/cross-account-logging.html) **`account-id`** The AWS account ID that requested credentials from Lake Formation. **`suffix`** A randomly generated string. # Managing cross-account permissions using both AWS Glue and Lake Formation It's possible to grant cross-account access to Data Catalog resources and underlying data by using either AWS Glue or AWS Lake Formation. In AWS Glue, you grant cross-account permissions by creating or updating a Data Catalog resource policy. In Lake Formation, you grant cross-account permissions by using the Lake Formation `GRANT/REVOKE` permissions model and the `Grant Permissions` API operation. **Tip** We recommend that rely solely on Lake Formation permissions to secure your data lake. You can view Lake Formation cross-account grants by using the Lake Formation console or the AWS Resource Access Manager (AWS RAM) console. However, those console pages don't show cross-account permissions granted by the AWS Glue Data Catalog resource policy. Similarly, you can view the cross-account grants in the Data Catalog resource policy using the **Settings** page of the AWS Glue console, but that page doesn't show the cross-account permissions granted using Lake Formation. To ensure that you don't miss any grants when viewing and managing cross-account permissions, Lake Formation and AWS Glue require you to perform the following actions to indicate that you are aware of and are permitting cross-account grants by both Lake Formation and AWS Glue. **When granting cross-account permissions using the AWS Glue Data Catalog resource policy** If your account (grantor account or producer account) has made no cross-account grants that uses AWS RAM to share the resources, you can save a Data Catalog resource policy as usual in AWS Glue. However, if grants that involve AWS RAM resource shares have already been made, you must do one of the following to ensure that saving the resource policy succeeds: + When you save the resource policy on the **Settings** page of the AWS Glue console, the console issues an alert stating that the permissions in the policy will be in addition to any permissions granted using the Lake Formation console. You must choose **Proceed** to save the policy. + When you save the resource policy using the `glue:PutResourcePolicy` API operation, you must set the `EnableHybrid` field to '`TRUE`' (type = string). To update an existing resource policy, use the `glue:GetResourcePolicy` API operation to retrieve your current policy first, then modify it as needed before calling `glue:PutResourcePolicy`. **Note** When creating AWS Glue resource policies for cross-account access, grant only the minimum permissions required for your specific use case. For more information, see [PutResourcePolicy Action (Python: put\$1resource\$1policy)](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-jobs-security.html#aws-glue-api-jobs-security-PutResourcePolicy) in the *AWS Glue Developer Guide*. **When granting cross-account permissions using the Lake Formation named resources method** If there is no Data Catalog resource policy in your account (producer account), Lake Formation cross-account grants that you make proceed as usual. However, if a Data Catalog resource policy exists, you must add the following statement to it to permit your cross-account grants to succeed if they are made with the named resource method. Replace ** with a valid Region name and ** with your AWS account ID (producer account ID). ``` { "Effect": "Allow", "Action": [ "glue:ShareResource" ], "Principal": {"Service": [ "ram.amazonaws.com" ]}, "Resource": [ "arn:aws:glue:::table/*/*", "arn:aws:glue:::database/*", "arn:aws:glue:::catalog" ] } ``` Without this additional statement, the Lake Formation grant succeeds, but becomes blocked in AWS RAM, and the recipient account can't access the granted resource. **Important** When using the Lake Formation tag-based access control (LF-TBAC) method to make cross-account grants, you must have a Data Catalog resource policy with at least the permissions specified in [Prerequisites](cross-account-prereqs.md). **See Also:** [Metadata access control](access-control-metadata.md) (for a discussion of the named resource method versus the Lake Formation tag-based access control (LF-TBAC) method). [Viewing shared Data Catalog tables and databases](viewing-available-shared-resources.md) [Working with Data Catalog Settings on the AWS Glue Console](https://docs.aws.amazon.com/glue/latest/dg/console-data-catalog-settings.html) in the *AWS Glue Developer Guide* [Granting Cross-Account Access](https://docs.aws.amazon.com/glue/latest/dg/cross-account-access.html) in the *AWS Glue Developer Guide* (for sample Data Catalog resource policies) # Viewing all cross-account grants using the GetResourceShares API operation If your enterprise grants cross-account permissions using both an AWS Glue Data Catalog resource policy and Lake Formation grants, the only way to view all cross-account grants in one place is to use the `glue:GetResourceShares` API operation. When you grant Lake Formation permissions across accounts by using the named resource method, AWS Resource Access Manager (AWS RAM) creates an AWS Identity and Access Management (IAM) resource policy and stores it in your AWS account. The policy grants the permissions required to access the resource. AWS RAM creates a separate resource policy for each cross-account grant. You can view all of these policies by using the `glue:GetResourceShares` API operation. **Note** This operation also returns the Data Catalog resource policy. However, if you enabled meta data encryption in Data Catalog settings, and you don't have permission on the AWS KMS key, the operation won't return the Data Catalog resource policy. **To view all cross-account grants** + Enter the following AWS CLI command. ``` aws glue get-resource-policies ``` The following is an example resource policy that AWS RAM creates and stores when you grant permissions on table `t` in database `db1` to AWS account 1111-2222-3333. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:GetTable", "glue:GetTables", "glue:GetTableVersion", "glue:GetTableVersions", "glue:GetPartition", "glue:GetPartitions", "glue:BatchGetPartition", "glue:SearchTables" ], "Principal": {"AWS": [ "111122223333" ]}, "Resource": [ "arn:aws:glue:us-east-1:111122223333:table/db1/t" ] } ] } ``` ------ **See also:** [GetResourceShares Action (Python: get\$1resource\$1policies)](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-jobs-security.html#aws-glue-api-jobs-security-GetResourcePolicies) in the *AWS Glue Developer Guide*