Acompanhe tudo o que foi anunciado no Firebase Summit e saiba como usar o Firebase para acelerar o desenvolvimento de apps e executá-los com confiança. Saiba mais

Autorizar solicitações de envio

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

As solicitações enviadas ao FCM de seu servidor de aplicativos ou ambiente confiável devem ser autorizadas. Observe estas diferenças importantes entre HTTP herdado e autorização de API HTTP v1:

  • A API FCM HTTP v1 autoriza solicitações com um token de acesso OAuth 2.0 de curta duração. Para criar esse token, você pode usar o Google Application Default Credentials (em ambientes de servidor do Google) e/ou obter manualmente as credenciais necessárias de um arquivo de chave privada JSON gerado para uma conta de serviço. Se você estiver usando o Firebase Admin SDK para enviar mensagens, a biblioteca processará o token para você.
  • Os protocolos legados podem usar apenas chaves de API de longa duração obtidas no console do Firebase.

Autorizar solicitações de envio HTTP v1

Dependendo dos detalhes do seu ambiente de servidor, use uma combinação dessas estratégias para autorizar solicitações de servidor aos serviços do Firebase:

  • Credenciais padrão do aplicativo do Google (ADC)
  • Um arquivo JSON da conta de serviço
  • Um token de acesso OAuth 2.0 de curta duração derivado de uma conta de serviço

Se seu aplicativo estiver em execução no Compute Engine, Google Kubernetes Engine, App Engine ou Cloud Functions (incluindo Cloud Functions para Firebase), use o Application Default Credentials (ADC). O ADC usa sua conta de serviço padrão existente para obter credenciais para autorizar solicitações, e o ADC permite testes locais flexíveis por meio da variável de ambiente GOOGLE_APPLICATION_CREDENTIALS . Para a automação mais completa do fluxo de autorização, use o ADC junto com as bibliotecas do servidor Admin SDK.

Se seu aplicativo estiver sendo executado em um ambiente de servidor que não seja do Google , você precisará fazer o download de um arquivo JSON de conta de serviço de seu projeto do Firebase. Contanto que você tenha acesso a um sistema de arquivos contendo o arquivo de chave privada, você pode usar a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para autorizar solicitações com essas credenciais obtidas manualmente. Se você não tiver esse acesso ao arquivo, deverá fazer referência ao arquivo da conta de serviço em seu código, o que deve ser feito com extremo cuidado devido ao risco de expor suas credenciais.

Forneça credenciais usando o ADC

O Google Application Default Credentials (ADC) verifica suas credenciais na seguinte ordem:

  1. O ADC verifica se a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS está definida. Se a variável for definida, o ADC usará o arquivo de conta de serviço para o qual a variável aponta.

  2. Se a variável de ambiente não estiver definida, o ADC usará a conta de serviço padrão fornecida pelo Compute Engine, Google Kubernetes Engine, App Engine e Cloud Functions para aplicativos executados nesses serviços.

  3. Se o ADC não puder usar nenhuma das credenciais acima, o sistema lançará um erro.

O exemplo de código Admin SDK a seguir ilustra essa estratégia. O exemplo não especifica explicitamente as credenciais do aplicativo. No entanto, o ADC é capaz de encontrar implicitamente as credenciais, desde que a variável de ambiente esteja definida ou enquanto o aplicativo estiver em execução no Compute Engine, Google Kubernetes Engine, App Engine ou Cloud Functions.

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

Java

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Pitão

default_app = firebase_admin.initialize_app()

Vai

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C #

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

Fornecer credenciais manualmente

Os projetos do Firebase oferecem suporte a contas de serviço do Google , que você pode usar para chamar APIs do servidor Firebase de seu servidor de aplicativos ou ambiente confiável. Se você estiver desenvolvendo código localmente ou implantando seu aplicativo no local, poderá usar as credenciais obtidas por meio dessa conta de serviço para autorizar solicitações de servidor.

Para autenticar uma conta de serviço e autorizá-la a acessar os serviços do Firebase, você deve gerar um arquivo de chave privada no formato JSON.

Para gerar um arquivo de chave privada para sua conta de serviço:

  1. No console do Firebase, abra Configurações > Contas de serviço .

  2. Clique em Gerar nova chave privada e confirme clicando em Gerar chave .

  3. Armazene com segurança o arquivo JSON que contém a chave.

Ao autorizar por meio de uma conta de serviço, você tem duas opções para fornecer as credenciais ao seu aplicativo. Você pode definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS ou passar explicitamente o caminho para a chave da conta de serviço no código. A primeira opção é mais segura e é fortemente recomendada.

Para definir a variável de ambiente:

Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Esta variável aplica-se apenas à sua sessão de shell atual, portanto, se você abrir uma nova sessão, defina a variável novamente.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

janelas

Com PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Depois de concluir as etapas acima, o Application Default Credentials (ADC) pode determinar implicitamente suas credenciais, permitindo que você use as credenciais da conta de serviço ao testar ou executar em ambientes que não sejam do Google.

Use credenciais para criar tokens de acesso

A menos que você esteja usando o Admin SDK , que processa a autorização automaticamente, você precisará criar o token de acesso e adicioná-lo para enviar solicitações.

Use suas credenciais do Firebase junto com a biblioteca Google Auth para seu idioma preferido para recuperar um token de acesso OAuth 2.0 de curta duração:

node.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    const key = require('../placeholders/service-account.json');
    const jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

Neste exemplo, a biblioteca cliente da API do Google autentica a solicitação com um token da web JSON ou JWT. Para obter mais informações, consulte tokens da web JSON .

Pitão

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = service_account.Credentials.from_service_account_file(
    'service-account.json', scopes=SCOPES)
  request = google.auth.transport.requests.Request()
  credentials.refresh(request)
  return credentials.token

Java

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}

Após a expiração do token de acesso, o método de atualização do token é chamado automaticamente para recuperar um token de acesso atualizado.

Para autorizar o acesso ao FCM, solicite o escopo https://www.googleapis.com/auth/firebase.messaging .

Para adicionar o token de acesso a um cabeçalho de solicitação HTTP:

Adicione o token como o valor do cabeçalho Authorization no formato Authorization: Bearer <access_token> :

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}

Pitão

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}

Java

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;

Autorizar solicitações de envio de protocolo herdado

Com o protocolo HTTP herdado, cada solicitação deve conter a chave do servidor da guia Cloud Messaging do painel Configurações do Firebase console. Para XMPP, você deve usar a mesma chave de servidor para estabelecer uma conexão.

Migrar chaves de servidor herdadas

A partir de março de 2020, o FCM parou de criar chaves de servidor herdadas. As chaves de servidor herdadas existentes continuarão funcionando, mas recomendamos que você use a versão mais recente da chave denominada Chave do servidor no Firebase console .

Se você deseja excluir uma chave de servidor herdada existente, pode fazê-lo no Google Cloud Console .

Autorizar solicitações HTTP

Uma solicitação de mensagem consiste em duas partes: o cabeçalho HTTP e o corpo HTTP. O cabeçalho HTTP deve conter os seguintes cabeçalhos:

  • Authorization : key=YOUR_SERVER_KEY
    Certifique-se de que esta é a chave do servidor , cujo valor está disponível na guia Cloud Messaging do painel Configurações do Firebase console. Android, plataforma Apple e chaves de navegador são rejeitadas pelo FCM.
  • Content-Type : application/json para JSON; application/x-www-form-urlencoded;charset=UTF-8 para texto simples.
    Se Content-Type for omitido, o formato será considerado texto simples.

Por exemplo:

Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
  "data" : {
    ...
  },
}

Consulte Construir solicitações de envio para obter detalhes completos sobre como criar solicitações de envio. A referência do protocolo HTTP herdado fornece uma lista de todos os parâmetros que sua mensagem pode conter.

Verificando a validade de uma chave de servidor

Se você receber erros de autenticação ao enviar mensagens, verifique a validade da sua chave do servidor. Por exemplo, no Linux, execute o seguinte comando:

api_key=YOUR_SERVER_KEY

curl --header "Authorization: key=$api_key" \
     --header Content-Type:"application/json" \
     https://fcm.googleapis.com/fcm/send \
     -d "{\"registration_ids\":[\"ABC\"]}"

Se você receber um código de status HTTP 401, sua chave do servidor não é válida.

Autorizar uma conexão XMPP

Com o XMPP, você pode manter uma conexão persistente, assíncrona e bidirecional com servidores FCM. A conexão pode ser usada para enviar e receber mensagens entre seu servidor e os dispositivos conectados ao FCM de seus usuários.

Você pode usar a maioria das bibliotecas XMPP para gerenciar uma conexão de longa duração com o FCM. O endpoint XMPP é executado em fcm-xmpp.googleapis.com:5235 . Ao testar a funcionalidade com usuários que não são de produção, você deve se conectar ao servidor de pré-produção em fcm-xmpp.googleapis.com:5236 (observe a porta diferente).

O teste regular na pré-produção (um ambiente menor onde as compilações mais recentes do FCM são executadas) é benéfico para isolar usuários reais do código de teste. Os dispositivos de teste e o código de teste que se conectam a fcm-xmpp.googleapis.com:5236 devem usar um ID de remetente FCM diferente para evitar qualquer risco de enviar mensagens de teste para usuários de produção ou enviar mensagens upstream do tráfego de produção em conexões de teste.

A conexão tem dois requisitos importantes:

  • Você deve iniciar uma conexão TLS (Transport Layer Security). Observe que o FCM atualmente não oferece suporte à extensão STARTTLS .
  • O FCM requer um mecanismo de autenticação SASL PLAIN usando <your_FCM_Sender_Id>@fcm.googleapis.com (FCM sender ID ) e a chave do servidor como senha. Esses valores estão disponíveis na guia Cloud Messaging do painel Configurações do Firebase console.

Se em algum momento a conexão falhar, você deve reconectar imediatamente. Não há necessidade de recuar após uma desconexão que ocorre após a autenticação. Para cada ID do remetente , o FCM permite 2500 conexões em paralelo.

Os snippets a seguir ilustram como executar autenticação e autorização para uma conexão XMPP ao FCM.

servidor XMPP

O servidor XMPP solicita uma conexão com o FCM

<stream:stream to="fcm.googleapis.com"
        version="1.0" xmlns="jabber:client"
        xmlns:stream="http://etherx.jabber.org/streams">

FCM

O FCM abre a conexão e solicita um mecanismo de autenticação, incluindo o método PLAIN .

<stream:features>
  <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl">
    <mechanism>X-OAUTH2</mechanism>
    <mechanism>X-GOOGLE-TOKEN</mechanism>
    <mechanism>PLAIN</mechanism>
  </mechanisms>
</stream:features>

servidor XMPP

O servidor XMPP deve responder usando o método de autenticação PLAIN , fornecendo a chave do servidor na guia Cloud Messaging do painel Configurações do Firebase console.

<auth mechanism="PLAIN"
xmlns="urn:ietf:params:xml:ns:xmpp-sasl">MTI2MjAwMzQ3OTMzQHByb2plY3RzLmdjbS5hb
mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth>

FCM

<success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>

servidor XMPP

<stream:stream to="fcm.googleapis.com"
        version="1.0" xmlns="jabber:client"
        xmlns:stream="http://etherx.jabber.org/streams">

FCM

<stream:features>
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"/>
  <session xmlns="urn:ietf:params:xml:ns:xmpp-session"/>
</stream:features>

servidor XMPP

<iq type="set">
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"></bind>
</iq>

FCM

<iq type="result">
  <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind">
    <jid>SENDER_ID@fcm.googleapis.com/RESOURCE</jid>
  </bind>
</iq>

Observação: o FCM não usa o recurso vinculado durante o roteamento de mensagens.

Consulte Construir solicitações de envio para obter detalhes completos sobre como criar solicitações de envio. A referência do protocolo Legacy XMPP fornece uma lista de todos os parâmetros que sua mensagem pode conter.