透過 JavaScript 使用 Apple 驗證

您可以使用 Firebase SDK 執行端對端 OAuth 2.0 登入流程，讓使用者使用 Apple ID 驗證 Firebase。

事前準備

如要使用 Apple 登入使用者，請先在 Apple 開發人員網站上設定「使用 Apple 登入」，然後將 Apple 設為 Firebase 專案的登入提供者。

加入 Apple 開發人員計畫

只有 Apple 開發人員計畫成員才能設定「使用 Apple 帳戶登入」功能。

設定「使用 Apple 帳戶登入」功能

在 Apple Developer 網站上執行下列操作：

  1. 按照「 設定網頁版 Apple 登入功能」第一節所述，將網站與應用程式建立關聯。在系統提示時，將下列網址註冊為返回網址：

    https://YOUR_FIREBASE_PROJECT_ID.firebaseapp.com/__/auth/handler

    您可以在 Firebase 控制台設定頁面取得 Firebase 專案 ID。

    完成後，請記下新的服務 ID，因為您會在下一個部分使用這項資訊。

  2. 建立使用 Apple 帳戶登入的私密金鑰。您將在下一個章節中需要新的私密金鑰和金鑰 ID。

  3. 如果您使用 Firebase Authentication 的任何功能傳送電子郵件給使用者，包括電子郵件連結登入、電子郵件地址驗證、帳戶變更撤銷等，請 設定 Apple 私人電子郵件轉發服務並註冊 noreply@YOUR_FIREBASE_PROJECT_ID.firebaseapp.com (或您自訂的電子郵件範本網域)，以便 Apple 將 Firebase Authentication 傳送的電子郵件轉發至匿名 Apple 電子郵件地址。

啟用 Apple 做為登入服務供應商

  1. 將 Firebase 新增至專案。
  2. 在 Firebase 控制台中，開啟「Auth」部分。在「Sign in method」分頁中，啟用 Apple 供應器。指定您在上一節中建立的服務 ID。此外，請在「OAuth 程式碼流程設定」專區中指定 Apple 團隊 ID，以及您在前一個專區中建立的私密金鑰和金鑰 ID。

遵守 Apple 去識別化資料規定

使用者可在登入時選擇使用「Sign In with Apple」功能，將自己的資料 (包括電子郵件地址) 匿名化。選擇這個選項的使用者電子郵件地址會使用 privaterelay.appleid.com 網域。在應用程式中使用「使用 Apple 帳戶登入」時，您必須遵守 Apple 針對這些匿名 Apple ID 所提供的任何適用開發人員政策或條款。

這包括在您將任何可直接識別的個人資訊與匿名 Apple ID 建立關聯之前，先取得任何必要的使用者同意。使用 Firebase 驗證時，這可能包括下列動作：

  • 將電子郵件地址連結至匿名 Apple ID，或將匿名 Apple ID 連結至電子郵件地址。
  • 將電話號碼連結至匿名 Apple ID，或將匿名 Apple ID 連結至電話號碼
  • 將非匿名社群媒體憑證 (Facebook、Google 等) 連結至匿名 Apple ID，或反之。

請注意，上方清單僅列出部分示例。請參閱開發人員帳戶「會員」部分的《Apple Developer Program License Agreement》，確保您的應用程式符合 Apple 的規定。

使用 Firebase SDK 處理登入流程

如果您要建構網頁應用程式，透過 Firebase 驗證使用者 Apple 帳戶的最佳方法，就是使用 Firebase JavaScript SDK 處理整個登入流程。

如要使用 Firebase JavaScript SDK 處理登入流程，請按照下列步驟操作：

  1. 使用對應的提供者 ID apple.com，建立 OAuthProvider 的例項。

    WebWeb
    import { OAuthProvider } from "firebase/auth";

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

  2. 選用：除了您想向驗證提供者要求的預設範圍外，指定其他 OAuth 2.0 範圍。

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

    根據預設，啟用「每個電子郵件地址一個帳戶」時，Firebase 會要求電子郵件和名稱範圍。如果您將這項設定變更為「每個電子郵件地址可建立多個帳戶」，Firebase 不會向 Apple 要求任何權限，除非您指定這些權限。

  3. 選用：如果您想以英文以外的語言顯示 Apple 登入畫面，請設定 locale 參數。如要瞭解支援的語言代碼，請參閱「使用 Apple 帳戶登入」說明文件。

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

  4. 使用 OAuth 提供者物件與 Firebase 進行驗證。您可以開啟彈出式視窗，或重新導向至登入頁面，提示使用者使用 Apple 帳戶登入。在行動裝置上，建議使用重新導向方法。

    • 如要透過彈出式視窗登入，請呼叫 signInWithPopup()：

      WebWeb
      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
       
      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

    • 如要透過重新導向登入頁面來登入，請呼叫 signInWithRedirect()：

    使用 signInWithRedirect、linkWithRedirect 或 reauthenticateWithRedirect 時，請遵循最佳做法。

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

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

    使用者完成登入並返回頁面後，您可以呼叫 getRedirectResult() 取得登入結果：

    WebWeb
    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
     
    // 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

    您也可以在這裡捕捉及處理錯誤。如需錯誤代碼清單，請參閱 API 參考資料。

    與 Firebase Auth 支援的其他提供者不同，Apple 不會提供相片網址。

    此外，如果使用者選擇不與應用程式分享電子郵件，Apple 會為該使用者提供專屬電子郵件地址 (格式為 xyz@privaterelay.appleid.com)，並與您的應用程式分享。如果您已設定私人電子郵件轉送服務，Apple 會將傳送至匿名地址的電子郵件轉寄至使用者的實際電子郵件地址。

    Apple 只會在使用者首次登入時，與應用程式分享顯示名稱等使用者資訊。通常，Firebase 會儲存使用者首次透過 Apple 登入時的顯示名稱，您可以使用 firebase.auth().currentUser.displayName 取得這項資訊。不過，如果您先前曾使用 Apple 服務讓使用者登入應用程式，但未使用 Firebase，Apple 就不會將使用者的顯示名稱提供給 Firebase。

重新驗證和帳戶連結

您可以使用相同的模式搭配 reauthenticateWithPopup() 和 reauthenticateWithRedirect()，擷取敏感作業的最新憑證，這些作業需要最近登入：

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

// Result from Redirect auth flow.
const auth = getAuth();
const provider = new OAuthProvider('apple.com');

reauthenticateWithPopup(auth.currentUser, provider)
  .then((result) => {
    // User is re-authenticated with fresh tokens minted and can perform
    // sensitive operations like account deletion, or updating their email
    // address or password.

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

    // You can also get the Apple OAuth Access and ID Tokens.
    const credential = OAuthProvider.credentialFromResult(result);
    const accessToken = credential.accessToken;
    const idToken = credential.idToken;

    // ...
  })
  .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_reauthenticate_popup.js
 
const provider = new firebase.auth.OAuthProvider('apple.com');

firebase
  .auth()
  .currentUser
  .reauthenticateWithPopup(provider)
  .then((result) => {
    // User is re-authenticated with fresh tokens minted and can perform
    // sensitive operations like account deletion, or updating their email
    // address or password.
    /** @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 in result.additionalUserInfo.profile.
      // ...
  })
  .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

您也可以使用 linkWithPopup() 和 linkWithRedirect()，將不同的身分識別資訊提供者連結至現有帳戶。

請注意，Apple 規定您必須取得使用者明確同意，才能將使用者的 Apple 帳戶連結至其他資料。

舉例來說，如要將 Facebook 帳戶連結至目前的 Firebase 帳戶，請使用從使用者登入 Facebook 取得的存取權權杖：

WebWeb
import { getAuth, linkWithPopup, FacebookAuthProvider } from "firebase/auth";

const auth = getAuth();
const provider = new FacebookAuthProvider();
provider.addScope('user_birthday');

// Assuming the current user is an Apple user linking a Facebook provider.
linkWithPopup(auth.currentUser, provider)
    .then((result) => {
      // Facebook credential is linked to the current Apple user.
      // ...

      // The user can now sign in to the same account
      // with either Apple or Facebook.
    })
    .catch((error) => {
      // Handle error.
    });
auth_apple_link_facebook.js
 
const provider = new firebase.auth.FacebookAuthProvider();
provider.addScope('user_birthday');

// Assuming the current user is an Apple user linking a Facebook provider.
firebase.auth().currentUser.linkWithPopup(provider)
    .then((result) => {
      // Facebook credential is linked to the current Apple user.
      // Facebook additional data available in result.additionalUserInfo.profile,

      // Additional Facebook OAuth access token can also be retrieved.
      // result.credential.accessToken

      // The user can now sign in to the same account
      // with either Apple or Facebook.
    })
    .catch((error) => {
      // Handle error.
    });
apple.js

在 Chrome 擴充功能中使用 Firebase 進行驗證

如果您要建構 Chrome 擴充功能應用程式，請參閱 離線文件指南。

建立專案時，Firebase 會為您的專案提供專屬子網域：https://my-app-12345.firebaseapp.com。

這也會用來做為 OAuth 登入的重新導向機制。您必須為所有支援的 OAuth 供應商允許該網域。不過，這也代表使用者在登入 Apple 時，可能會看到該網域，然後再重新導向至應用程式：Continue to: https://my-app-12345.firebaseapp.com。

如要避免顯示子網域，您可以使用 Firebase Hosting 設定自訂網域：

  1. 請按照「為 Hosting 設定網域」中的步驟 1 至 3 操作。驗證網域擁有權後，Hosting 會為自訂網域佈建 SSL 憑證。
  2. 將自訂網域新增至 Firebase 控制台的授權網域清單：auth.custom.domain.com。
  3. 在 Apple 開發人員控制台或 OAuth 設定頁面中，將重新導向網頁的網址加入白名單，這樣您就能透過自訂網域存取該網頁：https://auth.custom.domain.com/__/auth/handler。
  4. 初始化 JavaScript 程式庫時，請使用 authDomain 欄位指定自訂網域：
    var config = {
  apiKey: '...',
  // Changed from 'PROJECT_ID.firebaseapp.com'.
  authDomain: 'auth.custom.domain.com',
  databaseURL: 'https://PROJECT_ID.firebaseio.com',
  projectId: 'PROJECT_ID',
  storageBucket: 'PROJECT_ID.firebasestorage.app',
  messagingSenderId: 'SENDER_ID'
};
firebase.initializeApp(config);

請注意，您仍必須向 Apple 驗證自訂網域，方法與預設的 firebaseapp.com 網域類似：

http://auth.custom.example.com/.well-known/apple-developer-domain-association.txt

權杖撤銷

Apple 規定，支援帳戶建立功能的應用程式必須讓使用者在應用程式內部啟動帳戶刪除程序，詳情請參閱App Store 審查規範

如要符合這項規定，請實作下列步驟：

  1. 請確認您已填寫「使用 Apple 登入」供應器設定的 服務 ID 和 OAuth 代碼流程設定部分，如「設定使用 Apple 登入」一節所述。

  2. 使用者透過「使用 Apple 登入」建立帳戶時，Firebase 不會儲存使用者權杖，因此您必須先要求使用者再次登入，再撤銷其權杖並刪除帳戶。

    接著，從 OAuthCredential 取得 Apple OAuth 存取權杖，然後使用該權杖呼叫 revokeAccessToken(auth, token)，以撤銷 Apple OAuth 存取權杖。

    const provider = new OAuthProvider('apple.com');
provider.addScope('email');
provider.addScope('name');

const auth = getAuth();
signInWithPopup(auth, provider).then(result => {
  // Get the Apple OAuth access token.
  const credential = OAuthProvider.credentialFromResult(result);
  const accessToken = credential.accessToken;

  // Revoke the Apple OAuth access token.
  revokeAccessToken(auth, accessToken)
    .then(() => {
      // Token revoked.

      // Delete the user account.
      // ...
    })
    .catch(error => {
      // An error happened.
      // ...
    });
});

  3. 最後，請刪除使用者帳戶 (以及所有相關聯的資料)。

進階：在 Node.js 中使用 Firebase 進行驗證

如要在 Node.js 應用程式中使用 Firebase 進行驗證，請按照下列步驟操作：

  1. 請使用者登入 Apple 帳戶，並取得使用者的 Apple ID 權杖。您可以透過多種方式完成這項操作。舉例來說，如果您的 Node.js 應用程式有瀏覽器前端：

    1. 在後端產生隨機字串 (「Nonce」)，並計算其 SHA256 雜湊。Nonce 是一次性值，可用於驗證後端和 Apple 驗證伺服器之間的單一往返通訊。

      WebWeb
      const crypto = require("crypto");
const string_decoder = require("string_decoder");

// Generate a new random string for each sign-in
const generateNonce = (length) => {
  const decoder = new string_decoder.StringDecoder("ascii");
  const buf = Buffer.alloc(length);
  let nonce = "";
  while (nonce.length < length) {
    crypto.randomFillSync(buf);
    nonce = decoder.write(buf);
  }
  return nonce.slice(0, length);
};

const unhashedNonce = generateNonce(10);

// SHA256-hashed nonce in hex
const hashedNonceHex = crypto.createHash('sha256')
  .update(unhashedNonce).digest().toString('hex');
      auth_apple_nonce_node.js
       
      const crypto = require("crypto");
const string_decoder = require("string_decoder");

// Generate a new random string for each sign-in
const generateNonce = function(length) {
  const decoder = new string_decoder.StringDecoder("ascii");
  const buf = Buffer.alloc(length);
  var nonce = "";
  while (nonce.length < length) {
    crypto.randomFillSync(buf);
    nonce = decoder.write(buf);
  }
  return nonce.slice(0, length);
};

const unhashedNonce = generateNonce(10);

// SHA256-hashed nonce in hex
const hashedNonceHex = crypto.createHash('sha256')
  .update(unhashedNonce).digest().toString('hex');
      apple.js

    2. 在登入頁面中，在「Sign In with Apple」設定中指定經過雜湊處理的 Nonce：

      <script src="https://appleid.cdn-apple.com/appleauth/static/jsapi/appleid/1/en_US/appleid.auth.js"></script>
<div id="appleid-signin" data-color="black" data-border="true" data-type="sign in"></div>
<script>
    AppleID.auth.init({
        clientId: YOUR_APPLE_CLIENT_ID,
        scope: 'name email',
        redirectURI: URL_TO_YOUR_REDIRECT_HANDLER,  // See the next step.
        state: '[STATE]',  // Optional value that Apple will send back to you
                           // so you can return users to the same context after
                           // they sign in.
        nonce: HASHED_NONCE  // The hashed nonce you generated in the previous step.
    });
</script>

    3. 從伺服器端的 POST 驗證回應中取得 Apple ID 權杖：

      app.post('/redirect', (req, res) => {
  const savedState = req.cookies.__session;
  const code = req.body.code;
  const state = req.body.state;
  const appleIdToken = req.body.id_token;
  if (savedState !== state || !code) {
    res.status(403).send('403: Permission denied');
  } else {
    // Sign in with Firebase using appleIdToken. (See next step).
  }
});

    另請參閱「設定網頁以支援 Apple 登入」。

  2. 取得使用者的 Apple ID 權杖後，請使用該權杖建立憑證物件，然後使用憑證登入使用者：

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

const auth = getAuth();

// Build Firebase credential with the Apple ID token.
const provider = new OAuthProvider('apple.com');
const authCredential = provider.credential({
  idToken: appleIdToken,
  rawNonce: unhashedNonce,
});

// Sign in with credential form the Apple user.
signInWithCredential(auth, authCredential)
  .then((result) => {
    // User signed in.
  })
  .catch((error) => {
    // An error occurred. If error.code == 'auth/missing-or-invalid-nonce',
    // make sure you're sending the SHA256-hashed nonce as a hex string
    // with your request to Apple.
    console.log(error);
  });
    auth_apple_signin_nonce.js
     
    // Build Firebase credential with the Apple ID token.
const provider = new firebase.auth.OAuthProvider('apple.com');
const authCredential = provider.credential({
  idToken: appleIdToken,
  rawNonce: unhashedNonce,
});

// Sign in with credential form the Apple user.
firebase.auth().signInWithCredential(authCredential)
  .then((result) => {
    // User signed in.
  })
  .catch((error) => {
    // An error occurred. If error.code == 'auth/missing-or-invalid-nonce',
    // make sure you're sending the SHA256-hashed nonce as a hex string
    // with your request to Apple.
    console.log(error);
  });
    apple.js

後續步驟

使用者首次登入後，系統會建立新使用者帳戶，並連結至使用者登入時所用的憑證 (即使用者名稱和密碼、電話號碼或驗證服務提供者資訊)。這個新帳戶會儲存在 Firebase 專案中，無論使用者如何登入，都可以用於在專案中的每個應用程式中識別使用者。

  • 在應用程式中，建議您在 Auth 物件上設定觀察器，以便瞭解使用者的驗證狀態。接著，您可以從 User 物件取得使用者的基本個人資料資訊。請參閱「管理使用者」。

  • 在 Firebase Realtime Database 和 Cloud Storage 安全性規則中，您可以從 auth 變數取得已登入使用者的專屬使用者 ID，並利用該 ID 控管使用者可存取的資料。

您可以將驗證服務供應商憑證連結至現有使用者帳戶，讓使用者使用多個驗證服務供應商登入應用程式。

如要將使用者登出，請呼叫 signOut：

WebWeb
import { getAuth, signOut } from "firebase/auth";

const auth = getAuth();
signOut(auth).then(() => {
  // Sign-out successful.
}).catch((error) => {
  // An error happened.
});
auth_sign_out.js
 
firebase.auth().signOut().then(() => {
  // Sign-out successful.
}).catch((error) => {
  // An error happened.
});
index.js