Controlando o acesso

Com o IBM Cloud® App ID, é possível definir quais usuários e aplicativos podem acessar recursos específicos ou executar ações específicas em seus apps. Para controlar o acesso, é possível criar escopos e agrupá-los em uma função. Em seguida, atribua a função a um ou mais de seus usuários do app e aplicativos.

Um escopo é uma ação de tempo de execução em seu aplicativo que você registra no App ID para criar uma permissão de acesso. Uma função é uma coleção de escopos que atribui permissões variadas a diferentes tipos de usuários do app e aplicativos. Por exemplo, se sua empresa empregar desenvolvedores, eles poderão criar uma função que os permita ler e escrever para o código. Se você empregar auditores, será possível ter uma função de somente visualização, conforme mostrado na imagem a seguir.

Diagrama mostrando o fluxo de trabalho de quatro etapas do controle de acesso App ID: registrar ações em tempo de execução como escopos, compilar escopos em funções, atribuir funções a usuários ou aplicativos e verificar escopos em tokens de acesso em tempo de execução — Como funciona o controle de acesso App ID

Registre ações de tempo de execução que podem ocorrer em seu aplicativo no App ID.
Compile escopos em grupos para formar funções.
Controle permissões de acesso, designando funções para os seus usuários ou aplicativos.
Configure o seu aplicativo para verificar os escopos que são retornados em seu token de acesso de usuários no tempo de execução (ou em seu token de aplicativos se for o fluxo de credenciais do cliente).

Para obter mais informações sobre aplicativos, consulte Identidade e autorização do aplicativo.

Antes de Iniciar

Deve-se ter um aplicativo.
Assegure-se de entender como cada tipo de função e escopo podem impactar o seu aplicativo. Como você está concedendo o acesso, quer ter certeza de que o está concedendo somente às pessoas que precisam dele.
Conheça os limites estabelecidos.

Criação de escopos no console

Um escopo é uma ação de tempo de execução em seu aplicativo que pode ser tomada por usuários que têm concedidas as permissões necessárias para concluí-la. Os escopos são criados quando você registra seu aplicativo no App ID. Se seu app já estiver registrado, será possível editá-lo para incluir os escopos.

Os valores de nomes de escopo devem atender aos requisitos a seguir:

Ser alfanuméricos
Estar em letra minúscula
Não começar com appid ou openid
Não conter caracteres especiais diferentes de pontos (.) ou sublinhados (_)
Ter menos de 50 caracteres.

Para criar um escopo, é possível usar a IU do App ID.

Acesse Aplicativos no painel do App ID.
Clique em Incluir aplicativo para abrir a tela de configuração. Se você já tiver as credenciais que deseja usar, clique em Editar no menu Ações na linha que deseja atualizar.
Dê um nome ao seu app e selecione o tipo dele.
Insira um valor para o seu escopo customizado e clique no símbolo de mais (+). Um valor de escopo de exemplo pode ser read ou write.
Repita a etapa anterior até incluir todos os seus escopos no aplicativo.
Clique em Salvar.

Criando escopos com a API

Os valores de nomes de escopo devem atender aos requisitos a seguir:

Ser alfanuméricos
Estar em letra minúscula
Não começar com appid ou openid
Não conter caracteres especiais diferentes de pontos (.) ou sublinhados (_)
Ter menos de 50 caracteres.

Para criar um escopo, é possível usar a IU do App ID.

Crie os escopos fazendo a solicitação a seguir para o terminal /scopes.

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/scopes"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{\ "scopes":\ [\ <scopesObject>}" ]}"

Variável	Descrição
`region`	A região na qual sua instância do App ID é fornecida. Saiba mais sobre as regiões disponíveis.
`tenantID`	O identificador exclusivo para a sua instância do App ID. É possível localizar esse valor nas credenciais para o seu app, pois elas estão listadas na guia Aplicativos do painel de serviço.
`clientID`	O identificador exclusivo para o seu aplicativo. É possível localizar esse valor nas credenciais para o seu app, pois elas estão listadas em seus Aplicativos no painel de serviço.
`scopesObject`	Um objeto JSON de todos os escopos que você deseja criar para o seu aplicativo.
{: caption="Variáveis necessárias para chamar o ponto de extremidade `/scopes` " caption-side="top"}

Opcional: confirme se os escopos foram criados.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/scopes"
-H "accept: application/json"
-H "Content-Type: application/json"

Criação de funções no console

Uma função é um grupo de escopos que se aplicam a um mesmo tipo de usuário. Por exemplo, se você criar uma função administrativa, a seção de escopos poderá permitir que essa função realize as ações de leitura, gravação ou criação. Porém, se você criar outra função denominada viewer, os usuários aos quais essa função é atribuída terão acesso somente leitura. Para criar uma função, é possível usar a IU do App ID.

Acesse Perfis e funções > Funções no painel do App ID.
Clique em Criar função para abrir a tela de configuração.
Dê um nome e uma descrição à função.
Ao usar os escopos que você criou na seção anterior, designe os escopos a uma função usando o formato a seguir. Clique em + para incluir o escopo.
```
<appName>/<scope>
```
Se você tiver apenas um aplicativo, não precisará especificar o nome de seu app. É possível incluir o escopo sozinho.
Repita a etapa anterior para incluir mais escopos.
Clique em Salvar.

Criando funções com a API

Faça uma solicitação para o terminal /roles para criar a função.

curl -X POST "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles"
-H "accept: application/json"
-H "Content-Type: application/json"
-d { \"name\": \"<roleName>\", \"description\": \"<roleDescription>\", \"access\": [ { \"application_id\": \"<applicationID>\", \"scopes\": [ \"<scopes>" ] } ]}"

Variável	Descrição
`region`	A região na qual sua instância do App ID é fornecida. Saiba mais sobre as regiões disponíveis.
`tenantID`	O identificador exclusivo para a sua instância do App ID. É possível localizar esse valor nas credenciais para o seu app, pois elas estão listadas na guia Aplicativos do painel de serviço.
`clientID`	O identificador exclusivo para o seu aplicativo. É possível localizar esse valor nas credenciais para o seu app, pois elas estão listadas em Aplicativos.
`roleName`	O nome que você deseja designar à sua função.
`roleDescription`	Uma frase curta que descreve o que a sua função deve fazer.
`applicationID`	O identificador exclusivo para o seu aplicativo. É possível localizar esse valor nas credenciais para o seu app, pois elas estão listadas em Aplicativos.
`scopes`	Um objeto JSON de todos os escopos que você deseja aplicar a uma função.
{: caption="Variáveis necessárias para chamar o ponto de extremidade `/scopes` " caption-side="top"}

Opcional: confirme se as funções foram criadas.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles -H "accept: application/json"

A resposta é semelhante ao exemplo a seguir:

{
   "roles": [
   {
      "id": "12345678-1234-1234-1234-123456789012",
      "name": "admin",
      "description": "Can perform administrative tasks.",
      "access": [
         {
         "application_id": "de33d272-f8a7-4406-8fe8-ab28fd457be5",
         "scopes": [
            "create",
            "update",
            "write",
            "read"
         ]
         }
      ]
   }
   {
      "id": "123454231-1234-1234-3334-12345687012",
      "name": "developer",
      "description": "Can perform administrative tasks.",
      "access": [
         {
         "application_id": "de33d272-f8a7-4406-8fe8-ab28fd457be5",
         "scopes": [
            "write",
            "read"
         ]
         }
      ]
   }
   ]
}

Atribuição de funções a usuários no console

Depois de criar funções, é possível designá-las ao perfil do seu usuário. Também é possível designar funções ao criar um usuário futuro.

Acesse Perfis e funções > Perfis de usuário no painel do App ID.
No menu Ações, na linha do usuário específico ao qual você está designando uma função, clique em Designar função.
Selecione a função ou as funções que deseja incluir por meio da lista de funções disponíveis.
Opcional: se você não vir a função que procura, clique em Criar função e forneça as informações para incluir outra opção.
Clique em Salvar.

Designando funções aos usuários com a API

Depois de criar funções, é possível designá-las ao perfil do seu usuário. Também é possível designar funções ao criar um usuário futuro.

Obtenha o seu ID de usuário procurando em seus usuários do App ID com uma consulta de identificação, como um endereço de e-mail.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/Users?query=<identifyingSearchQuery>" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Exemplo:

curl -X GET https://us-south.appid.cloud.ibm.com/management/v4/e19a2778-3262-4986-8875-8khjafsdkhjsdafkjh/cloud_directory/Users?query=example@domain.com
-H "accept: application/json"
-H "authorization: Bearer eyJraWQiOiIyMDE3MTEyOSIsImFsZ...."

Opcional: obtenha o ID da função ou nome da função. Se você já souber o ID ou o nome da função, vá para a próxima etapa.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Faça uma solicitação para o terminal /roles que contém um objeto JSON das funções que você deseja designar.

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/users/<userID>/roles"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{ \"roles\": { \"ids\": [ \"<roleIDs>\" ] }}"
-H "authorization: Bearer <token>"

Para remover uma função de um usuário, faça a solicitação PUT novamente, mas remova o ID da função.

Incluindo funções de usuário em tokens

Por padrão, as funções não são retornadas em um token de usuários. Recomenda-se que as suas decisões de tempo de execução sejam configuradas com base em escopos. Mas, se você desejar usar funções, será possível mapeá-las para seus tokens usando o mapeamento de solicitações customizadas.

Ao autenticar, certifique-se de usar username : client ID e password : secret para o aplicativo e o usuário para os quais você configurou os controles.

Designando funções a um aplicativo

Depois de criar funções, é possível designá-las aos seus aplicativos usando as APIs do App ID.

As funções do aplicativo são válidas apenas no fluxo de credenciais do cliente.

Obtenha o seu ID do aplicativo cliente, consultando a lista de aplicativos. Também é possível obter esse valor por meio da guia Aplicativos da IU do App ID.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Exemplo:

curl -X GET https://us-south.appid.cloud.ibm.com/management/v4/e19a2778-3262-4986-8875-8khjafsdkhjsdafkjh/applications
-H "accept: application/json"
-H "authorization: Bearer eyJraWQiOiIyMDE3MTEyOSIsImFsZ...."

Obtenha o ID de função.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Faça uma solicitação para o terminal /roles que contém um objeto JSON das funções que você deseja designar. Essa solicitação substitui as funções atuais pelos IDs de função fornecidos. Tenha certeza de que você está designando as funções corretas.
```
curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/roles"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{ \"roles\": { \"ids\": [ \"<roleIDs>\" ] }}"
-H "authorization: Bearer <token>"
```

Para remover uma função de um usuário, faça a solicitação PUT novamente, mas remova o ID da função.

Controlando o acesso no tempo de execução

Quando um usuário ou aplicativo tenta acessar um de seus recursos protegidos, os tokens são criados e retornados pelo App ID. Quaisquer escopos com os quais um usuário ou aplicativo é designado são retornados no token de acesso. É possível usar o token de acesso para tomar decisões no tempo de execução. Dependendo da estratégia que você estiver usando para proteger os seus aplicativos, a maneira como você verifica os escopos pode diferir.

Ao usar a estratégia de app da web

É possível usar a estratégia de app da web para verificar se uma solicitação contém algum escopo usando o método hasScope. Quando um usuário com uma função atribuída se conecta, é concedido a ele o acesso por um token do App ID que contém todos os escopos que são definidos na função.Por exemplo, se você estiver trabalhando com o SDK Node.js, o seu fragmento de código será semelhante ao seguinte:

app.get("/protected", passport.authenticate(WebAppStrategy.STRATEGY_NAME), function(req, res){
    if(WebAppStrategy.hasScope(req, "read write")){
              res.json(req.user);
    }
    else {
        res.send("insufficient scopes");
    }
});

Ao usar a estratégia de API

É possível definir os escopos que são necessários para acessar um terminal específico incluindo uma variável de escopo em seu código de estratégia de API. Por exemplo, se você estiver trabalhando com o SDK Node.js, o seu fragmento de código será semelhante ao seguinte.

app.get("/api/protected",
        passport.authenticate(APIStrategy.STRATEGY_NAME, {
                audience: "myApp",
                scope: "read write update"
        }),
        function(req, res) {
                res.send("Hello from protected resource");
        }
);

Compreensão das variáveis usadas com a estratégia de API
Variável	Descrição
`scope`	Os escopos necessários, que são separados por um espaço.
`audience`	O ID do aplicativo cliente

Removendo o acesso

É possível excluir qualquer escopo ou função que não seja mais necessária.

Exclusão de escopos no console

Se você não precisar mais de um escopo, será possível excluí-lo usando a IU do App ID.

Quando você exclui um escopo, ele é removido de todas as funções às quais ele está associado.

É possível usar o painel de serviço do App ID para excluir os escopos.

Acesse Aplicativos no painel do App ID.
No menu Ações na linha do aplicativo para o qual deseja editar os escopos, clique em Editar.
Clique no X na caixa para o escopo que deseja remover.
Clique em Salvar.

Excluindo escopos com a API

Se você não precisar mais de um escopo, será possível excluí-lo usando a API do App ID. Para excluir um escopo, remova-o de seu objeto JSON e faça uma nova solicitação de PUT para o terminal /scopes.

Quando você exclui um escopo, ele é removido de todas as funções às quais ele está associado.

Mude ou exclua um escopo por meio da solicitação a seguir para o terminal /scopes. Certifique-se de atualizar o objeto JSON de seus escopos para conter apenas os escopos que você deseja permitir.

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/scopes"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{\ "scopes":\ [\ <scopesObject>" ]}"

Exclusão de funções no console

Se você não precisar mais de uma função específica, poderá exclui-la usando a IU do App ID.

A exclusão de uma função remove o acesso de todos os usuários e aplicativos que atualmente estão usando a função.

Acesse Perfis e funções > Funções no painel de serviço.
Na linha para a função que deseja excluir, selecione Excluir no menu Ações.
Confirme que você entende que a exclusão da função afeta todos os usuários e aplicativos que estão usando a função atualmente.
Clique em Excluir.

Excluindo funções com a API

Se você não precisar mais de uma função específica, poderá excluí-la usando as APIs do App ID.

A exclusão de uma função remove o acesso de todos os usuários e aplicativos que atualmente estão usando a função.

Obtenha o ID ou o nome da função. Se você já souber o ID ou o nome da função, vá para a próxima etapa.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles"
-H "accept: application/json"

Faça uma solicitação para o terminal /roles que contém um objeto JSON das funções que você deseja designar.

curl -X DELETE "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles/<roleID>"
-H "accept: application/json"