Como Proteger Suas APIs com Esquemas de Segurança OpenAPI

Se você está desenvolvendo ou consumindo APIs, provavelmente sabe o quão importante é protegê-las de acessos não autorizados e uso indevido. APIs são a espinha dorsal de muitos aplicativos modernos e precisam ser protegidas com mecanismos adequados de autenticação e autorização.

Mas como você descreve e documenta os requisitos de segurança de suas APIs? Como você garante que os consumidores da sua API saibam como acessar suas APIs de forma segura e correta? Como você evita confusão e inconsistência entre diferentes APIs e esquemas de segurança?

É aqui que os esquemas de segurança OpenAPI se tornam úteis. OpenAPI é um padrão amplamente utilizado para descrever e documentar APIs em um formato legível por máquina e amigável para humanos. Os esquemas de segurança OpenAPI são uma parte da especificação OpenAPI que permite definir e referenciar os mecanismos de segurança que protegem suas APIs.

Neste post do blog, explicaremos o que são os esquemas de segurança OpenAPI, como funcionam e como você pode usá-los para proteger suas APIs. Também mostraremos alguns exemplos de esquemas de segurança OpenAPI e como usá-los com Apidog, uma ferramenta poderosa para projetar, testar e documentar APIs.

button

O que são Esquemas de Segurança OpenAPI?

Os esquemas de segurança OpenAPI são uma forma de descrever os requisitos de segurança de suas APIs usando a especificação OpenAPI. Eles são definidos na seção components/securitySchemes do seu documento OpenAPI, e podem ser referenciados pela palavra-chave security no nível raiz ou no nível de operação da sua API.

Os esquemas de segurança OpenAPI podem descrever vários tipos de mecanismos de segurança, como:

Chaves de API
Esquemas de autenticação HTTP (Básico, Bearer, etc.)
OAuth 2.0
OpenID Connect

Cada esquema de segurança tem uma propriedade type que indica o tipo do mecanismo de segurança, e outras propriedades que dependem do tipo. Por exemplo, um esquema de segurança de chave de API tem uma propriedade name que especifica o nome do cabeçalho, parâmetro de consulta ou cookie que contém a chave de API, e uma propriedade in que especifica a localização da chave da API.

Aqui está um exemplo de um esquema de segurança de chave de API:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header

Para aplicar um esquema de segurança à sua API ou a uma operação específica, você precisa usar a palavra-chave security e fornecer um array de objetos de requisitos de segurança. Um objeto de requisito de segurança é um mapa de nomes de esquema de segurança para um array de nomes de escopo (para OAuth 2.0 e OpenID Connect) ou um array vazio (para outros tipos).

Por exemplo, para aplicar o esquema de segurança de chave de API a toda a API, você pode usar a seguinte sintaxe:

security:
  - ApiKeyAuth: []

Para aplicar o esquema de segurança de chave de API a uma operação específica, você pode usar a seguinte sintaxe:

paths:
  /pets:
    get:
      security:
        - ApiKeyAuth: []

Você também pode usar múltiplos esquemas de segurança para sua API ou para uma operação específica, seja como alternativas (OU lógico) ou como combinações (E lógico). Por exemplo, para exigir uma chave de API ou um token Bearer para uma operação específica, você pode usar a seguinte sintaxe:

paths:
  /pets:
    get:
      security:
        - ApiKeyAuth: []
        - BearerAuth: []

Para exigir tanto uma chave de API quanto um token Bearer para uma operação específica, você pode usar a seguinte sintaxe:

paths:
  /pets:
    get:
      security:
        - ApiKeyAuth: []
          BearerAuth: []

Por que Usar Esquemas de Segurança OpenAPI?

Os esquemas de segurança OpenAPI têm vários benefícios tanto para provedores quanto para consumidores de API, como:

Eles fornecem uma maneira clara e consistente de descrever os requisitos de segurança de suas APIs, o que pode ajudar a evitar confusão e erros entre diferentes consumidores e desenvolvedores de API.
Eles permitem a geração de documentação interativa e amostras de código que mostram como acessar suas APIs de forma segura e correta, o que pode melhorar a experiência do usuário e reduzir a curva de aprendizado das suas APIs.
Eles facilitam a integração de suas APIs com várias ferramentas e plataformas que suportam a especificação OpenAPI, como Apidog, que pode ajudá-lo a projetar, testar e documentar suas APIs de maneira mais fácil e eficiente.

Como Usar Esquemas de Segurança OpenAPI com Apidog?

Apidog é uma ferramenta poderosa para projetar, testar e documentar APIs. Ela suporta a especificação OpenAPI e permite criar e editar documentos OpenAPI de forma visual e intuitiva. Também fornece recursos como testes ao vivo, servidores simulados, geração de código e documentação interativa.

button

Uma das vantagens de usar Apidog é que ele pode detectar automaticamente e aplicar os esquemas de segurança que você define em seu documento OpenAPI. Por exemplo, se você definir um esquema de segurança de chave de API, o Apidog solicitará que você insira sua chave de API e a envie com suas requisições. Se você definir um esquema de segurança OAuth 2.0, o Apidog o guiará pelo fluxo de autorização e obterá e atualizará o token de acesso para você.

Para usar os esquemas de segurança OpenAPI com Apidog, você precisa seguir estas etapas:

Criar um novo projeto ou importar um documento OpenAPI existente no Apidog.
Definir seus esquemas de segurança na seção components/securitySchemes do seu documento OpenAPI, usando a sintaxe e as propriedades descritas acima.
Referenciar seus esquemas de segurança na palavra-chave security no nível raiz ou no nível de operação da sua API, usando a sintaxe e os valores descritos acima.
Salvar seu documento OpenAPI e mudar para a aba Testar no Apidog.
Select uma operação que exija segurança e clique no botão Segurança no painel direito.
Insira os parâmetros de segurança necessários, como sua chave de API, nome de usuário e senha, ou código de autorização, dependendo do tipo do esquema de segurança.
Clique no botão Enviar para enviar a requisição com os parâmetros de segurança.

O Apidog exibirá a resposta da sua API e mostrará os detalhes da requisição e dos parâmetros de segurança. Você também pode visualizar e editar o documento OpenAPI bruto na aba Código, e gerar documentação interativa e amostras de código nas abas Documentos e Código.

Conclusão

Os esquemas de segurança OpenAPI são um recurso útil da especificação OpenAPI que permite descrever e documentar os requisitos de segurança de suas APIs. Eles podem ajudá-lo a comunicar os mecanismos de segurança que protegem suas APIs para seus consumidores e desenvolvedores de API, além de permitir a geração de documentação interativa e amostras de código que mostram como acessar suas APIs de forma segura e correta.

Eles também podem ajudá-lo a integrar suas APIs com várias ferramentas e plataformas que suportam a especificação OpenAPI, como Apidog, que pode ajudá-lo a projetar, testar e documentar suas APIs de maneira mais fácil e eficiente.

button