Abilities API REST: autenticação segura com Application Passwords

Uma Ability registrada no WordPress só se torna útil para uma ferramenta externa quando existe um caminho controlado para descobrir seu contrato, autenticar uma identidade e executar a operação. A Abilities API REST fornece esse caminho; Application Passwords evitam entregar a senha principal da conta para a integração.

Neste tutorial, vamos usar as duas Abilities do plugin-base da série: wp24/site-summary, deliberadamente pública, e wp24/get-post-summary, protegida pela permissão de editar o post solicitado.

Os testes foram executados no WordPress 7.1-RC1 com PHP 8.3. Todas as credenciais eram efêmeras e foram revogadas no final.

O que uma Application Password faz

Application Password é uma credencial individual, revogável e vinculada a um usuário do WordPress. Ela foi criada para acesso programático, não para login interativo no navegador.

O WordPress armazena apenas o hash e mostra o segredo uma vez. Cada integração deve receber uma credencial própria. Assim, você pode revogar um agente, script ou serviço sem trocar a senha principal e sem interromper outras ferramentas.

Autenticar não concede poderes novos. A requisição assume as capabilities do usuário dono da credencial e ainda passa pela permission_callback da Ability.

Pré-requisitos

• WordPress 6.9 ou superior;
• plugin com Abilities marcadas com show_in_rest => true;
• HTTPS em produção;
• usuário dedicado com o menor papel suficiente;
• cliente capaz de enviar Basic Auth.

Application Passwords usam Basic Auth sobre HTTPS. Sem TLS, o cabeçalho pode ser lido por quem interceptar o tráfego. O WordPress normalmente só habilita o recurso em conexões seguras; ambientes locais são uma exceção de desenvolvimento.

Criando a credencial no painel

No WordPress, acesse Usuários → Perfil e localize Senhas de aplicativo. Escolha um nome que identifique a integração, como agente-editorial-producao.

Copie o segredo assim que ele for exibido. Depois disso, o painel mostra nome, data de criação, último uso e último IP, mas não recupera a senha original.

Não use nomes genéricos como API. O nome deve permitir responder rapidamente: qual sistema usa esta credencial e quem é responsável por ele?

Criando e revogando com WP-CLI

Em servidores administrados por SSH, o WP-CLI facilita automação:

wp user application-password create 123 "agente-editorial" --porcelain

O modo --porcelain imprime apenas o segredo. Capture-o em um gerenciador de secrets; não grave em repositório, arquivo de log ou histórico compartilhado.

Para listar credenciais:

wp user application-password list 123 \
  --fields=uuid,name,created,last_used,last_ip

Para revogar uma credencial específica:

wp user application-password delete 123 UUID_DA_CREDENCIAL

Descobrindo as Abilities

O endpoint de coleção exige um usuário autenticado no RC1 testado:

curl --user "USUARIO:SENHA_DE_APLICATIVO" \
  "https://example.com/wp-json/wp-abilities/v1/abilities"

Sem autenticação, o teste retornou HTTP 401 com rest_forbidden. Com a credencial, a resposta foi 200 e incluiu nomes, descrições, schemas, categoria e anotações.

Descoberta não significa autorização para executar tudo. Ela apresenta o catálogo que uma ferramenta usa para planejar chamadas.

Executando uma Ability pública

wp24/site-summary usa __return_true porque devolve apenas nome, URL e idioma públicos:

curl \
  "https://example.com/wp-json/wp-abilities/v1/abilities/wp24/site-summary/run"

O teste retornou 200 mesmo sem credencial. Isso é intencional no plugin didático e demonstra uma regra crucial: Application Password não protege automaticamente uma Ability. Quem define a fronteira é a permission_callback.

Se o resultado não deve ser público, nunca use __return_true apenas para fazer o exemplo funcionar.

Executando uma Ability parametrizada

No WordPress 7.1-RC1 testado, a entrada GET foi enviada como parâmetros aninhados:

curl --get \
  --user "USUARIO:SENHA_DE_APLICATIVO" \
  --data-urlencode "input[post_id]=123" \
  "https://example.com/wp-json/wp-abilities/v1/abilities/wp24/get-post-summary/run"

A documentação oficial também descreve o parâmetro input como JSON codificado na URL. Como este artigo antecede a versão final do WordPress 7.1, confirme o formato no seu build e na documentação atualizada. O princípio não muda: para uma Ability readonly, a execução usa GET e a entrada precisa cumprir o schema.

Por que o papel do usuário importa

Criamos duas credenciais no teste:

• administrador: podia editar o post e recebeu HTTP 200;
• assinante: estava autenticado, mas recebeu HTTP 403 com rest_ability_cannot_execute.

Esse resultado prova que a credencial não contorna a autorização. O fluxo é:

1. Basic Auth identifica o usuário;
2. WordPress carrega suas capabilities;
3. a Ability valida a entrada;
4. a permission_callback verifica o objeto;
5. somente então o callback executa.

Prefira um usuário de integração dedicado. Não conecte todas as ferramentas como administrador por conveniência.

Validando a própria credencial

Uma integração pode consultar os metadados da Application Password usada na requisição:

curl --user "USUARIO:SENHA_DE_APLICATIVO" \
  "https://example.com/wp-json/wp/v2/users/me/application-passwords/introspect"

O endpoint de introspecção retornou 200 no teste. Ele permite confirmar UUID, nome, criação, último uso e último IP sem revelar o segredo.

Revogação precisa ser um teste

Depois de excluir a Application Password administrativa, repetimos a execução protegida com o mesmo segredo. O WordPress retornou HTTP 401 e rest_ability_cannot_execute.

Não basta documentar que a credencial é revogável. Inclua a revogação no teste de implantação e no procedimento de desligamento da integração.

Matriz de testes observada

Checklist de segurança

1. use HTTPS em produção;
2. crie um usuário dedicado para a integração;
3. conceda o menor papel e as menores capabilities possíveis;
4. gere uma Application Password por ferramenta e ambiente;
5. dê nomes identificáveis às credenciais;
6. guarde o segredo em um cofre apropriado;
7. nunca coloque a credencial na URL;
8. não registre o cabeçalho Authorization em logs;
9. mantenha permission_callback específica por Ability;
10. teste usuários autorizados e negados;
11. monitore last_used e last_ip;
12. revogue credenciais inativas ou comprometidas;
13. confirme que o proxy encaminha o cabeçalho Authorization;
14. revise o formato de entrada contra a versão final do WordPress.

Próximo passo: conectando um agente

Agora temos catálogo, contrato, identidade, permissão, execução, auditoria e revogação. A próxima peça vai transformar essas operações REST em ferramentas que um agente consegue selecionar, chamar e interpretar sem receber acesso irrestrito ao site.

Fontes oficiais

• Endpoints REST da Abilities API
• Autenticação da REST API
• Guia de segurança de Application Passwords
• Referência REST de Application Passwords