Controle de acesso baseado em função do Estúdio de IA do Azure

Neste artigo, você aprenderá a gerenciar o acesso (autorização) a um hub do Estúdio de IA do Azure. O Azure RBAC (controle de acesso baseado em função do Azure) é usado para gerenciar o acesso aos recursos do Azure, como a capacidade de criar novos recursos ou usar os existentes. Os usuários em seu Microsoft Entra ID recebem funções específicas, que concedem acesso aos recursos. O Azure fornece funções internas e a capacidade de criar funções personalizadas.

Hub do Estudo de AI do Azure versus projeto

No Estúdio de IA do Azure, há dois níveis de acesso: o hub e o projeto. O hub de IA abriga a infraestrutura (incluindo a configuração de rede virtual, chaves gerenciadas pelo cliente, identidades gerenciadas e políticas), assim como onde você configura seus serviços de IA do Azure. O acesso ao hub pode permitir que você modifique a infraestrutura, crie novos hubs e crie projetos. Os projetos são um subconjunto do hub que atua como workspaces que permitem criar e implantar sistemas de IA. Em um projeto, você pode desenvolver fluxos, implantar modelos e gerenciar ativos de projeto. O acesso ao projeto permite que você desenvolva a IA de ponta a ponta, aproveitando a configuração da infraestrutura no recurso de IA do Azure.

Um dos principais benefícios do hub de IA e da relação de projeto de IA é que os desenvolvedores podem criar seus próprios projetos que herdam as configurações de segurança do hub de IA. Você também pode ter desenvolvedores que são colaboradores de um projeto e não podem criar novos projetos.

Funções padrão para o hub

O Estúdio de IA do Azure tem funções internas que estão disponíveis por padrão.

Aqui está uma tabela das funções internas e das respectivas permissões:

A principal diferença entre o Colaborador e o Desenvolvedor de IA do Azure é a capacidade de criar recursos de IA do Azure. Se você não quiser que os usuários criem novos hubs (devido à cota, ao custo ou apenas ao gerenciamento de quantos hubs você tem), atribua a função de Desenvolvedor de IA do Azure.

Somente as funções Proprietário e Colaborador permitem que você crie um hub. No momento, as funções personalizadas não podem conceder permissão para criar hubs.

Função de Desenvolvedor de IA do Azure

O conjunto completo de permissões para a função “Desenvolvedor de IA do Azure” é o seguinte:

{
    "Permissions": [ 
        { 
        "Actions": [
            "Microsoft.MachineLearningServices/workspaces/*/read",
            "Microsoft.MachineLearningServices/workspaces/*/action",
            "Microsoft.MachineLearningServices/workspaces/*/delete",
            "Microsoft.MachineLearningServices/workspaces/*/write",
            "Microsoft.MachineLearningServices/locations/*/read",
            "Microsoft.Authorization/*/read",
            "Microsoft.Resources/deployments/*"
        ],
    
        "NotActions": [
            "Microsoft.MachineLearningServices/workspaces/delete",
            "Microsoft.MachineLearningServices/workspaces/write",
            "Microsoft.MachineLearningServices/workspaces/listKeys/action",
            "Microsoft.MachineLearningServices/workspaces/hubs/write",
            "Microsoft.MachineLearningServices/workspaces/hubs/delete",
            "Microsoft.MachineLearningServices/workspaces/featurestores/write",
            "Microsoft.MachineLearningServices/workspaces/featurestores/delete"
        ], 
        "DataActions": [ 
            "Microsoft.CognitiveServices/accounts/OpenAI/*", 
            "Microsoft.CognitiveServices/accounts/SpeechServices/*", 
            "Microsoft.CognitiveServices/accounts/ContentSafety/*" 
        ], 
        "NotDataActions": [], 
        "Condition": null, 
        "ConditionVersion": null 
        } 
    ] 
}

Se a função de Desenvolvedor de IA do Azure integrada não atender às suas necessidades, você poderá criar uma função personalizada.

Funções padrão para projetos

Os projetos do Estúdio de IA do Azure têm funções internas que estão disponíveis por padrão.

Veja uma tabela das funções internas e as respectivas permissões do projeto de IA do Azure:

Quando um usuário recebe acesso a um projeto (por exemplo, por meio do gerenciamento de permissões do AI Studio), mais duas funções são atribuídas automaticamente ao usuário. A primeira função é Leitor no hub. A segunda função é a função Operador de Implantação de Inferência, que permite que o usuário crie implantações no grupo de recursos em que o projeto se encontra. Essa função é composta por essas duas permissões: "Microsoft.Authorization/*/read" e "Microsoft.Resources/deployments/*".

Para concluir o desenvolvimento e a implantação de IA de ponta a ponta, os usuários precisam apenas dessas duas funções atribuídas automaticamente e da função Colaborador ou Desenvolvedor de IA do Azure em um projeto.

As permissões mínimas necessárias para criar um projeto são uma função que tem a ação Microsoft.MachineLearningServices/workspaces/hubs/join permitida no hub. A função interna do Desenvolvedor de IA do Azure tem essa permissão.

Permissões RBAC do serviço de dependência

O hub tem dependências em outros serviços do Azure. A tabela a seguir lista as permissões necessárias para esses serviços ao criar um recurso do hub de IA do Azure. A pessoa que cria o hub precisa dessas permissões. A pessoa que cria um projeto do hub não precisa deles.

Exemplo de configuração de RBAC empresarial

Veja a seguir um exemplo de como configurar o controle de acesso baseado em função para o Estúdio de IA do Azure para uma empresa.

Acesso aos recursos criados fora do hub

Quando você cria um recurso de IA do Azure, as permissões internas de controle de acesso baseado em função permitem a você acesso para usar o recurso. No entanto, se você quiser usar recursos fora do que foi criado em seu nome, precisará verificar o seguinte:

• O recurso que você está tentando usar tem permissões configuradas para permitir que você o acesse.
• Seu hub tem permissão para acessá-lo.

Por exemplo, se você estiver tentando consumir um novo armazenamento de blobs, precisará verificar se a identidade gerenciada do recurso de IA do Azure foi adicionada à função Leitor do Armazenamento de Blobs do Blob. Caso você esteja tentando usar uma nova fonte da Pesquisa de IA do Azure, talvez seja necessário adicionar o recurso de IA do Azure às atribuições de função da Pesquisa de IA do Azure.

Gerenciar o acesso usando funções

Caso você seja proprietário de um hub, é possível adicionar e remover funções do Estúdio de IA. Acesse a home page no Estúdio de IA e selecione seu hub. Em seguida, selecione Usuários para adicionar e remover usuários para o hub. Gerencie também as permissões no portal do Azure em IAM (Controle de Acesso) ou pela CLI do Azure. Por exemplo, use a CLI do Azure para atribuir a função Desenvolvedor de IA do Azure a “joe@contoso.com” no grupo de recursos “this-rg” com o seguinte comando:

az role assignment create --role "Azure AI Developer" --assignee "joe@contoso.com" --resource-group this-rg 

Criar funções personalizadas

Caso as funções internas sejam insuficientes, você poderá criar funções personalizadas. Funções personalizadas podem ter permissões de leitura, gravação, exclusão e recursos de computação neste Estúdio de IA. Você pode tornar a função disponível em níveis específicos do projeto, do grupo de recursos ou da assinatura.

O exemplo JSON a seguir define uma função de desenvolvedor personalizada do Estúdio de IA no nível da assinatura:

{
    "properties": {
        "roleName": "AI Studio Developer",
        "description": "Custom role for AI Studio. At subscription level",
        "assignableScopes": [
            "/subscriptions/<your-subscription-id>"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.MachineLearningServices/workspaces/write",
                    "Microsoft.MachineLearningServices/workspaces/endpoints/write",
                    "Microsoft.Storage/storageAccounts/write",
                    "Microsoft.Resources/deployments/validate/action",
                    "Microsoft.KeyVault/vaults/write",
                    "Microsoft.Authorization/roleAssignments/read",
                    "Microsoft.Authorization/roleDefinitions/read",
                    "Microsoft.CognitiveServices/*/read"
                ],
                "notActions": [
                    "Microsoft.MachineLearningServices/workspaces/delete",
                    "Microsoft.MachineLearningServices/workspaces/write",
                    "Microsoft.MachineLearningServices/workspaces/listKeys/action",
                    "Microsoft.MachineLearningServices/workspaces/hubs/write",
                    "Microsoft.MachineLearningServices/workspaces/hubs/delete",
                    "Microsoft.MachineLearningServices/workspaces/featurestores/write",
                    "Microsoft.MachineLearningServices/workspaces/featurestores/delete"
                ],
                "dataActions": [
                    "Microsoft.CognitiveServices/accounts/OpenAI/*/read",
                    "Microsoft.CognitiveServices/accounts/OpenAI/engines/completions/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/engines/search/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/engines/generate/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/deployments/search/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/deployments/completions/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/deployments/chat/completions/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/deployments/extensions/chat/completions/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/deployments/embeddings/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/images/generations/action"
                ],
                "notDataActions": []
            }
        ]
    }
}

Para saber como criar uma função personalizada, use um dos seguintes artigos:

• Portal do Azure
• CLI do Azure
• PowerShell do Azure

Para obter mais informações sobre como criar funções personalizadas em geral, visite o artigo Funções personalizadas do Azure.

Atribuindo funções no AI Studio

Você pode adicionar usuários e atribuir funções diretamente do IA do Azure Studio no nível do hub ou do projeto. Em uma página de visão geral do hub ou do projeto, selecione Novo usuário para adicionar um usuário.

Em seguida, você será solicitado a inserir as informações do usuário e selecionar uma função integrada.

Cenário: usar uma chave gerenciada pelo cliente

Ao configurar um hub para usar uma CMK (chave gerenciada pelo cliente), um Azure Key Vault é usado para armazenar a chave. O usuário ou a entidade de serviço usada para criar o espaço de trabalho deve ter acesso de proprietário ou colaborador ao cofre de chaves.

Se o hub do IA Studio estiver configurado com uma identidade gerenciada atribuída pelo usuário, a identidade deverá receber as seguintes funções. Essas funções permitem que a identidade gerida crie os recursos Armazenamento do Microsoft Azure, Azure Cosmos DB e Azure Search utilizados ao utilizar uma chave gerida pelo cliente:

• Microsoft.Storage/storageAccounts/write
• Microsoft.Search/searchServices/write
• Microsoft.DocumentDB/databaseAccounts/write

Dentro do cofre de chaves, o usuário ou a entidade de serviço deve ter acesso de criação, obtenção, exclusão e limpeza à chave por meio de uma política de acesso do cofre de chaves. Para obter mais informações, confira Segurança do Azure Key Vault.

Cenário: conexões usando a autenticação do Microsoft Entra ID

Quando criar uma conexão que use a autenticação do Microsoft Entra ID, você precisa atribuir funções aos seus desenvolvedores para que possam acessar o recurso.

Ao usar conexões autenticadas pelo Microsoft Entra ID no playground do chat, os serviços precisam se autorizar mutuamente a acessar os recursos necessários. O administrador que estiver executando a configuração precisa ter a função de Proprietário nesses recursos para adicionar atribuições de função. A tabela a seguir lista as atribuições de função necessárias para cada recurso. A coluna Destinatário se refere à identidade gerenciada atribuída pelo sistema do recurso listado. A coluna Recurso se refere ao recurso que o destinatário precisa acessar. Por exemplo, a OpenAI do Azure tem uma identidade gerenciada atribuída pelo sistema à qual a função de Leitor de Dados do Índice de Pesquisa para o recurso de Pesquisa de IA do Azure precisa ser atribuída.

Cenário: usar um recurso existente do Azure OpenAI

Ao criar uma conexão a um recurso existente do Azure OpenAI, você também deve atribuir funções aos usuários para que eles possam acessar o recurso. Você deve atribuir a função de Usuário do OpenAI de Serviços Cognitivos ou de Colaborador de OpenAI dos Serviços Cognitivos, dependendo das tarefas que eles precisam executar. Para obter informações sobre essas funções e as tarefas que elas habilitam, consulte as funções do Azure OpenAI.

Cenário: usar o Registro de Contêiner do Azure

Uma instância do Registro de Contêiner do Azure é uma dependência opcional para o hub do Estúdio de IA do Azure. A tabela a seguir lista a matriz de suporte ao autenticar um hub no Registro de Contêiner do Azure, dependendo do método de autenticação e da configuração de acesso à rede pública do Registro de Contêiner do Azure.

Uma identidade gerenciada atribuída pelo sistema é atribuída automaticamente às funções corretas quando o hub é criado. Se você estiver usando uma identidade gerenciada atribuída pelo usuário, precisará atribuir a função ACRPull à identidade.

Cenário: usar o Azure Application Insights para registrar em log

O Azure Application Insights é uma dependência opcional para o hub do Estúdio de IA do Azure. A tabela a seguir lista as permissões necessárias se você quiser usar o Application Insights ao criar um hub. A pessoa que cria o hub precisa dessas permissões. A pessoa que cria um projeto do hub não precisa dessas permissões.

Cenário: aquisição de unidade de taxa de transferência provisionada

O exemplo a seguir define uma função personalizada que pode adquirir unidades de taxa de transferência provisionadas (PTU).

{
    "properties": {
        "roleName": "PTU procurer",
        "description": "Custom role to purchase PTU",
        "assignableScopes": [
            "/subscriptions/<your-subscription-id>"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.CognitiveServices/accounts/commitmentplans/read",
                    "Microsoft.CognitiveServices/accounts/commitmentplans/write",
                    "Microsoft.CognitiveServices/accounts/commitmentplans/delete",
                    "Microsoft.CognitiveServices/locations/commitmentTiers/read",
                    "Microsoft.CognitiveServices/accounts/commitmentplans/read",
                    "Microsoft.CognitiveServices/accounts/commitmentplans/write",
                    "Microsoft.CognitiveServices/accounts/commitmentplans/delete",
                    "Microsoft.Features/features/read",
                    "Microsoft.Features/providers/features/read",
                    "Microsoft.Features/providers/features/register/action",
                    "Microsoft.Insights/logDefinitions/read",
                    "Microsoft.Insights/metricdefinitions/read",
                    "Microsoft.Insights/metrics/read",
                    "Microsoft.ResourceHealth/availabilityStatuses/read",
                    "Microsoft.Resources/deployments/operations/read",
                    "Microsoft.Resources/subscriptions/operationresults/read",
                    "Microsoft.Resources/subscriptions/read",
                    "Microsoft.Resources/subscriptions/resourcegroups/deployments/*",
                    "Microsoft.Resources/subscriptions/resourceGroups/read"
                ],
                "notActions": [],
                "dataActions": [],
                "notDataActions": []
            }
        ]
    }
}

Cenário: API de Assistentes da OpenAI do Azure

O exemplo a seguir define uma função para um desenvolvedor usando Assistentes da OpenAI do Azure.

{
    "id": "",
    "properties": {
        "roleName": "Azure OpenAI Assistants API Developer",
        "description": "Custom role to work with Azure OpenAI Assistants API",
        "assignableScopes": [
            "<your-scope>"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.CognitiveServices/*/read",
                    "Microsoft.Authorization/roleAssignments/read",
                    "Microsoft.Authorization/roleDefinitions/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.CognitiveServices/accounts/OpenAI/*/read",
                    "Microsoft.CognitiveServices/accounts/OpenAI/engines/completions/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/engines/search/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/engines/generate/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/deployments/search/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/deployments/completions/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/deployments/chat/completions/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/deployments/extensions/chat/completions/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/deployments/embeddings/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/images/generations/action",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/write",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/read",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/delete",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/files/write",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/files/read",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/files/delete",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/threads/write",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/threads/read",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/threads/delete",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/threads/messages/write",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/threads/messages/read",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/threads/messages/files/read",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/threads/runs/write",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/threads/runs/read",
                    "Microsoft.CognitiveServices/accounts/OpenAI/assistants/threads/runs/steps/read"
                ],
                "notDataActions": []
            }
        ]
    }
}

Solução de problemas

Erro: O principal não tem acesso à API/Operação

Sintomas

Ao usar o playground de chat do IA do Azure Studio, você recebe uma mensagem de erro informando "O diretor não tem acesso à API/operação". O erro também pode incluir um "Apim-request-id".

Causa

O usuário ou entidade de serviço usada para autenticar solicitações ao Azure OpenAI ou ao IA do Azure Search não tem as permissões necessárias para acessar o recurso.

Solução

Atribua as seguintes funções ao usuário ou entidade de serviço. A função que você atribui depende dos serviços que você está usando e do nível de acesso que o usuário ou entidade de serviço requer:

Próximas etapas

• Como criar um hub do Estúdio de IA do Azure
• Como crie um projeto do Estúdio de IA do Azure.
• Como criar uma conexão no Estúdio de IA do Azure