Cross-Account Licensing Setup

Overview
Choosing an approach
- Assume role setup
- License grants setup
Verifying the setup
Troubleshooting
IAM permissions reference

Overview

When an organisation purchases DataMasque through AWS Marketplace, the contract license is owned by the purchasing AWS account. In some deployments the purchasing account (referred to here as the billing account) is different from the account where DataMasque is actually running (the deployment account) — for example, a centralised procurement team manages all AWS contracts in a dedicated billing account, while engineering teams run workloads in separate production accounts.

This guide explains how to configure both AWS and DataMasque so that a DataMasque instance in the deployment account can check out a license held in the billing account.

Choosing an approach

Approach	Description	Recommended
Assume role	DataMasque in the deployment account temporarily assumes an IAM role in the billing account when performing license operations (checkout, check-in, discovery). The license itself stays in the billing account.	✓
License grants	The billing account uses AWS License Manager to grant the license to the deployment account. DataMasque then checks it out from the deployment account directly, with no cross-account credentials required.

Assume role is recommended for most deployments:

No changes to the license grant are required.
Access can be revoked by modifying the IAM trust policy without touching the license.
The same license can serve multiple deployment accounts through separate role assumptions.

Use license grants if your organisation already has an established grants workflow or prefers not to manage cross-account IAM roles.

Assume role setup

The following table summarises what needs to be configured in each account.

Account	Action
Billing account	Create an IAM role with License Manager permissions and a trust policy allowing the DataMasque role to assume it.
Deployment account	Add `sts:AssumeRole` permission to the DataMasque instance role.
DataMasque UI	Enter the billing account role ARN in the AWS Contract License configure panel.

Step 1: Billing account: create a cross-account IAM role

In the billing account, create an IAM role — for example, DataMasqueLicenseRole.

Permissions policy

Attach the following policy to the role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DataMasqueLicenseOperations",
            "Effect": "Allow",
            "Action": [
                "license-manager:CheckoutLicense",
                "license-manager:CheckInLicense",
                "license-manager:ListReceivedLicenses",
                "license-manager:GetLicense",
                "aws-marketplace:SearchAgreements"
            ],
            "Resource": "*"
        }
    ]
}

license-manager:ListReceivedLicenses and license-manager:GetLicense enable DataMasque to show available products and product details in the AWS Contract License configure panel. Without them, license checkout will still work but product discovery will be unavailable.

Trust policy

Attach the following trust policy, replacing the placeholders with the actual values for your deployment:

<deployment-account-id> — the AWS account ID of the account where DataMasque is running.
<datamasque-role-name> — the name of the IAM role attached to your DataMasque instance. Typical values: DataMasque-EC2-Role (EC2 deployments), eks-datamasque-sa-role (EKS deployments), or the task role name (ECS deployments).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<deployment-account-id>:role/<datamasque-role-name>"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Note the full ARN of this role once created, for example: arn:aws:iam::<billing-account-id>:role/DataMasqueLicenseRole. You will need it in Steps 2 and 3.

Step 2: Deployment account: grant assume role permission to DataMasque

In the deployment account, attach the following additional statement to the IAM policy of the DataMasque instance role. Replace the account ID and role name with the values from Step 1:

{
    "Sid": "DataMasqueLicenseAssumeRole",
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": "arn:aws:iam::<billing-account-id>:role/DataMasqueLicenseRole"
}

If you want to scope this more broadly (for example to allow assuming any future license roles in the billing account), you can use a wildcard resource:

{
    "Sid": "DataMasqueLicenseAssumeRole",
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": "arn:aws:iam::<billing-account-id>:role/DataMasqueLicense*"
}

Step 3: Configure the role ARN in DataMasque

Once the IAM roles are in place, configure DataMasque to use them:

Navigate to the My Account page.
In the Account License Information section, click Configure next to AWS Contract License.
Check Assume role for license check out.
In the Role ARN field, enter the ARN of the role created in Step 1.
Click Save.

Configuring assume role in the AWS Contract License panel

After saving, DataMasque will use the specified role for all license operations. The AWS Contract License status area will update to reflect the checkout result.

AWS Contract License status after successful checkout

You can also configure the role ARN programmatically via the API — see PUT /api/license/contract-type/ for details.

License grants setup

Note: Assume role is the recommended approach. Use license grants only if your organisation already uses or prefers the AWS License Manager grants workflow.

AWS License Manager allows the billing account to grant license usage directly to the deployment account. Once the deployment account accepts the grant, DataMasque can check out licenses without any additional configuration — no role ARN is required in the DataMasque UI.

Step 1: Billing account: create a license grant

Open the AWS License Manager console in the billing account.
In the left navigation, choose Granted licenses.
Choose Create grant.
Select the DataMasque license you want to share.
In the Grantee AWS account ID field, enter the account ID of the deployment account.
Select the allowed operations (at minimum: CheckoutLicense and CheckInLicense).
Complete the grant creation.

The deployment account will now have a pending grant to accept.

Step 2: Deployment account: accept the grant

Open the AWS License Manager console in the deployment account.
In the left navigation, choose Received grants.
Locate the grant from the billing account.
Select it and choose Accept grant.

Once accepted, DataMasque in the deployment account can check out the license without any cross-account role configuration. No Assume role for license check out settings are required in the DataMasque UI.

Verifying the setup

Assume role

Verify that the IAM trust and permissions are correct using the AWS CLI from an instance with the same IAM role as DataMasque:

# Attempt to assume the billing account role
aws sts assume-role \
    --role-arn arn:aws:iam::<billing-account-id>:role/DataMasqueLicenseRole \
    --role-session-name datamasque-verify-session

If this returns a set of temporary credentials, the IAM configuration is correct.

You can then verify that the assumed role can see the license:

# Export the temporary credentials from the assume-role output
export AWS_ACCESS_KEY_ID=<AccessKeyId from above>
export AWS_SECRET_ACCESS_KEY=<SecretAccessKey from above>
export AWS_SESSION_TOKEN=<SessionToken from above>

# List licenses visible from the billing account
aws license-manager list-received-licenses

The DataMasque license should appear in the output.

License grants

In the deployment account, verify the grant has been accepted and the license is visible:

aws license-manager list-received-licenses

The DataMasque license granted by the billing account should appear with a status of ACTIVE.

Troubleshooting

Note: AWS Marketplace licenses always reside in us-east-1. AWS License Manager's marketplace APIs work globally, so DataMasque running in a different region (e.g. us-west-2) will reach the license correctly. You do not need to configure the region manually.

Symptom	Likely cause	Resolution
`AccessDenied` when checking out a license	DataMasque instance role lacks `license-manager:CheckoutLicense` or `CheckInLicense`	Add the missing permission to the DataMasque instance role
`AccessDenied` when assuming the billing account role	Deployment account policy missing `sts:AssumeRole`, or the trust policy references a wrong role ARN	Verify both the deployment account policy and the trust policy in the billing account
Role ARN accepted but checkout still fails with `AccessDenied`	The billing account role lacks `license-manager:CheckoutLicense`	Add the permission to the billing account role's policy
No products shown in Specific checkout mode	Billing account role missing `license-manager:ListReceivedLicenses`	Add `license-manager:ListReceivedLicenses` to the billing account role
`AuthorizationException` when checking out, even though IAM policy references a specific license ARN	AWS License Manager does not support resource-level restrictions for `CheckoutLicense`, `CheckInLicense`, or `ExtendConsumptionLicense` — AWS silently treats the policy as granting nothing	Change `"Resource"` to `"*"` in the IAM policy. Scoping to a specific ARN will always fail for these actions regardless of how the ARN is formatted
Grant not visible in the deployment account	Grant not yet accepted, or an AWS Organizations SCP is blocking access	Accept the grant in the deployment account's License Manager console; check for SCPs if the grant does not appear
Save is disabled in the DataMasque configure panel	Role ARN field is empty or contains an invalid ARN	Ensure the ARN follows the format `arn:aws:iam::<account-id>:role/<role-name>`

For DataMasque-specific errors shown in the My Account page, refer to Troubleshooting Dynamic licenses.

IAM permissions reference

The following table lists all IAM permissions relevant to Dynamic licensing and cross-account setup.

Permission	Where to grant	Required	Purpose
`license-manager:CheckoutLicense`	DataMasque instance role (same-account) or billing account cross-account role (assume role)	✓	Check out a license unit
`license-manager:CheckInLicense`	Same as above	✓	Release a license unit on shutdown or when checkout is disabled
`sts:AssumeRole`	DataMasque instance role in the deployment account	Only for assume role	Allow DataMasque to assume the billing account role
`license-manager:ListReceivedLicenses`	Billing account cross-account role (assume role) or deployment account role (grants)		Show available products in Specific checkout mode
`license-manager:GetLicense`	Same as above		Display product name and contract expiry in the status section
`license-manager:GetLicenseUsage`	Same as above		Display consumed and available entitlement counts in Specific checkout mode
`aws-marketplace:SearchAgreements`	DataMasque instance role (same-account) or billing account cross-account role (assume role)		Display the Agreement ID with a link to AWS Marketplace console

Permissions marked as required are needed for basic license checkout to function. Optional permissions only affect the information displayed in the DataMasque UI.