建立自訂憑證

本文件說明如何使用 Identity Platform 建立自訂 JSON Web Token (JWT)。

您可以透過自訂權杖完全掌控驗證程序。您可以在伺服器上產生這些權杖，將其傳回用戶端裝置，然後呼叫 signInWithCustomToken() 來登入使用者。

您可以使用 Identity Platform Admin SDK 建立自訂權杖，或使用第三方 JWT 程式庫。

事前準備

  • 安裝 Admin SDK。如果您使用服務帳戶自動探索功能或明確指定的服務帳戶 ID，請確認您使用的服務帳戶至少具備「服務帳戶憑證建立者」(roles/iam.serviceAccountTokenCreator) 角色。

  • 建立並部署可接受使用者登入憑證的伺服器端點。

使用 Admin SDK 建立自訂憑證

Admin SDK 內建建立自訂權杖的方法。您至少需要提供 uid。這可以是任何可獨特識別使用者或裝置的字串。這些權杖會在一小時後失效。

以下範例說明如何建立自訂權杖：

Node.js

const uid = 'some-uid';

getAuth()
  .createCustomToken(uid)
  .then((customToken) => {
    // Send token back to client
  })
  .catch((error) => {
    console.log('Error creating custom token:', error);
  });
create_custom_tokens.js

Java

String uid = "some-uid";

String customToken = FirebaseAuth.getInstance().createCustomToken(uid);
// Send token back to client
FirebaseAuthSnippets.java

Python

uid = 'some-uid'

custom_token = auth.create_custom_token(uid)
index.py

Go

client, err := app.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

token, err := client.CustomToken(ctx, "some-uid")
if err != nil {
	log.Fatalf("error minting custom token: %v\n", err)
}

log.Printf("Got custom token: %v\n", token)
auth.go

C#

var uid = "some-uid";

string customToken = await FirebaseAuth.DefaultInstance.CreateCustomTokenAsync(uid);
// Send token back to client
FirebaseAuthSnippets.cs

建立自訂權杖後，應用程式就能使用該權杖讓使用者登入。

您也可以選擇在自訂權杖中加入其他宣告。這些資訊會以頂層要求傳播至使用者的 ID 權杖。

以下範例說明如何新增 premiumAccount 權利要求：

Node.js

const userId = 'some-uid';
const additionalClaims = {
  premiumAccount: true,
};

getAuth()
  .createCustomToken(userId, additionalClaims)
  .then((customToken) => {
    // Send token back to client
  })
  .catch((error) => {
    console.log('Error creating custom token:', error);
  });
create_custom_tokens.js

Java

String uid = "some-uid";
Map<String, Object> additionalClaims = new HashMap<String, Object>();
additionalClaims.put("premiumAccount", true);

String customToken = FirebaseAuth.getInstance()
    .createCustomToken(uid, additionalClaims);
// Send token back to client
FirebaseAuthSnippets.java

Python

uid = 'some-uid'
additional_claims = {
    'premiumAccount': True
}

custom_token = auth.create_custom_token(uid, additional_claims)
index.py

Go

client, err := app.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

claims := map[string]interface{}{
	"premiumAccount": true,
}

token, err := client.CustomTokenWithClaims(ctx, "some-uid", claims)
if err != nil {
	log.Fatalf("error minting custom token: %v\n", err)
}

log.Printf("Got custom token: %v\n", token)
auth.go

C#

var uid = "some-uid";
var additionalClaims = new Dictionary<string, object>()
{
    { "premiumAccount", true },
};

string customToken = await FirebaseAuth.DefaultInstance
    .CreateCustomTokenAsync(uid, additionalClaims);
// Send token back to client
FirebaseAuthSnippets.cs

Identity Platform 符合 OpenID Connect JWT 規格。這表示下列聲明為保留，無法指定：

  • acr
  • amr
  • at_hash
  • aud
  • auth_time
  • azp
  • cnf
  • c_hash
  • exp
  • firebase
  • iat
  • iss
  • jti
  • nbf
  • nonce
  • sub

使用第三方 JWT 程式庫建立自訂權杖

如果後端使用 Admin SDK 不支援的語言編寫，您仍可手動建立自訂符記。首先，找出適用於您語言的第三方 JWT 程式庫。然後使用該程式庫鑄造 JWT，其中包含下列宣告：

alg 演算法 "RS256"
iss 核發單位 專案的服務帳戶電子郵件地址。
sub 主旨 專案的服務帳戶電子郵件地址。
aud 目標對象 "https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit"
iat 核發時間 自 UNIX Epoch 起算的目前時間，以秒為單位。
exp 到期時間 權杖到期時間，以自 Unix 紀元時間起算的秒數為單位。比 iat 晚最多 3600 秒。
請注意，這項設定只會控制自訂權杖本身的到期時間。使用者透過 signInWithCustomToken() 登入後，會一直保持登入狀態，直到他們登出或工作階段失效為止。
uid 已登入使用者的專屬 ID。長度必須介於 1 至 36 個半形字元之間。
claims (選填) 要納入的其他自訂聲明。

以下範例說明如何使用 Admin SDK 不支援的語言建立自訂權杖：

PHP

使用 php-jwt：

// Requires: composer require firebase/php-jwt
use Firebase\JWT\JWT;

// Get your service account's email address and private key from the JSON key file
$service_account_email = "abc-123@a-b-c-123.iam.gserviceaccount.com";
$private_key = "-----BEGIN PRIVATE KEY-----...";

function create_custom_token($uid, $is_premium_account) {
  global $service_account_email, $private_key;

  $now_seconds = time();
  $payload = array(
  "iss" => $service_account_email,
  "sub" => $service_account_email,
  "aud" => "https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit",
  "iat" => $now_seconds,
  "exp" => $now_seconds+(60*60),  // Maximum expiration time is one hour
  "uid" => $uid,
  "claims" => array(
      "premium_account" => $is_premium_account
  )
  );
  return JWT::encode($payload, $private_key, "RS256");
}

小茹

使用 ruby-jwt：

require "jwt"

# Get your service account's email address and private key from the JSON key file
$service_account_email = "service-account@my-project-abc123.iam.gserviceaccount.com"
$private_key = OpenSSL::PKey::RSA.new "-----BEGIN PRIVATE KEY-----\n..."

def create_custom_token(uid, is_premium_account)
  now_seconds = Time.now.to_i
  payload = {:iss => $service_account_email,
              :sub => $service_account_email,
              :aud => "https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit",
              :iat => now_seconds,
              :exp => now_seconds+(60*60), # Maximum expiration time is one hour
              :uid => uid,
              :claims => {:premium_account => is_premium_account}}
  JWT.encode payload, $private_key, "RS256"
end

建立自訂權杖後，應用程式就能使用該權杖讓使用者登入。

後續步驟