Autorização na plataforma iugu

A autorização na plataforma iugu é gerida pelo GIA (Gestão de Identidades e Acessos), é um sistema composto por permissões e políticas, que são atribuídas a cada principal (são os recursos permissionáveis, usuários e aplicativos). Essas permissões e políticas permitem o acesso do principal a determinadas ações, dentro de uma área de trabalho.

Para saber mais a respeito do GIA, permissões, políticas e ações, acesse a documentação do GIA.

Autorização no contexto de aplicativos

Cada aplicativo possui ações que podem ser executadas, seja em sua interface web / mobile ou em sua API. Para saber mais a respeito de ações de aplicativos e autorização acesse a documentação de aplicativos.

Para saber se um principal possui autorização para executar determinada ação do aplicativo em uma determinada área de trabalho, o Identity disponibiliza o endpoint de /verify.

O /verify é um endpoint que recebe como input os principals, que estão querendo executar a ação, as ações a serem executadas e a área de trabalho, onde se deseja verificar essa autorização. O /verify vai responder por ação, se os principals estão autorizados a executar ou não.

Diferença entre o Identity e o modelo padrão do OAuth

Uma das principais diferenças entre o Identity da Iugu e o modelo padrão do OAuth está na forma como os tokens e os escopos são utilizados durante o processo de autorização.

No modelo OAuth padrão:

Quando o client solicita um token ao authorization server, ele já deve informar os escopos necessários para realizar as ações desejadas.
Caso algum dos escopos solicitados não esteja autorizado para aquele client, o authorization server rejeita a solicitação imediatamente.
O controle de permissões é centralizado no momento do consentimento do resource owner para com o client.

No modelo do Identity:

Quando um client solicita um token ao Identity, não é necessário informar escopos. O client apenas especifica o audience, ou seja, a aplicação ou serviço com o qual deseja se comunicar.
O token retornado é genérico e pode ser usado para diferentes verificações. A validação das permissões ocorre posteriormente, quando o token é apresentado ao Resource Server.
O Resource Server faz uma chamada ao endpoint /verify para consultar as permissões do client junto ao Identity (authorization server). Com base na resposta do /verify, o Resource Server decide se a ação solicitada será permitida ou não.

Benefícios do modelo do Identity:

Flexibilidade na emissão de tokens:
- Os tokens são genéricos, sem dependência de escopos previamente definidos.
Atualizações em tempo real:
- Alterações nas permissões ou políticas são refletidas imediatamente, pois a validação ocorre no /verify em cada chamada.
Separação de responsabilidades:
- O authorization server cuida apenas da emissão e validação de permissões, enquanto o Resource Server decide a autorização com base nas respostas do /verify.
Granularidade de permissões:
- Permissões são gerenciadas com base em ações específicas (ex.: billing:events:create), em vez de escopos amplos como read ou write.

Exemplo de fluxo no Identity:

O client solicita um token com um audience específico:

POST /token HTTP/1.1
Host: identity.iugu.com
Content-Type: application/json

{
    "client_id": "app_id",
    "client_secret": "app_secret",
    "audience": "Iugu.Platform.resource_server_id",
    "grant_type": "client_credentials"
}

Resposta:

{
    "access_token": "eyJhbGciOi...",
    "token_type": "Bearer",
    "expires_in": 3600
}

O client usa o token para acessar um recurso no Resource Server, que faz uma chamada ao /verify:

POST /verify HTTP/1.1
Host: identity.iugu.com
Authorization: Bearer 
Content-Type: application/json

{
    "workspace_id": "workspace_id",
    "principals": [
        "app:2PC8oKnGzMJUTFJvhtdrlo"
    ],
    "actions": [
        "barbecues:create"
    ]
}

Com base na resposta do /verify, o Resource Server responde ao client:

Caso autorizado:

{
    "barbecues:create": true
}

Caso não autorizado:

{
    "barbecues:create": false
}

Esse modelo permite maior flexibilidade e controle granular sobre as permissões e ações executadas dentro da plataforma Iugu.

Camadas adicionais de segurança

Validação de IP (`ip_address`)

Essa funcionalidade permite verificar se a solicitação foi feita a partir de um IP permitido (whitelist). É útil para restringir acessos de usuários ou aplicações com base em redes específicas.

Saiba como criar e validar mascaras de IP aqui

Exemplo de Requisição:

POST /verify HTTP/1.1
Host: identity.iugu.com
Authorization: Bearer 
Content-Type: application/json

{
    "workspace_id": "2eRMu8YTMmyNHgNCXWdqe3",
    "principals": [
        {
            "principal": "app:6dOUpOVaC7FNOdFtKxEiLi",
            "ip_address": "192.168.12.1"
        }
    ],
    "actions": [
        "barbecues:create"
    ]
}

Exemplo de Resposta:

{
    "barbecues:create": true
}

Validação de Certificado (`certificate_thumbprint`)

Essa funcionalidade garante que o certificado mTLS apresentado é válido e corresponde ao principal que está realizando a solicitação. É ideal para proteger rotas sensíveis, como operações financeiras.

Saiba como criar e revogar certificados aqui

Exemplo de Requisição:

POST /verify HTTP/1.1
Host: identity.iugu.com
Authorization: Bearer 
Content-Type: application/json

{
    "workspace_id": "2eRMu8YTMmyNHgNCXWdqe3",
    "principals": [
        {
            "principal": "app:6dOUpOVaC7FNOdFtKxEiLi",
            "certificate_thumbprint": "9d9d0d20f2b1441c7c7bd0f83aa42007b78ca8f973f8e2af6f084e62bf740570"
        }
    ],
    "actions": [
        "pix:cob.write"
    ]
}

Exemplo de Resposta:

{
    "pix:cob.write": true
}

Pontos importantes do /verify

É importante ressaltar que o /verify aceita múltiplos principals, então é possível autorizar mais de um principal ao mesmo tempo, porém, neste cenário com mais de um principal, todos os principals envolvidos precisam estarem aptos a executarem a ação solicitada.

Boas práticas ao utilizar o /verify

Existem algumas boas práticas que gostaríamos de destacar com relação ao uso do endpoint de /verify.

Uso em interfaces web
Perceba que o /verify aceita múltiplas actions no mesmo request, essa estrutura permite que sua aplicação solicite o permissionamento de um usuário para todas as actions que existem em sua interface web de uma só vez, tornando assim a comunicação com o Identity mais simples, deste modo sua aplicação pode montar um sistema de cache que pode ser invalidado a depender da criticidade de cada ação, ou seja, ações mais criticas mantém um cache que expira de maneira mais rápida e ações menos criticas mantém um cache de maior duração.
Uso em API O mesmo sistema de cache utilizado em interfaces web pode ser empregado pela API, tomando-se o cuidado de identificar ações criticas que podem ter um cache com menor TTL ou até mesmo serem real time, chamando o /verify em todos os requests.

Voltar

Autenticação na plataforma iugu

Avançar

Authorization Code

Nesta página