API App Identity para pacotes de serviços legados

ID da região

O REGION_ID é um código abreviado que o Google atribui com base na região que você selecionou ao criar o aplicativo. O código não corresponde a um país ou estado, ainda que alguns IDs de região sejam semelhantes aos códigos de país e estado geralmente usados. Para apps criados após fevereiro de 2020, o REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criados antes dessa data, o ID da região é opcional no URL.

Saiba mais sobre IDs de região.

OK

A API App Identity permite que um aplicativo descubra seu próprio ID, também chamado de ID do projeto. Com esse ID, um aplicativo do App Engine pode confirmar a própria identidade para outros aplicativos do App Engine e APIs do Google, assim como para aplicativos e serviços de terceiros. Ele também pode ser usado para gerar um URL ou endereço de e-mail ou para tomar uma decisão de tempo de execução.

Essa API é compatível com os ambientes de execução de primeira geração e pode ser usada ao fazer upgrade para os ambientes de execução de segunda geração correspondentes. Se você estiver atualizando para o ambiente de execução do PHP 7 ou 8 no App Engine, consulte o guia de migração para saber mais sobre as opções de migração para serviços incluídos no pacote.

Como conseguir o ID do projeto

O ID do projeto pode ser encontrado usando o método AppIdentityService::getApplicationId().

Como conseguir o nome do host do aplicativo

Por padrão, os aplicativos do App Engine são exibidos a partir de URLs no formato https://PROJECT_ID.REGION_ID.r.appspot.com, em que o ID do projeto faz parte do nome do host. Se um aplicativo é disponibilizado de um domínio personalizado, talvez seja necessário recuperar todo o componente do nome do host. Para isso, use o método AppIdentityService::getDefaultVersionHostname().

Como confirmar a identidade para outros apps do App Engine

Se você quiser determinar a identidade do aplicativo do App Engine que está fazendo uma solicitação para o aplicativo do App Engine, use o cabeçalho de solicitação X-Appengine-Inbound-Appid. Esse cabeçalho é adicionado à solicitação pelo serviço URLFetch e não pode ser modificado pelo usuário. Por isso, indica com segurança o ID do projeto do aplicativo solicitante, se houver um.

Requisitos:

• Somente as chamadas feitas para o domínio appspot.com do aplicativo conterão o cabeçalho X-Appengine-Inbound-Appid. Chamadas para domínios personalizados não contêm cabeçalho.
• Suas solicitações precisam ser definidas para não seguir redirecionamentos.

No gerenciador do aplicativo, é possível verificar o ID recebido lendo o cabeçalho X-Appengine-Inbound-Appid e comparando-o a uma lista de IDs com permissão para fazer solicitações.

Como confirmar a identidade das APIs do Google

As APIs do Google usam o protocolo OAuth 2.0 para autenticação e autorização. A API App Identity pode criar tokens OAuth usados para confirmar que a origem de uma solicitação é o próprio aplicativo. O método getAccessToken() retorna um token de acesso para um escopo ou uma lista de escopos. Esse token pode ser configurado nos cabeçalhos HTTP de uma chamada para identificar o aplicativo que fez a chamada.

No exemplo a seguir, mostramos como usar a API App Identity para recuperar contatos do Google Agenda usando o OAuth.

Observação: as bibliotecas de cliente das APIs do Google também podem gerenciar grande parte disso automaticamente.

// Retrieves Google Calendar contacts using OAuth

use google\appengine\api\app_identity\AppIdentityService;

function setAuthHeader() {
  $access_token = AppIdentityService::getAccessToken('https://www.google.com/m8/feeds');
  return [sprintf('Authorization: OAuth %s', $access_token['access_token'])];
}

$get_contacts_url = 'https://www.google.com/m8/feeds/contacts/default/full';
$headers = setAuthHeader();
$opts = [
  'http' => [
    'header' => implode("\r\n", $headers),
  ],
];

$context = stream_context_create($opts);

$response = file_get_contents($get_contacts_url, false, $context);

$xml = simplexml_load_string($response);

$email = $xml->author->email;
$service_account = AppIdentityService::getServiceAccountName();

if (strcmp($email, $service_account) != 0) {
  die(sprintf('%s does not match the service account name %s.',
              $email,
              $service_account));
}

A identidade do aplicativo é representada pelo nome da conta de serviço, que normalmente é [e-mail]. Você pode receber o valor exato usando o método getServiceAccountName(). Para conceder acesso ao aplicativo nos serviços que oferecem ACLs, basta conceder acesso à esta conta.

Como afirmar a identidade para serviços de terceiros

O token gerado por getAccessToken() só funciona nos serviços do Google. No entanto, é possível usar a tecnologia de assinatura subjacente para confirmar a identidade do seu aplicativo a outros serviços. O método signForApp() assina bytes usando uma chave privada exclusiva do seu aplicativo, e o método getPublicCertificates() retornará certificados que podem ser usados para validar a assinatura.

Observação: os certificados podem ser alternados periodicamente, e o método pode retornar vários certificados. Apenas certificados válidos atualmente são retornados. Se você armazenar mensagens assinadas, precisará de um gerenciamento extra de chaves para verificar as assinaturas posteriormente.

Como encontrar o nome padrão do bucket do Cloud Storage

Cada aplicativo pode ter um bucket padrão do Cloud Storage, que inclui 5 GB de armazenamento gratuito e uma cota gratuita para operações de E/S.

Para saber o nome do bucket padrão, chame CloudStorageTools::getDefaultGoogleStorageBucketName. Se preferir, use o valor #default# como o nome do bucket, em que #default# será substituído automaticamente no tempo de execução pelo nome do bucket padrão do aplicativo.