Esta página foi traduzida pela API Cloud Translation.

Configure a autenticação no Artifact Registry para npm

Tem de autenticar-se no Artifact Registry quando usa uma aplicação de terceiros para se ligar a um repositório.

Não precisa de configurar a autenticação para o Cloud Build nem para os ambientes de execução, como o Google Kubernetes Engine e o Cloud Run, mas deve verificar se as autorizações necessárias estão configuradas. Google Cloud

Antes de começar

Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando:
```
gcloud init
```
Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.
(Opcional) Configure as predefinições para os comandos da CLI gcloud.
Se estiver a estabelecer ligação a repositórios a partir do Windows, instale o PowerShell.
Crie uma conta de serviço para agir em nome da sua aplicação.
Se está a usar o npm pela primeira vez, leia a vista geral para saber mais sobre os pacotes com âmbito e o ficheiro de configuração das suas definições de autenticação.

Vista geral

O Artifact Registry suporta os seguintes métodos de autenticação.

Usar um auxiliar de credenciais: Esta opção oferece a maior flexibilidade. Quando inclui o auxiliar na sua configuração do npm, o Artifact Registry procura credenciais da conta de serviço no ambiente.
Especificar uma chave de conta de serviço como credencial: Use esta opção quando uma aplicação não suporta as credenciais predefinidas da aplicação, mas suporta a autenticação com um nome de utilizador e uma palavra-passe.

Autenticação com um auxiliar de credenciais

google-artifactregistry-auth é uma biblioteca cliente que obtém credenciais para repositórios do Artifact Registry.

O Artifact Registry procura credenciais pela seguinte ordem:

Credenciais padrão da aplicação (ADC), uma estratégia que procura credenciais pela seguinte ordem:
1. Credenciais definidas na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.
2. Credenciais fornecidas pela conta de serviço predefinida do Compute Engine, do Google Kubernetes Engine, do Cloud Run, do App Engine ou das funções do Cloud Run.
Credenciais fornecidas pela CLI do Google Cloud, incluindo credenciais de utilizador do comando gcloud auth application-default login.

A variável GOOGLE_APPLICATION_CREDENTIALS torna a conta para autenticação explícita, o que facilita a resolução de problemas. Se não usar a variável, verifique se todas as contas que o ADC possa usar têm as autorizações necessárias. Por exemplo, a conta de serviço predefinida para VMs do Compute Engine, nós do Google Kubernetes Engine e revisões do Cloud Run tem acesso apenas de leitura aos repositórios. Se pretende fazer o carregamento a partir destes ambientes através da conta de serviço predefinida, tem de modificar as autorizações.

Para criar uma conta de serviço e definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS:

Crie uma conta de serviço para agir em nome da sua aplicação ou escolha uma conta de serviço existente que use para a automatização de CI/CD.
Conceda a função do Artifact Registry específica à conta de serviço para fornecer acesso ao repositório.
Atribua a localização do ficheiro de chave da conta de serviço à variável GOOGLE_APPLICATION_CREDENTIALS para que o auxiliar de credenciais do Artifact Registry possa obter a sua chave quando se ligar a repositórios.
```
export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
```
Onde KEY-FILE é o caminho para o ficheiro de chave da conta de serviço.

Para configurar a autenticação:

Execute o seguinte comando para imprimir a configuração do repositório:
```
gcloud artifacts print-settings npm [--project=PROJECT] \
    [--repository=REPOSITORY] \
    [--location=LOCATION] \
    --scope=@SCOPE-NAME \
```
Onde
- PROJECT é o ID do projeto. Se esta flag for omitida, é usado o projeto atual ou predefinido.
- REPOSITORY é o ID do repositório. Se configurou um repositório do Artifact Registry predefinido, este é usado quando esta flag é omitida do comando.
- LOCATION é a localização regional ou multirregional do repositório.
- SCOPE-NAME é o nome do âmbito do npm a associar ao repositório.
  
  A utilização de âmbitos garante que publica e instala sempre pacotes do repositório correto.
  
  Os pacotes sem âmbito estão associados ao seu registo npm predefinido, normalmente, o registo público npm. Se não especificar um âmbito, a configuração devolvida define o repositório do Artifact Registry como o registo predefinido. Isto pode causar problemas se os seus projetos Node.js precisarem de instalar pacotes do registo npm público e do seu repositório do Artifact Registry.
Adicione as definições de configuração devolvidas ao ficheiro de configuração .npmrc nos seus projetos Node.js. Normalmente, este ficheiro encontra-se no mesmo diretório que package.json.

Certifique-se de que inclui estas definições em projetos Node.js para pacotes que publica, bem como projetos que instalam dependências do seu repositório npm.
Se tiver outros repositórios Node.js aos quais estabelecer ligação, repita os passos anteriores para obter as definições e adicione-as aos ficheiros .npmrc adequados.
Quando estiver a postos para associar um repositório, obtenha um token de acesso para autenticação.

Cada repositório de pacotes do Node.js do Artifact Registry está associado a um ponto final do registo https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY

Se não especificou um âmbito com o comando print-settings, pode executar o seguinte comando para associar um âmbito a um repositório do Artifact Registry.

npm config set @SCOPE_NAME:registry https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY/

Obter um token de acesso

As chaves de acesso são válidas durante 60 minutos. Gere um token de acesso pouco tempo antes de executar comandos que interagem com repositórios.

Para obter um token, use uma destas opções:

Use o comando npx para atualizar a chave de acesso.
1. Certifique-se de que as credenciais para estabelecer ligação ao registo npm público estão no ficheiro de configuração npm do utilizador, ~/.npmrc.
2. Execute o seguinte comando no diretório do projeto Node.js.
```
npx google-artifactregistry-auth
```
  Se o seu repositório do Artifact Registry estiver definido como o seu registo global e os seus pacotes não estiverem no âmbito, use o seguinte comando para que o comando possa transferir o auxiliar de credenciais do registo npm público em vez do seu repositório do Artifact Registry.
```
npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
```

Adicione um script ao ficheiro package.json no seu projeto.

"scripts": {
 "artifactregistry-login": "npx google-artifactregistry-auth"
}

Execute o script no diretório do projeto Node.js.

npm run artifactregistry-login

O Artifact Registry lê as definições do repositório do Artifact Registry no ficheiro .npmrc do projeto e usa-as para adicionar credenciais de token ao ficheiro .npmrc do utilizador. Armazenar o token no ficheiro .npmrc do utilizador isola as suas credenciais do código-fonte e do sistema de controlo de origem.

O ficheiro --repo-config é o ficheiro .npmrc com as definições do seu repositório. Se não especificar esta flag, a localização predefinida é o diretório atual.
--credential-config é o caminho para o ficheiro .npmrc onde quer escrever o token de acesso. O predefinido é o ficheiro .npmrc do utilizador.

Configurar a autenticação por palavra-passe

Use esta abordagem quando a sua aplicação Node.js requer autenticação com um nome de utilizador e uma palavra-passe especificados.

As chaves de contas de serviço são credenciais de longa duração. Use as seguintes diretrizes para limitar o acesso aos seus repositórios:

Considere usar uma conta de serviço dedicada para interagir com repositórios.
Conceda a função do Artifact Registry mínima exigida pela conta de serviço. Por exemplo, atribua a função Leitor do Artifact Registry a uma conta de serviço que apenas transfere artefactos.
Se os grupos na sua organização precisarem de diferentes níveis de acesso a repositórios específicos, conceda acesso ao nível do repositório e não ao nível do projeto.
Siga as práticas recomendadas para gerir credenciais.

Para criar uma conta de serviço e configurar a autenticação:

Crie uma conta de serviço para agir em nome da sua aplicação ou escolha uma conta de serviço existente que use para automatização.

Precisa da localização do ficheiro de chave da conta de serviço para configurar a autenticação com o Artifact Registry. Para contas existentes, pode ver as chaves e criar novas chaves na página Contas de serviço.

Aceda à página Contas de serviço

Nota: As chaves de contas de serviço representam um risco de segurança se não forem geridas corretamente. Deve escolher uma alternativa mais segura às chaves de contas de serviço sempre que possível. Se tiver de fazer a autenticação com uma chave de conta de serviço, é responsável pela segurança da chave privada e por outras operações descritas nas Práticas recomendadas de gestão de chaves de contas de serviço. Se não conseguir criar uma chave de conta de serviço, a criação de chaves de contas de serviço pode estar desativada para a sua organização. Para mais informações, consulte o artigo Gerir recursos da organização seguros por predefinição.
Se adquiriu a chave da conta de serviço a partir de uma fonte externa, tem de a validar antes de a usar. Para mais informações, consulte os Requisitos de segurança para credenciais de origem externa.
Conceda a função do Artifact Registry específica à conta de serviço para fornecer acesso ao repositório.
Se quiser ativar a conta de serviço na sessão atual da CLI gcloud, execute o comando:
```
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
```
Onde
- ACCOUNT é o utilizador ou a conta de serviço.
- KEY-FILE é o caminho para o ficheiro de chave JSON da conta de serviço.
Execute o seguinte comando para imprimir a configuração do repositório:
```
gcloud artifacts print-settings npm [--project=PROJECT] \
[--repository=REPOSITORY] [--location=LOCATION] --scope=@SCOPE-NAME --json-key=KEY-FILE
```
Onde
- PROJECT é o ID do projeto. Se esta flag for omitida, é usado o projeto atual ou predefinido.
- REPOSITORY é o ID do repositório. Se configurou um repositório do Artifact Registry predefinido, este é usado quando esta flag é omitida do comando.
- LOCATION é a localização regional ou multirregional do repositório.
- SCOPE-NAME é o nome do âmbito do npm a associar ao repositório.
  
  A utilização de âmbitos garante que publica e instala sempre pacotes do repositório correto.
  
  Os pacotes sem âmbito estão associados ao seu registo npm predefinido, normalmente, o registo público npm. Se não especificar um âmbito, a configuração devolvida define o repositório do Artifact Registry como o registo predefinido. Isto pode causar problemas se os seus projetos Node.js precisarem de instalar pacotes do registo npm público e do seu repositório do Artifact Registry.
- KEY-FILE é o caminho para o ficheiro de chave JSON da conta de serviço.
Nota: as definições de configuração devolvidas incluem um endereço de email de marcador de posição. É necessário um endereço de email na configuração do npm para publicar pacotes npm. O endereço de email do marcador de posição não é usado pelo Artifact Registry para autenticação.
Adicione as definições de configuração devolvidas ao ficheiro de configuração .npmrc nos seus projetos Node.js. Normalmente, este ficheiro encontra-se no mesmo diretório que package.json. Certifique-se de que inclui estas definições em projetos Node.js para pacotes que publica, bem como projetos que instalam dependências do seu repositório npm.
Se tiver outros repositórios do Node.js aos quais se ligar, repita os passos anteriores para obter as definições e adicione-as ao ficheiro .npmrc.