Iniciar sessão de utilizadores com a Apple

Este documento mostra como usar a Identity Platform para adicionar a opção Iniciar sessão com a Apple à sua app Web.

Antes de começar

  • Ativar a Identity Platform e ter uma app Web básica escrita em HTML e JavaScript. Para saber como ativar a Identity Platform e iniciar sessão, consulte o início rápido.

  • Adira ao Apple Developer Program.

Configurar a sua app com a Apple

No site do programador da Apple:

  1. Siga os passos em Configure o início de sessão com a Apple para a Web. Isto inclui:

    1. Registar um URL de retorno, que tem o seguinte aspeto:

      https://project-id.firebaseapp.com/__/auth/handler

    2. A alojar temporariamente um ficheiro no seguinte URL para validar o seu domínio:

      https://project-id.firebaseapp.com/.well-known/apple-developer-domain-association.txt

    Além disso, tome nota do seu ID dos serviços e ID da equipa Apple. Vai precisá-los na secção seguinte.

  2. Use uma chave privada da Apple para criar um início de sessão. Vai precisar da chave e do respetivo ID na secção seguinte.

  3. Se usar a Identity Platform para enviar emails aos seus utilizadores, configure o seu projeto com o serviço de retransmissão de email privado da Apple usando o seguinte email:

    noreply@project-id.firebaseapp.com

    Também pode usar um modelo de email personalizado, se a sua app tiver um.

Agir em conformidade com os requisitos de dados anónimos da Apple

A Apple dá aos utilizadores a opção de anonimizar os respetivos dados, incluindo o endereço de email. A Apple atribui aos utilizadores que selecionam esta opção um endereço de email ocultado com o domínio privaterelay.appleid.com.

A sua app tem de estar em conformidade com todas as políticas ou termos de programadores aplicáveis da Apple relativamente a IDs Apple anónimos. Isto inclui obter o consentimento do utilizador antes de associar quaisquer informações de identificação pessoal (IIP) a um ID Apple anónimo. As ações que envolvem PII incluem, entre outras:

  • Associar um endereço de email a um ID Apple anónimo ou vice-versa.
  • Associar um número de telefone a um ID Apple anónimo ou vice-versa
  • Associar uma credencial social não anónima, como o Facebook ou o Google, a um ID Apple anónimo ou vice-versa.

Para mais informações, consulte o Contrato de Licença do Programa para Programadores da Apple para a sua conta de programador da Apple.

Configurar a Apple como fornecedor

Para configurar a Apple como um Fornecedor de identidade:

  1. Aceda à página Fornecedores de identidade na Google Cloud consola.

    Aceda à página Fornecedores de identidade

  2. Clique em Adicionar um fornecedor.

  3. Selecione Apple na lista.

  4. Em Plataforma, selecione Web.

  5. Introduza o seu ID de serviços, ID da equipa Apple, ID da chave e chave privada.

  6. Registe os domínios da sua app clicando em Adicionar domínio em Domínios autorizados. Para fins de programação, o localhost já está ativado por predefinição.

  7. Em Configure a sua aplicação, clique em Detalhes da configuração. Copie o fragmento para o código da sua app para inicializar o SDK do cliente do Identity Platform.

  8. Clique em Guardar.

Iniciar sessão de utilizadores com o SDK do cliente

Para iniciar sessão de um utilizador:

  1. Crie uma instância do objeto fornecedor OAuthProvider com o ID apple.com:

    Versão Web 9

    import { OAuthProvider } from "firebase/auth";

const provider = new OAuthProvider('apple.com');
    auth_apple_provider_create.js

    Versão Web 8

    var provider = new firebase.auth.OAuthProvider('apple.com');
    apple.js

  2. Opcional: adicione âmbitos do OAuth. Os âmbitos especificam os dados que está a pedir à Apple. Os dados mais confidenciais podem exigir âmbitos específicos. Por predefinição, quando a opção Uma conta por endereço de email está ativada, o Identity Platform pede os âmbitos email e name.

    Versão Web 9

    provider.addScope('email');
provider.addScope('name');
    auth_apple_provider_scopes.js

    Versão Web 8

    provider.addScope('email');
provider.addScope('name');
    apple.js

  3. Opcional: localize o fluxo de autenticação. Pode especificar um idioma ou usar o idioma predefinido do dispositivo. Consulte os documentos de início de sessão com a Apple para ver as localizações suportadas.

    Versão Web 9

    provider.setCustomParameters({
  // Localize the Apple authentication screen in French.
  locale: 'fr'
});
    auth_apple_provider_params.js

    Versão Web 8

    provider.setCustomParameters({
  // Localize the Apple authentication screen in French.
  locale: 'fr'
});
    apple.js

  4. Use o objeto do fornecedor para iniciar sessão no utilizador. Pode abrir uma janela de pop-up ou redirecionar a página atual. O redirecionamento é mais fácil para os utilizadores em dispositivos móveis.

    Para mostrar um pop-up, chame signInWithPopup():

    Versão Web 9

    import { getAuth, signInWithPopup, OAuthProvider } from "firebase/auth";

const auth = getAuth();
signInWithPopup(auth, provider)
  .then((result) => {
    // The signed-in user info.
    const user = result.user;

    // Apple credential
    const credential = OAuthProvider.credentialFromResult(result);
    const accessToken = credential.accessToken;
    const idToken = credential.idToken;

    // IdP data available using getAdditionalUserInfo(result)
    // ...
  })
  .catch((error) => {
    // Handle Errors here.
    const errorCode = error.code;
    const errorMessage = error.message;
    // The email of the user's account used.
    const email = error.customData.email;
    // The credential that was used.
    const credential = OAuthProvider.credentialFromError(error);

    // ...
  });
    auth_apple_signin_popup.js

    Versão Web 8

    firebase
  .auth()
  .signInWithPopup(provider)
  .then((result) => {
    /** @type {firebase.auth.OAuthCredential} */
    var credential = result.credential;

    // The signed-in user info.
    var user = result.user;

    // You can also get the Apple OAuth Access and ID Tokens.
    var accessToken = credential.accessToken;
    var idToken = credential.idToken;

    // IdP data available using getAdditionalUserInfo(result)
  // ...
  })
  .catch((error) => {
    // Handle Errors here.
    var errorCode = error.code;
    var errorMessage = error.message;
    // The email of the user's account used.
    var email = error.email;
    // The firebase.auth.AuthCredential type that was used.
    var credential = error.credential;

    // ...
  });
    apple.js

    Para redirecionar a página, chame primeiro signInWithRedirect():

    Siga as práticas recomendadas quando usar signInWithRedirect, linkWithRedirect ou reauthenticateWithRedirect.

    Versão Web 9

    import { getAuth, signInWithRedirect } from "firebase/auth";

const auth = getAuth();
signInWithRedirect(auth, provider);
    auth_apple_signin_redirect.js

    Versão Web 8

    firebase.auth().signInWithRedirect(provider);
    apple.js

    Em seguida, chame getRedirectResult() para obter o token da Apple quando a página for carregada:

    Versão Web 9

    import { getAuth, getRedirectResult, OAuthProvider } from "firebase/auth";

// Result from Redirect auth flow.
const auth = getAuth();
getRedirectResult(auth)
  .then((result) => {
    const credential = OAuthProvider.credentialFromResult(result);
    if (credential) {
      // You can also get the Apple OAuth Access and ID Tokens.
      const accessToken = credential.accessToken;
      const idToken = credential.idToken;
    }
    // The signed-in user info.
    const user = result.user;
  })
  .catch((error) => {
    // Handle Errors here.
    const errorCode = error.code;
    const errorMessage = error.message;
    // The email of the user's account used.
    const email = error.customData.email;
    // The credential that was used.
    const credential = OAuthProvider.credentialFromError(error);

    // ...
  });
    auth_apple_signin_redirect_result.js

    Versão Web 8

    // Result from Redirect auth flow.
firebase
  .auth()
  .getRedirectResult()
  .then((result) => {
    if (result.credential) {
      /** @type {firebase.auth.OAuthCredential} */
      var credential = result.credential;

      // You can get the Apple OAuth Access and ID Tokens.
      var accessToken = credential.accessToken;
      var idToken = credential.idToken;

      // IdP data available in result.additionalUserInfo.profile.
      // ...
    }
    // The signed-in user info.
    var user = result.user;
  })
  .catch((error) => {
    // Handle Errors here.
    var errorCode = error.code;
    var errorMessage = error.message;
    // The email of the user's account used.
    var email = error.email;
    // The firebase.auth.AuthCredential type that was used.
    var credential = error.credential;

    // ...
  });
    apple.js

    É também aqui que pode detetar e processar erros. Para ver uma lista de códigos de erro, consulte a referência da API.

Ao contrário de muitos outros fornecedores de identidade, a Apple não fornece um URL de foto.

Se um utilizador optar por não partilhar o respetivo email real com a sua app, a Apple disponibiliza um endereço de email exclusivo para esse utilizador partilhar. Este email tem o formato xyz@privaterelay.appleid.com. Se configurou o serviço de retransmissão de email privado, a Apple encaminha os emails enviados para o endereço anónimo para o endereço de email real do utilizador.

A Apple só partilha informações do utilizador, como nomes a apresentar, com as apps na primeira vez que um utilizador inicia sessão. Na maioria dos casos, a Identity Platform armazena estes dados, o que lhe permite obtê-los através de firebase.auth().currentUser.displayName durante sessões futuras. No entanto, se permitiu que os utilizadores iniciassem sessão na sua app através da Apple antes da integração com a Identity Platform, as informações dos utilizadores não estão disponíveis.

O que se segue?