Visão geral da API App Identity para Java 8

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 mais usados. A inclusão de REGION_ID.r em URLs do App Engine é opcional para aplicativos que já existem e, em breve, será obrigatória para todos os aplicativos novos.

Para garantir uma transição tranquila, estamos atualizando gradativamente o App Engine para usar IDs de região. Se ainda não tivermos atualizado seu projeto do Google Cloud, você não verá um ID de região para o aplicativo. Como o ID é opcional para os aplicativos atuais, não é necessário atualizar os URLs ou fazer outras alterações quando o ID de região está disponível para os aplicativos atuais.

Saiba mais sobre IDs de região.

A API App Identity permite que um aplicativo descubra o ID dele (também chamado 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. Também é possível usar o ID do aplicativo para gerar um URL ou endereço de e-mail ou para tomar uma decisão de ambiente de execução.

Como conseguir o ID do projeto

O ID do projeto pode ser encontrado usando o método `ApiProxy.getCurrentEnvironment().getAppId()`.

Como saber 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. Faça isso usando o atributo com.google.appengine.runtime.default_version_hostname do CurrentEnvironment.

@Override
public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
  resp.setContentType("text/plain");
  ApiProxy.Environment env = ApiProxy.getCurrentEnvironment();
  resp.getWriter().print("default_version_hostname: ");
  resp.getWriter()
      .println(env.getAttributes().get("com.google.appengine.runtime.default_version_hostname"));
}

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. As chamadas para domínios personalizados não contêm o cabeçalho.
  • Suas solicitações precisam ser definidas para não seguir redirecionamentos. Se você usar a classe URLFetchService, seu aplicativo precisará especificar doNotFollowRedirect. Os aplicativos em execução no ambiente de execução do Java 8 não usam o serviço URLFetch por padrão. Para ativar o URLFetch, siga estas instruções.
  • Se seu aplicativo usa java.net, atualize seu código para não seguir redirecionamentos:
    connection.setInstanceFollowRedirects(false);

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, veja como usar a API App Identity para fazer uma chamada REST para a API Google URL Shortener.

/**
 * Returns a shortened URL by calling the Google URL Shortener API.
 *
 * <p>Note: Error handling elided for simplicity.
 */
public String createShortUrl(String longUrl) throws Exception {
  ArrayList<String> scopes = new ArrayList<String>();
  scopes.add("https://www.googleapis.com/auth/urlshortener");
  final AppIdentityService appIdentity = AppIdentityServiceFactory.getAppIdentityService();
  final AppIdentityService.GetAccessTokenResult accessToken = appIdentity.getAccessToken(scopes);
  // The token asserts the identity reported by appIdentity.getServiceAccountName()
  JSONObject request = new JSONObject();
  request.put("longUrl", longUrl);

  URL url = new URL("https://www.googleapis.com/urlshortener/v1/url?pp=1");
  HttpURLConnection connection = (HttpURLConnection) url.openConnection();
  connection.setDoOutput(true);
  connection.setRequestMethod("POST");
  connection.addRequestProperty("Content-Type", "application/json");
  connection.addRequestProperty("Authorization", "Bearer " + accessToken.getAccessToken());

  OutputStreamWriter writer = new OutputStreamWriter(connection.getOutputStream());
  request.write(writer);
  writer.close();

  if (connection.getResponseCode() == HttpURLConnection.HTTP_OK) {
    // Note: Should check the content-encoding.
    //       Any JSON parser can be used; this one is used for illustrative purposes.
    JSONTokener responseTokens = new JSONTokener(connection.getInputStream());
    JSONObject response = new JSONObject(responseTokens);
    return (String) response.get("id");
  } else {
    try (InputStream s = connection.getErrorStream();
        InputStreamReader r = new InputStreamReader(s, StandardCharsets.UTF_8)) {
      throw new RuntimeException(
          String.format(
              "got error (%d) response %s from %s",
              connection.getResponseCode(), CharStreams.toString(r), connection.toString()));
    }
  }
}

A identidade do aplicativo é representada pelo nome da conta de serviço, que costuma ser applicationid@appspot.gserviceaccount.com. Para obter o valor exato, use 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 getPublicCertificatesForApp() retornará certificados que podem ser usados para validar a assinatura.

Veja um exemplo que mostra como assinar um blob e validar sua assinatura:
// Note that the algorithm used by AppIdentity.signForApp() and
// getPublicCertificatesForApp() is "SHA256withRSA"

private byte[] signBlob(byte[] blob) {
  AppIdentityService.SigningResult result = appIdentity.signForApp(blob);
  return result.getSignature();
}

private byte[] getPublicCertificate() throws UnsupportedEncodingException {
  Collection<PublicCertificate> certs = appIdentity.getPublicCertificatesForApp();
  PublicCertificate publicCert = certs.iterator().next();
  return publicCert.getX509CertificateInPemFormat().getBytes("UTF-8");
}

private Certificate parsePublicCertificate(byte[] publicCert)
    throws CertificateException, NoSuchAlgorithmException {
  InputStream stream = new ByteArrayInputStream(publicCert);
  CertificateFactory cf = CertificateFactory.getInstance("X.509");
  return cf.generateCertificate(stream);
}

private boolean verifySignature(byte[] blob, byte[] blobSignature, PublicKey pk)
    throws NoSuchAlgorithmException, InvalidKeyException, SignatureException {
  Signature signature = Signature.getInstance("SHA256withRSA");
  signature.initVerify(pk);
  signature.update(blob);
  return signature.verify(blobSignature);
}

private String simulateIdentityAssertion()
    throws CertificateException, UnsupportedEncodingException, NoSuchAlgorithmException,
    InvalidKeyException, SignatureException {
  // Simulate the sending app.
  String message = "abcdefg " + Calendar.getInstance().getTime().toString();
  byte[] blob = message.getBytes();
  byte[] blobSignature = signBlob(blob);
  byte[] publicCert = getPublicCertificate();

  // Simulate the receiving app, which gets the certificate, blob, and signature.
  Certificate cert = parsePublicCertificate(publicCert);
  PublicKey pk = cert.getPublicKey();
  boolean isValid = verifySignature(blob, blobSignature, pk);

  return String.format(
      "isValid=%b for message: %s\n\tsignature: %s\n\tpublic cert: %s",
      isValid, message, Arrays.toString(blobSignature), Arrays.toString(publicCert));
}

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 conseguir o nome do bucket padrão, use a API App Identity. Chame AppIdentityService.getDefaultGcsBucketName.