Geração de tokens de acesso para APIs do lado do servidor generating-access-tokens-for-server-side-apis

Algumas arquiteturas dependem de fazer chamadas para o Adobe Experience Manager (AEM) as a Cloud Service a partir de um aplicativo hospedado em um servidor fora da infraestrutura do AEM. Por exemplo, um aplicativo móvel chama um servidor, que então faz solicitações de API ao AEM as a Cloud Service.

Use o AEM as a Cloud Service Developer Console para criar uma conta técnica OAuth de servidor para servidor. Seu aplicativo troca sua ID de cliente e o segredo do cliente por um token de acesso usando a concessão client_credentials do Adobe Identity Management Services (IMS). Não é necessário nenhum certificado, chave privada ou JWT assinado.

O fluxo de servidor para servidor the-server-to-server-flow

Usuários com uma função de administrador da organização IMS que também são membros do perfil de produto Usuários do AEM ou Administradores do AEM no AEM Author podem criar uma conta técnica. O segredo do cliente é exibido somente para o usuário que o cria, no momento da criação. Um usuário com a função de administrador de ambiente do AEM as a Cloud Service pode exibir os detalhes da conta, que não incluem o segredo do cliente.

O fluxo de servidor para servidor envolve estas etapas:

Criar uma conta técnica e recuperar suas credenciais fetch-the-aem-as-a-cloud-service-credentials

Para examinar os detalhes de um segredo posteriormente, abra o menu de linha do segredo do cliente e selecione Exibir. A caixa de diálogo de credenciais mostra o endpoint do IMS, os escopos, a ID do cliente, o email da conta técnica, a ID secreta e o status de revogação. Ela não mostra o valor do segredo do cliente.

Instalar as credenciais de serviço do AEM em um servidor que não seja da AEM install-the-aem-service-credentials-on-a-non-aem-server

Disponibilize as credenciais somente para o aplicativo do lado do servidor que chama o AEM. Use um gerenciador de segredos ou outro mecanismo de armazenamento controlado por acesso.

Não coloque um segredo do cliente no código do navegador, em aplicativos móveis, no controle de origem ou em logs. Trate os tokens de acesso como segredos também.

Solicitar um token de acesso OAuth request-an-oauth-access-token

Envie uma solicitação POST HTTPS para https://<imsEndpoint>/ims/token/v3. O imsEndpoint na sua credencial JSON é um nome de host IMS. Por exemplo, ims-na1.adobelogin.com usa https://ims-na1.adobelogin.com/ims/token/v3. Use o nome de host fornecido em suas credenciais, incluindo o nome de host do estágio ao usar credenciais de estágio.

Use Content-Type: application/x-www-form-urlencoded e inclua estes campos de formulário no corpo da solicitação:

Codificação URL de cada valor de formulário. Envie segredos no corpo da solicitação, não no URL ou na sequência de consulta.

A resposta inclui access_token, token_type e expires_in. Use access_token para chamar o AEM. O valor expires_in é o tempo de vida do token em segundos. Use esse valor em vez de considerar um tempo de expiração fixo.

Armazene em cache e reutilize o token de acesso até que sua expiração se aproxime, em seguida, solicite um novo token com as mesmas credenciais de cliente. Esta concessão não requer uma troca JWT ou um token de atualização.

Exemplo de autenticação do Node.js nodejs-authentication-example

Para uma implementação mínima de servidor para servidor do OAuth, consulte o exemplo de Biblioteca de Cliente de API AEM-CS. Ele usa APIs Node.js integradas e requer Node.js 18 ou mais recente, sem dependências adicionais.

O exemplo espera as credenciais dentro de um objeto integration. O arquivo aem-s2s-credentials.json baixado do AEM Developer Console contém as credenciais sem este invólucro. Vincule seu conteúdo antes de usá-lo com o exemplo, por exemplo com jq:

jq '{integration: .}' aem-s2s-credentials.json > downloaded_integration.json

Como alternativa, edite o arquivo para que seu conteúdo completo se torne o valor de um campo integration de nível superior. Em uma verificação do repositório de exemplo, execute:

node oauth-s2s-cli.js downloaded_integration.json

Para uso programático, o auxiliar do OAuth aceita o objeto encapsulado como requestAccessToken(credentials). Ele usa o nome do host IMS, a ID do cliente, o segredo do cliente e os escopos dentro de integration.

Mantenha o arquivo de credencial privado. A CLI imprime um token de acesso. Não envie sua saída para logs compartilhados ou publique-a. O arquivo README do exemplo também mostra como usar o token em uma solicitação de API do AEM.

Chamada da API do AEM calling-the-aem-api

Inclua o token de acesso no cabeçalho Authorization das solicitações para o ambiente AEM as a Cloud Service usando o valor Bearer <access_token>.

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  "https://author-p<program-id>-e<environment-id>.adobeaemcloud.com/content/dam.json"

Use o nome do host para o ambiente e a camada que seu aplicativo acessa. Chame apenas recursos que a conta técnica está autorizada a acessar.

Definir as permissões apropriadas para o usuário da conta técnica no AEM set-the-appropriate-permissions-for-the-technical-account-user-in-aem

Para obter mais informações sobre usuários e grupos do IMS e do AEM, consulte Suporte ao IMS.

Fluxo do desenvolvedor developer-flow

Para testes locais, os desenvolvedores podem gerar um token de acesso de desenvolvimento diretamente no AEM Developer Console sem criar uma conta técnica OAuth de servidor para servidor. O token pode ser usado para chamar ambientes do AEM que o desenvolvedor pode acessar. Use credenciais OAuth de servidor para servidor, em vez de um token de desenvolvimento local, para aplicativos autônomos do lado do servidor.

Consulte as Diretrizes do desenvolvedor para obter as permissões necessárias para usar o AEM Developer Console.

Gerar o token de acesso generating-the-access-token

Chamar o aplicativo AEM com um token de acesso call-the-aem-application-with-an-access-token

Use o token de acesso de desenvolvimento local como um token de portador no cabeçalho Authorization, conforme descrito em Chamando a API AEM.

Para um projeto do AEM em execução em sua máquina local, um token de acesso IMS não é necessário.

Girar segredos do cliente refresh-credentials

As credenciais de servidor para servidor do OAuth não exigem a renovação anual do certificado. Gire os segredos do cliente periodicamente e sempre que um segredo for exposto. Crie um novo segredo, alterne seus aplicativos para ele e, somente então, revogue o segredo antigo.

A criação e revogação de segredos requer os valores secretos que você salvou. O AEM Developer Console usa um segredo inserido somente para autenticar a solicitação com IMS e não o armazena.

Revogação de credenciais credentials-revocation

Revogar desabilita um segredo selecionado para novas solicitações de token. Exige que o valor do segredo seja revogado. A revogação pode demorar para se propagar. Não presuma que revogar um segredo invalida imediatamente os tokens de acesso já emitidos.

Excluir em um segredo revogado remove seus metadados, como a ID do segredo e o status de revogação, do AEM Developer Console. Ela não executa uma revogação IMS separada e não está disponível para segredos ativos.

Excluir uma conta técnica delete-a-technical-account

A exclusão de uma conta técnica revoga imediatamente a conta e todos os seus segredos de cliente no IMS. Nenhum token de acesso novo é emitido para nenhuma credencial na conta, e as integrações que o usam param de funcionar assim que os tokens atuais expiram. Para restaurar o acesso, você deve criar uma nova conta técnica, atualizar seus aplicativos com as credenciais e atribuir as permissões necessárias no AEM novamente.

A exclusão de conta não pode ser desfeita. Confirme somente depois de verificar quais aplicativos dependem da conta e não os use como uma etapa de rotação secreta individual.

Migrar uma integração baseada em JWT migrate-a-jwt-based-integration

Para as operações de certificado e chave privada na conta antiga, consulte o guia herdado do JWT. Não remova a conta antiga antes de verificar a integração de substituição.