Credenciais de serviço

As integrações com o Adobe Experience Manager (AEM) as a Cloud Service devem ser capazes de autenticar com segurança no serviço de AEM. O Developer Console da AEM concede acesso às Credenciais de serviço, que são usadas para facilitar aplicativos, sistemas e serviços externos para interagir programaticamente com os serviços do AEM Author ou do Publish por HTTP.

O AEM integra-se com outros produtos Adobe usando o S2S OAuth gerenciado pela Adobe Developer Console. Para integrações personalizadas com contas de serviço, as credenciais JWT são usadas e gerenciadas no AEM Developer Console.

As Credenciais de Serviço podem parecer Tokens de Acesso de Desenvolvimento Local semelhantes, mas são diferentes de algumas maneiras principais:

  • As Credenciais de serviço são associadas às Contas técnicas. Várias credenciais de serviço podem estar ativas para uma Conta Técnica.
  • As Credenciais de Serviço são não tokens de acesso, mas são credenciais usadas para obter tokens de acesso.
  • As Credenciais de serviço são mais permanentes (os certificados expiram a cada 365 dias) e não são alteradas, a menos que sejam revogadas, enquanto os Tokens de acesso de desenvolvimento local expiram diariamente.
  • As Credenciais de serviço para um ambiente do AEM as a Cloud Service são mapeadas para um único usuário técnico da conta AEM, enquanto os Tokens de acesso de desenvolvimento local são autenticados como o usuário do AEM que gerou o token de acesso.
  • Um ambiente do AEM as a Cloud Service pode ter até dez contas técnicas, cada uma com suas próprias Credenciais de serviço, cada uma mapeando para um usuário AEM de conta técnica distinto.

As Credenciais de serviço e os tokens de acesso gerados por elas, além dos Tokens de acesso de desenvolvimento local, devem ser mantidos em segredo. Como todos os três podem ser usados para obter, acesse o respectivo ambiente do AEM as a Cloud Service.

Gerar credenciais de serviço

A geração de Credenciais de serviço é dividida em duas etapas:

  1. Uma criação de conta técnica única por um administrador da organização Adobe IMS
  2. O download e o uso das credenciais de serviço da conta técnica JSON

Criar uma conta técnica

As Credenciais de serviço, diferentemente dos Tokens de acesso de desenvolvimento local, exigem que uma Conta técnica seja criada por um Administrador IMS da Adobe Org antes de serem baixadas. Contas técnicas discretas devem ser criadas para cada cliente que requer acesso programático ao AEM.

Criar uma Conta Técnica

As Contas técnicas são criadas uma vez, no entanto, as Chaves privadas usam o para gerenciar Credenciais de serviço associadas à Conta técnica do podem ser gerenciadas ao longo do tempo. Por exemplo, novas Credenciais de chave privada/serviço devem ser geradas antes da expiração da chave privada atual, para permitir o acesso ininterrupto por um usuário das Credenciais de serviço.

  1. Verifique se você está conectado como:

    • Administrador de sistema da Organização IMS da Adobe
    • Membro do Perfil de Produto IMS de Administradores do AEM em Autor do AEM
  2. Faça logon no Adobe Cloud Manager

  3. Abra o Programa que contém o ambiente do AEM as a Cloud Service para integrar e configurar as Credenciais de serviço para

  4. Toque nas reticências ao lado do ambiente na seção Ambientes e selecione Developer Console

  5. Toque na guia Integrações

  6. Toque na guia Contas técnicas

  7. Toque no botão Criar nova conta técnica

  8. As Credenciais de serviço da conta técnica são inicializadas e exibidas como JSON

AEM Developer Console - Integrações - Obter Credenciais de Serviço

Depois que as Credenciais de serviço do ambiente AEM as Cloud Service forem inicializadas, outros desenvolvedores do AEM em sua organização Adobe IMS poderão baixá-las.

Baixar credenciais de serviço

Baixar Credenciais do Serviço

O download das Credenciais de serviço segue as etapas semelhantes à inicialização.

  1. Verifique se você está conectado como:

    • Administrador da organização Adobe IMS
    • Membro do Perfil de Produto IMS de Administradores do AEM em Autor do AEM
  2. Faça logon no Adobe Cloud Manager

  3. Abra o Programa que contém o ambiente do AEM as a Cloud Service para integrar com o

  4. Toque nas reticências ao lado do ambiente na seção Ambientes e selecione Developer Console

  5. Toque na guia Integrações

  6. Toque na guia Contas técnicas

  7. Expanda a Conta técnica a ser usada

  8. Expanda a Chave privada cujas Credenciais de Serviço serão baixadas e verifique se o status é Ativo

  9. Toque em > Exibir associado à Chave Privada, que exibe as Credenciais de Serviço JSON

  10. Toque no botão de download no canto superior esquerdo para baixar o arquivo JSON que contém o valor Credenciais de serviço e salvar o arquivo em um local seguro

Instalar as Credenciais de Serviço

As Credenciais de serviço fornecem os detalhes necessários para gerar um JWT, que é substituído por um token de acesso usado para autenticação com o AEM as a Cloud Service. As Credenciais de Serviço devem ser armazenadas em um local seguro acessível aos aplicativos, sistemas ou serviços externos que as utilizam para acessar o AEM. Como e onde as Credenciais de serviço são gerenciadas são exclusivas por cliente.

Para simplificar, este tutorial passa as Credenciais de serviço no pela linha de comando. No entanto, trabalhe com sua equipe de Segurança de TI para entender como armazenar e acessar essas credenciais de acordo com as diretrizes de segurança de sua organização.

  1. Copie o JSON de Credenciais de Serviço para um arquivo chamado service_token.json na raiz do projeto
    • Lembre-se, nunca confirme nenhuma credencial no Git!

Usar credenciais de serviço

As Credenciais de serviço, um objeto JSON totalmente formado, não são as mesmas que o JWT nem o token de acesso. Em vez disso, as Credenciais de serviço (que contêm uma chave privada) são usadas para gerar um JWT, que é substituído por um token de acesso pelas APIs do Adobe IMS.

Credenciais de Serviço - Aplicativo Externo

  1. Baixar as Credenciais de serviço do AEM Developer Console em um local seguro
  2. O aplicativo externo precisa interagir programaticamente com o ambiente do AEM as a Cloud Service
  3. O Aplicativo Externo lê as Credenciais de Serviço de um local seguro
  4. O aplicativo externo usa informações das credenciais de serviço para criar um token JWT
  5. O token JWT é enviado ao Adobe IMS para troca por um token de acesso
  6. O Adobe IMS retorna um token de acesso que pode ser usado para acessar o AEM as a Cloud Service
    • Os tokens de acesso não podem alterar um tempo de expiração.
  7. O aplicativo externo faz solicitações HTTP ao AEM as a Cloud Service, adicionando o token de acesso como um token de portador ao cabeçalho de autorização das solicitações HTTP
  8. O AEM as a Cloud Service recebe a solicitação HTTP, autentica a solicitação e realiza o trabalho solicitado pela solicitação HTTP e retorna uma resposta HTTP de volta ao Aplicativo externo

Atualizações no aplicativo externo

Para acessar o AEM as a Cloud Service usando as Credenciais de serviço, o aplicativo externo deve ser atualizado de três maneiras:

  1. Ler nas Credenciais de serviço
  • Para simplificar, as Credenciais de serviço são lidas a partir do arquivo JSON baixado. No entanto, em cenários de uso real, as Credenciais de serviço devem ser armazenadas com segurança, de acordo com as diretrizes de segurança de sua organização
  1. Gerar um JWT a partir das Credenciais de serviço
  2. Trocar o JWT por um token de acesso
  • Quando as Credenciais de serviço estão presentes, o aplicativo externo usa esse token de acesso em vez do Token de acesso de desenvolvimento local, ao acessar o AEM as a Cloud Service

Neste tutorial, o módulo Adobe @adobe/jwt-auth npm é usado para ambos, (1) gerar o JWT a partir das Credenciais de serviço e (2) trocá-lo por um token de acesso, em uma única chamada de função. Se o seu aplicativo não for baseado no JavaScript, revise o código de amostra em outros idiomas para saber como criar um JWT a partir das Credenciais de serviço e troque-o por um token de acesso com o Adobe IMS.

Ler as credenciais de serviço

Revise o getCommandLineParams() para ver como o arquivo JSON de Credenciais de Serviço é lido usando o mesmo código usado para ler no JSON do Token de Acesso de Desenvolvimento Local.

function getCommandLineParams() {
    ...

    // Read in the credentials from the provided JSON file
    // Since both the Local Development Access Token and Service Credentials files are JSON, this same approach can be re-used
    if (parameters.file) {
        parameters.developerConsoleCredentials = JSON.parse(fs.readFileSync(parameters.file));
    }

    ...
    return parameters;
}

Criar um JWT e trocar por um token de acesso

Depois que as Credenciais de serviço são lidas, elas são usadas para gerar um JWT, que é então trocado com as APIs do Adobe IMS por um token de acesso. Esse token de acesso pode ser usado para acessar o AEM as a Cloud Service.

Este aplicativo de exemplo é baseado em Node.js, portanto, é melhor usar o módulo @adobe/jwt-auth npm para facilitar a (1) geração de JWT e (20) troca com o Adobe IMS. Se seu aplicativo for desenvolvido usando outra linguagem, revise as amostras de código apropriadas sobre como criar a solicitação HTTP para o Adobe IMS usando outras linguagens de programação.

  1. Atualize o getAccessToken(..) para inspecionar o conteúdo do arquivo JSON e determinar se ele representa um Token de Acesso de Desenvolvimento Local ou Credenciais de Serviço. Isso pode ser feito facilmente verificando a existência da propriedade .accessToken, que só existe para o JSON do Token de Acesso de Desenvolvimento Local.

    Se as Credenciais de serviço forem fornecidas, o aplicativo gerará um JWT e o trocará com o Adobe IMS por um token de acesso. Use a função auth(...) de @adobe/jwt-auth que gera um JWT e o troca por um token de acesso em uma única chamada de função. Os parâmetros para o método auth(..) são um objeto JSON composto de informações específicas disponíveis no JSON de Credenciais de Serviço, conforme descrito abaixo no código.

 async function getAccessToken(developerConsoleCredentials) {

     if (developerConsoleCredentials.accessToken) {
         // This is a Local Development access token
         return developerConsoleCredentials.accessToken;
     } else {
         // This is the Service Credentials JSON object that must be exchanged with Adobe IMS for an access token
         let serviceCredentials = developerConsoleCredentials.integration;

         // Use the @adobe/jwt-auth library to pass the service credentials generated a JWT and exchange that with Adobe IMS for an access token.
         // If other programming languages are used, please see these code samples: https://www.adobe.io/authentication/auth-methods.html#!AdobeDocs/adobeio-auth/master/JWT/samples/samples.md
         let { access_token } = await auth({
             clientId: serviceCredentials.technicalAccount.clientId, // Client Id
             technicalAccountId: serviceCredentials.id,              // Technical Account Id
             orgId: serviceCredentials.org,                          // Adobe IMS Org Id
             clientSecret: serviceCredentials.technicalAccount.clientSecret, // Client Secret
             privateKey: serviceCredentials.privateKey,              // Private Key to sign the JWT
             metaScopes: serviceCredentials.metascopes.split(','),   // Meta Scopes defining level of access the access token should provide
             ims: `https://${serviceCredentials.imsEndpoint}`,       // IMS endpoint used to obtain the access token from
         });

         return access_token;
     }
 }
Agora, dependendo de qual arquivo JSON - o JSON do Token de Acesso de Desenvolvimento Local ou o JSON de Credenciais de Serviço - for transmitido por meio desse parâmetro de linha de comando "file", o aplicativo derivará um token de acesso.

Lembre-se, enquanto as Credenciais de serviço expiram a cada 365 dias, o JWT e o token de acesso correspondente expiram com frequência e precisam ser atualizados antes de expirarem. Isso pode ser feito usando um "refresh_token" [fornecido pelo Adobe IMS](https://www.adobe.io/authentication/auth-methods.html#!AdobeDocs/adobeio-auth/master/OAuth/OAuth.md#access-tokens).
  1. Com essas alterações em vigor, o JSON de Credenciais de Serviço foi baixado do AEM Developer Console e, para simplificar, salvo como service_token.json na mesma pasta que este index.js. Agora, vamos executar o aplicativo substituindo o parâmetro de linha de comando file por service_token.json e atualizando o propertyValue para um novo valor de forma que os efeitos sejam aparentes no AEM.

    code language-shell
    $ node index.js \
        aem=https://author-p1234-e5678.adobeaemcloud.com \
        folder=/wknd-shared/en/adventures/napa-wine-tasting \
        propertyName=metadata/dc:rights \
        propertyValue="WKND Restricted Use" \
        file=service_token.json
    

    A saída para o terminal é semelhante a:

    code language-shell
    200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd-shared/en/adventures/napa-wine-tasting.json
    403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd-shared/en/adventures/napa-wine-tasting/AdobeStock_277654931.jpg.json
    403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd-shared/en/adventures/napa-wine-tasting/AdobeStock_239751461.jpg.json
    403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd-shared/en/adventures/napa-wine-tasting/AdobeStock_280313729.jpg.json
    403 - Forbidden @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd-shared/en/adventures/napa-wine-tasting/AdobeStock_286664352.jpg.json
    

    As linhas 403 - Proibido indicam erros nas chamadas de API HTTP para o AEM as a Cloud Service. Esses erros 403 Proibidos ocorrem ao tentar atualizar os metadados dos ativos.

    O motivo para isso é que o token de acesso derivado de Credenciais de serviço autentica a solicitação para o AEM usando um usuário AEM de conta técnica criado automaticamente, que, por padrão, tem somente acesso de leitura. Para fornecer ao aplicativo acesso de gravação ao AEM, o usuário da conta técnica AEM associado ao token de acesso deve receber permissão no AEM.

Configuração do acesso no AEM

O token de acesso derivado de Credenciais de Serviço usa um Usuário AEM de conta técnica que tem associação no grupo de usuários AEM Colaboradores.

Credenciais de Serviço - Usuário Técnico da Conta AEM

Quando o usuário técnico AEM existir no AEM (após a primeira solicitação HTTP com o token de acesso), as permissões desse usuário AEM AEM poderão ser gerenciadas da mesma forma que os outros usuários do.

  1. Primeiro, localize o nome de logon AEM da conta técnica abrindo o JSON de Credenciais de Serviço baixado do AEM Developer Console e localize o valor integration.email, que deve ser semelhante a: 12345678-abcd-9000-efgh-0987654321c@techacct.adobe.com.
  2. Fazer logon no serviço do autor do ambiente AEM correspondente como um administrador AEM
  3. Navegue até Ferramentas > Segurança > Usuários
  4. Localize o usuário AEM com o Nome de Logon identificado na Etapa 1 e abra suas Propriedades
  5. Navegue até a guia Grupos e adicione o grupo Usuários DAM (que têm acesso de gravação aos ativos)
  6. Toque em Salvar e fechar

Com a conta técnica permitida no AEM para ter permissões de gravação em ativos, execute o aplicativo novamente:

$ node index.js \
    aem=https://author-p1234-e5678.adobeaemcloud.com \
    folder=/wknd-shared/en/adventures/napa-wine-tasting \
    propertyName=metadata/dc:rights \
    propertyValue="WKND Restricted Use" \
    file=service_token.json

A saída para o terminal é semelhante a:

200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd-shared/en/adventures/napa-wine-tasting.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd-shared/en/adventures/napa-wine-tasting/AdobeStock_277654931.jpg.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd-shared/en/adventures/napa-wine-tasting/AdobeStock_286664352.jpg.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd-shared/en/adventures/napa-wine-tasting/AdobeStock_239751461.jpg.json
200 - OK @ https://author-p1234-e5678.adobeaemcloud.com/api/assets/wknd-shared/en/adventures/napa-wine-tasting/AdobeStock_280313729.jpg.json

Verificar as alterações

  1. Faça logon no ambiente AEM as a Cloud Service que foi atualizado (usando o mesmo nome de host fornecido no parâmetro de linha de comando aem)
  2. Navegue até Assets > Arquivos
  3. Navegue até a pasta de ativos especificada pelo parâmetro de linha de comando folder, por exemplo WKND > Inglês > Aventuras > Napa Wine Tasting
  4. Abra as Propriedades de qualquer ativo na pasta
  5. Navegue até a guia Avançado
  6. Revise o valor da propriedade atualizada, por exemplo Copyright que está mapeada para a propriedade JCR metadata/dc:rights atualizada, que agora reflete o valor fornecido no parâmetro propertyValue, por exemplo Uso Restrito de WKND

Atualização de Metadados de Uso Restrito do WKND

Parabéns.

Agora que acessamos programaticamente o AEM as a Cloud Service usando um token de acesso de desenvolvimento local e um token de acesso de serviço para serviço pronto para produção!

recommendation-more-help
e25b6834-e87f-4ff3-ba56-4cd16cdfdec4