Before You Begin
Before you can share a model, you must have a trained custom classifier or custom entity recognizer in Amazon Comprehend in your AWS account. For more information about training custom models, see Custom Classification (p. 90) or Custom Entity Recognition (p. 109).
Required Permissions
IAM Policy Statement
Before you can add a resource-based policy to a custom model, you require permissions in AWS Identity and Access Management (IAM). Your IAM user or group must have a policy attached so you can create, get, and delete model policies, as shown in the following example.
Example IAM policy to manage resource-based policies for custom models
{ "Effect": "Allow", "Action": [
"comprehend:PutResourcePolicy", "comprehend:DeleteResourcePolicy", "comprehend:DescribeResourcePolicy"
],
"Resource": "arn:aws:comprehend:us-west-2:111122223333:document-classifier/foo/version/*"
}
For information about creating an IAM policy, see Creating IAM policies in the IAM User Guide. For information about attaching an IAM policy, see Adding and removing IAM identity permissions in the IAM User Guide.
AWS KMS Key Policy Statement
If you are sharing an encrypted model, then you might need to add permissions for AWS KMS.
This requirement depends on the type of KMS key that you use to encrypt the model in Amazon Comprehend.
An AWS owned key is owned and managed by an AWS service. If you use an AWS owned key, you do not need to add permissions for AWS KMS, and you can skip this section.
A Customer managed key is a key that you create, own, and manage in your AWS account. If you use a customer managed key, you must add a statement to your KMS key policy.
The policy statement authorizes one or more entities (such as IAM users or AWS accounts) to perform the AWS KMS operations required to decrypt the model.
Use the following condition keys in the policy to validate the entities that access your KMS key. When a user imports the model, AWS KMS checks that the ARN of the source model version matches the condition. If you do not include a condition in the policy, the specified principals can use your KMS key to decrypt any model version:
• aws:SourceArn – Use this condition key with the kms:GenerateDataKey and kms:Decrypt actions.
Before You Begin
• kms:EncryptionContext – Use this condition key with the kms:GenerateDataKey, kms:Decrypt, and kms:CreateGrant actions.
In the following example, the policy authorizes AWS account 444455556666 to use version 1 of the specified classifier model owned by AWS account 111122223333.
Example KMS key policy to access a specific classifier model version
{ "Version": "2012-10-17",
"Action": "kms:CreateGrant", "Resource": "*",
"Condition": { "StringEquals": {
"kms:EncryptionContext:aws:comprehend:arn":
"arn:aws:comprehend:us-west-2:111122223333:document-classifier/classifierName/version/1"
The following example policy authorizes user ExampleUser from AWS account 444455556666 and ExampleRole from AWS account 123456789012 to access this KMS key via the Amazon Comprehend service.
Example KMS key policy to allow access to the Amazon Comprehend service (alternative 1).
{
Before You Begin
"Action": "kms:CreateGrant", "Resource": "*",
"Condition": { "StringLike": {
"kms:EncryptionContext:aws:comprehend:arn": "arn:aws:comprehend:*"
} } } ]}
The following example policy authorizes AWS account 444455556666 to access this KMS key via the Amazon Comprehend service, using an alternative syntax to the previous example.
Example KMS key policy to allow access to the Amazon Comprehend service (alternative 2).
{
For more information, see Key policies in AWS KMS in the AWS Key Management Service Developer Guide.
Resource-Based Policies for Custom Models
Resource-Based Policies for Custom Models
Before an Amazon Comprehend user in another AWS account can import a custom model from your AWS account, you must authorize them to do so. To authorize them, you add a resource-based policy to the model version that you want to share. A resource-based policy is an IAM policy that you attach to a resource in AWS.
When you attach a resource policy to a custom model version, the policy authorizes one or more entities, such as IAM users or AWS accounts, to perform the comprehend:ImportModel action on the model version.
Example resource-based policy for a custom model version
This example specifies the authorized entities in the Principal attribute. Resource "*" refers to the specific model version that you attach the policy to.
{
"Version": "2012-10-17", "Statement": [
{
"Effect": "Allow",
"Action": "comprehend:ImportModel", "Resource": "*",
"Principal": { "AWS": [
"arn:aws:iam::111122223333:root",
"arn:aws:iam::444455556666:user/ExampleUser", "arn:aws:iam::123456789012:role/ExampleRole"
] } } ] }
For policies that you attach to custom models, comprehend:ImportModel is the only action that Amazon Comprehend supports.
For more information about resource-based policies, see Identity-based policies and resource-based policies in the IAM User Guide.
Step 1: Add a Resource-Based Policy to a Custom Model
You can add a resource-based policy by using the AWS Management Console, AWS CLI, or Amazon Comprehend API.
AWS Management Console
You can use Amazon Comprehend in the AWS Management Console.
To add a resource-based policy
1. Sign in to the AWS Management Console and open the Amazon Comprehend console.
2. In the navigation menu on the left, under Customization, choose the page that contains your custom model:
a. If you are sharing a custom document classifier, choose Custom classification.
b. If you are sharing a custom entity recognizer, choose Custom entity recognition.
Step 1: Add a Resource-Based Policy to a Custom Model
3. In the list of models, choose the model name to open its details page.
4. Under Versions, choose the name of the model version that you want to share.
5. On the version details page, choose the Tags, VPC & Policy tab.
6. In the Resource-based policy section, choose Edit.
7. On the Edit resource-based policy page, do the following:
a. For Policy name, enter a name that will help you recognize the policy after you create it.
b. Under Authorize, specify one or more of the following entities to authorize them to import your model:
Field Definition and examples
Service principals Service principal identifiers for the services that can access this model version. For example:
comprehend.amazonaws.com
AWS account IDs AWS accounts that can access this model version. Authorizes all users who belong to the account. For example:
111122223333, 123456789012
IAM entities ARNs for IAM users or roles that can access this model version. For example:
arn:aws:iam::111122223333:user/ExampleUser, arn:aws:iam::444455556666:role/ExampleRole
8. Under Share, you can copy the ARN of the model version to help you share it with the person who will import your model. When someone imports a custom model from a different AWS account, the model version ARN is required.
9. Choose Save. Amazon Comprehend creates your resource-based policy and attaches it to your model.
AWS CLI
To add a resource-based policy to a custom model with the AWS CLI, use the PutResourcePolicy command. The command takes the following parameters:
• resource-arn – The ARN of the custom model, including the model version.
• resource-policy – A JSON file that defines the resource-based policy to attach to your custom model.
You can also provide the policy as an inline JSON string. To provide valid JSON for your policy, enclose the attribute names and values in double quotes. If the JSON body is also enclosed in double quotes, you escape the double quotes that are inside the policy.
• policy-revision-id – The revision ID that Amazon Comprehend assigned to the policy that you are updating. If you are creating a new policy that has no prior version, don't use this parameter. Amazon Comprehend creates the revision ID for you.
Example Add a resource-based policy to a custom model using the put-resource-policy command
This example defines a policy in a JSON file named policyFile.json and associates the policy to a model.
The model is version v2 of a classifier named mycf1.
Step 2: Provide the Details That Others Need to Import
$ aws comprehend put-resource-policy \
> --resource-arn arn:aws:comprehend:us-west-2:111122223333:document-classifier/mycf1/
version/v2 \
> --resource-policy file://policyFile.json \
> --policy-revision-id revision-id
The JSON file for the resource policy contains the following contents:
• Action – The policy authorizes the named principals to use comprehend:ImportModel.
• Resource – The ARN of the custom model. Resource "*" refers to the model version that you specify in the put-resource-policy command.
• Principal – The policy authorizes user jane from AWS account 444455556666 and all users from AWS account 123456789012.
{ "Version":"2012-10-17", "Statement":[
{"Sid":"ResourcePolicyForImportModel", "Effect":"Allow",
"Action":["comprehend:ImportModel"], "Resource":"*",
"Principal":
{"AWS":
["arn:aws:iam::444455556666:user/jane", "123456789012"]
} } ] }
Amazon Comprehend API
To add a resource-based policy to a custom model by using the Amazon Comprehend API, use the PutResourcePolicy API operation.
You can also add a policy to a custom model in the API request that creates the model. To do this, provide the policy JSON for the ModelPolicy parameter when you submit a CreateDocumentClassifier or CreateEntityRecognizer request.
Step 2: Provide the Details That Others Need to Import
Now that you have added the resource-based policy to your custom model, you have authorized other Amazon Comprehend users to import your model into their AWS accounts. However, before they can import, you must provide them with the following details:
• The Amazon Resource Name (ARN) of the model version.
• The AWS Region that contains the model. Anyone who imports your model must use the same AWS Region.
• Whether the model is encrypted, and if it is, the type of AWS KMS key that you use: AWS owned key or customer managed key.
• If your model is encrypted with a customer managed key, then you must provide the ARN of the KMS key. Anyone who imports your model must include the ARN in an IAM service role in their AWS
Importing a Custom Model
account. This role authorizes Amazon Comprehend to use the KMS key to decrypt the model during the import.
For more information about how other users import your model, see Importing a Custom Model From Another AWS Account (p. 150).
Importing a Custom Model From Another AWS Account
In Amazon Comprehend, you can import a custom model that's in another AWS account. When you import a model, you create a new custom model in your account. Your new custom model is a fully-trained duplicate of the model that you imported.
Topics
• Before You Begin (p. 150)
• Importing a Custom Model (p. 152)
Before You Begin
Before you can import a custom model from another AWS account, ensure that the person who shared the model with you does the following:
• Authorizes you to do the import. This authorization is granted in the resource-based policy that is attached to the model version. For more information, see Resource-Based Policies for Custom Models (p. 147).
• Provides you with the following information:
• The Amazon Resource Name (ARN) of the model version.
• The AWS Region that contains the model. You must use the same AWS Region when you import.
• Whether the model is encrypted with an AWS KMS key and, if it is, the type of key that is used.
If the model is encrypted, you might need to take additional steps, depending on the type of KMS key that is used:
• AWS owned key – This type of KMS key is owned and managed by AWS. If the model is encrypted with an AWS owned key, no additional steps are needed.
• Customer managed key – This type of KMS key is created, owned, and managed by an AWS customer in their AWS account. If the model is encrypted with a customer managed key, then the person who shared the model must:
• Authorize you to decrypt the model. This authorization is granted in the KMS key policy for the customer managed key. For more information, see AWS KMS Key Policy Statement (p. 144).
• Provide the ARN of the customer managed key. You use this ARN when you create an IAM service role. This role authorizes Amazon Comprehend to use the KMS key to decrypt the model.
Required Permissions
Before you can import a custom model, you or your administrator must authorize the required actions in AWS Identity and Access Management (IAM). As an Amazon Comprehend user, you must be authorized to import by an IAM policy statement. If encryption or decryption is required during the import, then Amazon Comprehend must be authorized to use the necessary AWS KMS keys.
Before You Begin
IAM Policy Statement
Your IAM user or group must have a policy attached that allows the ImportModel action, as shown in the following example.
Example IAM policy to import a custom model
{ "Effect": "Allow", "Action": [
"comprehend:ImportModel"
], "Resource": "arn:aws:comprehend:us-west-2:111122223333:document-classifier/foo/version/*"
}
For information about creating an IAM policy, see Creating IAM policies in the IAM User Guide. For information about attaching an IAM policy, see Adding and removing IAM identity permissions in the IAM User Guide.
IAM Service Role for AWS KMS Encryption
When you import a custom model, you must authorize Amazon Comprehend to use AWS KMS keys in either of the following cases:
• You are importing a custom model that is encrypted with a customer managed key in AWS KMS. In this case, Amazon Comprehend needs access to the KMS key so that it can decrypt the model during the import.
• You want to encrypt the new custom model that you create with the import, and you want to use a customer managed key. In this case, Amazon Comprehend needs access to your KMS key so that it can encrypt the new model.
To authorize Amazon Comprehend to use these AWS KMS keys, you create an IAM service role. This type of IAM role allows an AWS service to access resources in other services on your behalf. For more information about service roles, see Creating a Role to Delegate Permissions to an AWS Service in the IAM User Guide.
If you use the Amazon Comprehend console to import, you can have Amazon Comprehend create the service role for you. Otherwise, you must create a service role in IAM before you import.
The IAM service role must have a permissions policy and a trust policy, as shown by the following examples.
Example permissions policy
The following permissions policy allows the AWS KMS operations that Amazon Comprehend uses to encrypt and decrypt custom models. It grants access to two KMS keys:
• One KMS key is in the AWS account that contains the model to import. It was used to encrypt the model, and Amazon Comprehend uses it to decrypt the model during the import.
• The other KMS key is in the AWS account that imports the model. Amazon Comprehend uses this key to encrypt the new custom model that is created by the import.
{
"Version": "2012-10-17", "Statement": [
{
"Effect": "Allow", "Action": [
Importing a Custom Model
"kms:CreateGrant"
],
"Resource": [
"arn:aws:kms:us-west-2:111122223333:key/key-id", "arn:aws:kms:us-west-2:444455556666:key/key-id"
]
"arn:aws:kms:us-west-2:111122223333:key/key-id", "arn:aws:kms:us-west-2:444455556666:key/key-id"
],
The following trust policy allows Amazon Comprehend to assume the role and gain its permissions. It allows the comprehend.amazonaws.com service principal to perform the sts:AssumeRole operation.
To help with confused deputy prevention (p. 197), you restrict the scope of the permission by using one or more global condition context keys. For aws:SourceAccount, specify the account Id of the user who is importing the model.
"Service": "comprehend.amazonaws.com"
},
"Action": "sts:AssumeRole", "Condition": {
You can import a custom model by using the AWS Management Console, AWS CLI, or Amazon Comprehend API.
AWS Management Console
You can use Amazon Comprehend in the AWS Management Console.
Importing a Custom Model
To import a custom model
1. Sign in to the AWS Management Console and open the Amazon Comprehend console.
2. In the navigation menu on the left, under Customization, choose the page for the type of model that you are importing:
a. If you are importing a custom document classifier, choose Custom classification.
b. If you are importing a custom entity recognizer, choose Custom entity recognition.
3. Choose Import version.
4. On the Import model version page, enter the following details:
• Model version ARN – The ARN of the model version to import.
• Model name – A custom name for the new model that is created by the import.
• Version name – A custom name for the new model version that is created by the import.
5. For Model encryption, choose the type of KMS key to use to encrypt the new custom model that you create with the import:
• Use AWS owned key – Amazon Comprehend encrypts your model by using a key in AWS Key Management Service (AWS KMS) that is created, managed, and used on your behalf by AWS.
• Choose a different AWS KMS key (advanced) – Amazon Comprehend encrypts your model by using a customer managed key that you manage in AWS KMS.
If you choose this option, select a KMS key that's in your AWS account, or create a new one by choosing Create an AWS KMS key.
6. In the Service access section, grant Amazon Comprehend access to any AWS KMS keys that it needs to:
• Decrypt the custom model that you import.
• Encrypt that the new custom model that you create with the import.
You grant access with an IAM service role that allows Amazon Comprehend to use the KMS keys.
For Service role, do one of the following:
• If you have an existing service role that you want to use, choose Use an existing IAM role. Then, select it under Role name.
• If you want Amazon Comprehend to create a role for you, choose Create an IAM role.
7. If you chose to have Amazon Comprehend create the role for you, do the following:
a. For Role name, enter a role name suffix that will help you recognize the role later.
b. For Source KMS key ARN, enter the ARN of the KMS key that is used to encrypt the model that you're importing. Amazon Comprehend uses this key to decrypt the model during the import.
8. (Optional) In the Tags section, you can add tags to the new custom model that you create by importing. For more information about tagging custom models, see Tagging a new resource (p. 191).
9. Choose Confirm.
AWS CLI
You can use Amazon Comprehend by running commands with the AWS CLI.
Example import-model command
To import a custom model, use the import-model command:
Importing a Custom Model
$ aws comprehend import-model \
> --source-model arn:aws:comprehend:us-west-2:111122223333:document-classifier/foo/version/
bar \
> --model-name importedDocumentClassifier \
> --version-name versionOne \
> --data-access-role-arn arn:aws:iam::444455556666:role/comprehendAccessRole \
> --model-kms-key-id kms-key-id
This example uses the following parameters:
• source-model – The ARN of the custom model to import.
• model-name – A custom name for the new model that is created by the import.
• version-name – A custom name for the new model version that is created by the import.
• data-access-role-arn – The ARN of the IAM service role that allows Amazon Comprehend to use the necessary AWS KMS keys to encrypt or decrypt the custom model.
• model-kms-key-id – The ARN or ID of the KMS key that Amazon Comprehend uses to encrypt the custom model that you create with this import. This key must be in AWS KMS in your AWS account.
• model-kms-key-id – The ARN or ID of the KMS key that Amazon Comprehend uses to encrypt the custom model that you create with this import. This key must be in AWS KMS in your AWS account.