建立自訂憑證

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

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

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

事前準備

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

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

使用 Admin SDK 建立自訂權杖

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

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

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);
  });

Java

String uid = "some-uid";

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

Python

uid = 'some-uid'

custom_token = auth.create_custom_token(uid)

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)

C#

var uid = "some-uid";

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

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

您也可以選擇在自訂權杖中加入其他聲明。這些屬性會以頂層聲明形式傳播至使用者的 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);
  });

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

Python

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

custom_token = auth.create_custom_token(uid, additional_claims)

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)

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

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 Epoch 紀元時間開始算起。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

使用 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

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

後續步驟