Como compartilhar um modelo personalizado com outra Conta da AWS

Com o Amazon Comprehend, você pode compartilhar seus modelos personalizados com outras pessoas, permitindo que elas importem seus modelos para as contas da AWS delas. Quando um usuário importa um de seus modelos personalizados, ele cria um novo modelo personalizado na conta dele. O novo modelo do usuário duplica o modelo que você compartilhou.

Para compartilhar um modelo personalizado, você anexa uma política que autorize outras pessoas a importá-lo. Em seguida, você fornece os detalhes necessários a esses usuários.

nota

Quando outros usuários importarem um modelo personalizado que você compartilhou, eles deverão usar a mesma Região da AWS — p. ex., Leste dos EUA (Norte da Virgínia) — que contém seu modelo.

Antes de começar

Antes de compartilhar um modelo, você deve ter um classificador personalizado treinado ou um reconhecedor personalizado de entidade principal no Amazon Comprehend em sua Conta da AWS. Para mais informações sobre o treinamento de modelos personalizados, consulte Classificação personalizada ou Reconhecimento de entidade personalizado.

Permissões obrigatórias

Declaração de política do IAM

Antes que seja possível adicionar uma política baseada em recursos a um modelo personalizado, você precisa de permissões no AWS Identity and Access Management (IAM). Seu usuário, grupo ou perfil deve ter uma política anexada para que você possa criar, obter e excluir políticas de modelo, conforme apresentado no exemplo a seguir.

exemplo Política do IAM para gerenciar políticas baseadas em recursos para modelos personalizados

{
  "Effect": "Allow",
  "Action": [
    "comprehend:PutResourcePolicy",
    "comprehend:DeleteResourcePolicy",
    "comprehend:DescribeResourcePolicy"
  ],
  "Resource": "arn:aws:comprehend:us-west-2:111122223333:document-classifier/foo/version/*"
}

Para obter mais informações sobre como criar uma política do IAM, consulte Criar políticas do IAM no Guia do usuário do IAM. Para obter informações sobre como anexar a política do IAM, consulte Adicionar e remover permissões de identidade do IAM no Guia do usuário do IAM.

Declaração de política de chaves do AWS KMS

Se você estiver compartilhando um modelo criptografado, talvez seja necessário adicionar permissões para o AWS KMS. Esse requisito dependerá do tipo de chave do KMS que você usa para criptografar o modelo no Amazon Comprehend.

Uma Chave pertencente à AWS pertence e é gerenciada por um serviço da AWS. Se você usar um Chave pertencente à AWS, não precisará adicionar permissões AWS KMS e poderá ignorar esta seção.

Uma Chave gerenciada pelo cliente é uma chave que você cria, possui e gerencia na sua Conta da AWS. Se usar uma chave gerenciada pelo cliente, você deverá adicionar uma instrução à sua política de chave do KMS.

A declaração de política autoriza uma ou mais entidades (como usuários ou contas) a realizar as operações do AWS KMS necessárias para descriptografar o modelo.

Você usa chaves de condição para ajudar a evitar o problema “confused deputy”. Para ter mais informações, consulte Prevenção contra o ataque do “substituto confuso” em todos os serviços.

Use as seguintes chaves de condição na política para validar as entidades principais que acessam sua chave do KMS. Quando um usuário importar o modelo, o AWS KMS verificará se o ARN da versão do modelo de origem corresponde à condição. Se você não incluir uma condição na política, as entidades principais especificadas poderão usar sua chave do KMS para descriptografar qualquer versão do modelo:

• aws: SourceArn — Use essa chave de condição com kms:GenerateDataKey as kms:Decrypt ações e.

• kms: EncryptionContext — Use essa chave de condição com as kms:CreateGrant ações kms:GenerateDataKeykms:Decrypt, e.

No exemplo a seguir, a política autoriza a Conta da AWS 444455556666 a usar a versão 1 do modelo de classificador especificado de propriedade da Conta da AWS 111122223333.

exemplo Política de chaves do KMS para acessar uma versão específica do modelo de classificador

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
          "AWS":
                "arn:aws:iam::444455556666:root"
      },
      "Action": [
          "kms:Decrypt",
          "kms:GenerateDataKey"
      ],
      "Resource": "*",
      "Condition": {
          "StringEquals": {
              "aws:SourceArn":
                "arn:aws:comprehend:us-west-2:111122223333:document-classifier/classifierName/version/1"
          }
      }
    },
    {
      "Effect": "Allow",
      "Principal": {
          "AWS":  "arn:aws:iam::444455556666:root"
      },
      "Action": "kms:CreateGrant",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
           "kms:EncryptionContext:aws:comprehend:arn":
              "arn:aws:comprehend:us-west-2:111122223333:document-classifier/classifierName/version/1"
        }
      }
    }
  ]
}

O exemplo de política a seguir autoriza o usuário ExampleUser ExampleRolede Conta da AWS 444455556666 e Conta da AWS 123456789012 para acessar essa chave KMS por meio do serviço Amazon Comprehend.

exemplo Política de chaves do KMS para permitir o acesso ao serviço Amazon Comprehend (alternativa 1).

{
  "Version": "2012-10-17",
  "Statement": [
    {
        "Effect": "Allow",
        "Principal": {
            "AWS": [
                "arn:aws:iam::444455556666:user/ExampleUser",
                "arn:aws:iam::123456789012:role/ExampleRole"
              ]
        },
        "Action": [
            "kms:Decrypt",
            "kms:GenerateDataKey"
        ],
        "Resource": "*",
        "Condition": {
            "StringLike": {
                "aws:SourceArn": "arn:aws:comprehend:*"

            }
        }
    },
    {
      "Effect": "Allow",
      "Principal": {
         "AWS": [
                "arn:aws:iam::444455556666:user/ExampleUser",
                "arn:aws:iam::123456789012:role/ExampleRole"
              ]
      },
      "Action": "kms:CreateGrant",
      "Resource": "*",
      "Condition": {
          "StringLike": {
              "kms:EncryptionContext:aws:comprehend:arn": "arn:aws:comprehend:*"
          }
      }
    }
  ]
}

O exemplo de política a seguir autoriza a Conta da AWS 444455556666 a acessar a essa chave do KMS por meio do serviço Amazon Comprehend, usando uma sintaxe alternativa ao exemplo anterior.

exemplo Política de chaves do KMS para permitir o acesso ao serviço Amazon Comprehend (alternativa 2).

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
          "AWS": "arn:aws:iam::444455556666:root"
      },
      "Action": [
          "kms:Decrypt",
          "kms:GenerateDataKey",
          "kms:CreateGrant"
      ],
      "Resource": "*",
      "Condition": {
          "StringLike": {
              "kms:EncryptionContext:aws:comprehend:arn": "arn:aws:comprehend:*"
          }
      }
    }
  ]
}

Para obter mais informações, consulte Políticas de chaves no AWS KMS no Guia do desenvolvedor do AWS Key Management Service.

Políticas baseadas em recursos para modelos personalizados

Antes que um usuário do Amazon Comprehend em outra Conta da AWS possa importar um modelo personalizado da sua conta da AWS, você deverá autorizá-lo a fazer isso. Para autorizá-los, adicione uma política baseada em recursos à versão do modelo que deseja compartilhar. Uma política baseada em recursos é uma política do IAM que você anexa a um recurso na AWS.

Quando você anexa uma política de recursos a uma versão de modelo personalizado, a política autoriza usuários, grupos ou funções a executar a ação comprehend:ImportModel na versão do modelo.

exemplo Política baseada em recursos para uma versão de modelo personalizado

Este exemplo especifica as entidades autorizadas no atributo Principal. O recurso “*” se refere à versão específica do modelo à qual você anexa a política.

{
  "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"
         ]
      }
    }
  ]
}

Para políticas que você anexa a modelos personalizados, comprehend:ImportModel é a única ação que o Amazon Comprehend suporta.

Para obter mais informações sobre as políticas de acesso baseadas em recursos, consulte Políticas baseadas em identidade no Guia do usuário do IAM.

Etapa 1: incluir uma política baseada em recursos em um modelo personalizado

Você pode adicionar uma política baseada em recursos usando o AWS Management Console, o AWS CLI ou a API do Amazon Comprehend.

AWS Management Console

Você pode usar o Amazon Comprehend no AWS Management Console.

Para adicionar uma política baseada em recurso

1. Faça login no AWS Management Console e abra o console do Amazon Comprehend em https://console.aws.amazon.com/comprehend/

2. No menu de navegação à esquerda, em Personalização, escolha a página que contém seu modelo personalizado:

   1. Se você estiver compartilhando um classificador personalizado de documento, escolha Classificação personalizada.

   2. Se você estiver compartilhando um reconhecedor personalizado de entidade, escolha Reconhecimento personalizado de entidade.

3. Na lista de modelos, escolha um modelo para exibir sua página de detalhes.

4. Em Versões, escolha o nome da versão do modelo que deseja compartilhar.

5. Na página de detalhes da versão, escolha a guia Tags, VPC e política.

6. Na seção Política baseada em recursos, escolha Editar.

7. Na página Editar página de política baseada em recursos, faça o seguinte:

   1. Em Nome da política, insira um nome que ajude a reconhecer a política após criá-la.

   2. Em Autorizar, especifique uma ou mais das seguintes entidades para autorizá-las a importar seu modelo:

      Campo	Definição e exemplos
      Entidades principais de serviço	Identificadores de entidades principais de serviço para os serviços que podem acessar essa versão do modelo. Por exemplo: . comprehend.amazonaws.com
      IDs de Conta da AWS	Contas da AWS que podem acessar essa versão do modelo. Autoriza todos os usuários que pertencem à conta. Por exemplo: . 111122223333, 123456789012
      Entidades do IAM	ARNs para usuários ou perfis que podem acessar essa versão do modelo. Por exemplo: . arn:aws:iam: :111122223333:user/, arn:aws:iam: :444455556666:role/ ExampleUser ExampleRole

8. Em Compartilhar, você pode copiar o ARN da versão do modelo para ajudar no compartilhamento com a pessoa que importará seu modelo. Quando alguém importa um modelo personalizado de outra Conta da AWS, é necessário informar o ARN da versão do modelo.

9. Escolha Salvar. O Amazon Comprehend cria sua política baseada em recursos e a anexa ao seu modelo.

AWS CLI

Para adicionar uma política baseada em recursos a um modelo personalizado com oAWS CLI, use o PutResourcePolicycomando. O comando usa os seguintes parâmetros:

• resource-arn – o ARN do modelo personalizado, incluindo a versão do modelo.

• resource-policy – um arquivo JSON que define a política baseada em recursos a ser anexada ao seu modelo personalizado.

  Você também pode fornecer a política como uma string JSON em linha. Para fornecer JSON válido para sua política, coloque os nomes e valores dos atributos entre aspas duplas. Se o corpo do JSON também estiver entre aspas duplas, você fará o escape das aspas duplas que estão dentro da política.

• policy-revision-id – o ID de revisão que o Amazon Comprehend atribuiu à política que você está atualizando. Se você estiver criando uma nova política que não tenha uma versão anterior, não use esse parâmetro. O Amazon Comprehend cria o ID de revisão para você.

exemplo Adicionar uma política baseada em recursos a um modelo personalizado usando o comando put-resource-policy

Este exemplo define uma política em um arquivo JSON chamado policyFile.json e associa a política a um modelo. O modelo é a versão v2 de um classificador chamado mycf1.

$ 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
          

O arquivo JSON da política de recursos contém o seguinte conteúdo:

• Ação – a política autoriza o uso de comprehend:ImportModel pelas entidades principais nomeadas.

• Recurso – o ARN do modelo personalizado. O recurso “*” se refere à versão do modelo que você especifica no comando put-resource-policy.

• Entidade principal – a política autoriza o usuário jane da Conta da AWS 444455556666 e todos os usuários da Conta da AWS 123456789012.

{
"Version":"2012-10-17",
 "Statement":[
    {"Sid":"ResourcePolicyForImportModel",
     "Effect":"Allow",
     "Action":["comprehend:ImportModel"],
     "Resource":"*",
     "Principal":
         {"AWS":
            ["arn:aws:iam::444455556666:user/jane",
             "123456789012"]
         }
   }
 ]
}         

API Amazon Comprehend

Para adicionar uma política baseada em recursos a um modelo personalizado usando a API Amazon Comprehend, use a operação da API. PutResourcePolicy

Você também pode adicionar uma política a um modelo personalizado na solicitação de API que cria o modelo. Para fazer isso, forneça a política JSON para o ModelPolicy parâmetro ao enviar uma CreateEntityRecognizersolicitação CreateDocumentClassifieror.

Etapa 2: fornecer os detalhes que outras pessoas precisam importar

Agora que você adicionou a política baseada em recursos ao seu modelo personalizado, você autorizou outros usuários do Amazon Comprehend a importar seu modelo para as Contas da AWS deles. No entanto, você deve fornecer os seguintes detalhes antes que eles possam importar:

• O nome do recurso da Amazon (ARN) da versão do modelo.

• A Região da AWS que contém o modelo. Qualquer pessoa que importe seu modelo deverá usar a mesma Região da AWS.

• Se o modelo é ou não criptografado e, caso seja, o tipo de chave do AWS KMS que você usa: Chave pertencente à AWS ou chave gerenciada pelo cliente.

• Se seu modelo for criptografado com uma chave gerenciada pelo cliente, será necessário fornecer o ARN da chave do KMS. Qualquer pessoa que importe seu modelo deverá incluir o ARN em um perfil de serviço do IAM em sua Conta da AWS. Esse perfil autoriza o Amazon Comprehend a usar a chave do KMS para descriptografar o modelo durante a importação.

Para obter mais informações sobre como outros usuários importam seu modelo, consulte Como importar um modelo personalizado de outra Conta da AWS.