Tạo mã thông báo tuỳ chỉnh

Firebase cho phép bạn toàn quyền kiểm soát quá trình xác thực bằng cách xác thực người dùng hoặc thiết bị bằng Mã thông báo web JSON (JWT) bảo mật. Bạn tạo các mã thông báo này trên máy chủ, chuyển các mã thông báo đó trở lại thiết bị khách, sau đó sử dụng các mã thông báo đó để xác thực thông qua phương thức signInWithCustomToken().

Để làm được việc này, bạn phải tạo một điểm cuối máy chủ chấp nhận thông tin đăng nhập, chẳng hạn như tên người dùng và mật khẩu. Nếu thông tin đăng nhập hợp lệ, thì điểm cuối này sẽ trả về một JWT tuỳ chỉnh. Sau đó, thiết bị khách có thể sử dụng JWT tuỳ chỉnh được trả về từ máy chủ của bạn để xác thực bằng Firebase (iOS+, Android, web). Sau khi xác thực, danh tính này sẽ được sử dụng khi truy cập vào các dịch vụ Firebase khác, chẳng hạn như Firebase Realtime Database và Cloud Storage. Hơn nữa, nội dung của JWT sẽ có trong đối tượng auth trong Realtime Database Security Rules và đối tượng request.auth trong Cloud Storage Security Rules.

Bạn có thể tạo mã thông báo tuỳ chỉnh bằng SDK Quản trị Firebase hoặc sử dụng thư viện JWT của bên thứ ba nếu máy chủ của bạn được viết bằng ngôn ngữ mà Firebase không hỗ trợ.

Trước khi bắt đầu

Mã thông báo tuỳ chỉnh là JWT đã ký, trong đó khoá riêng tư dùng để ký thuộc về một tài khoản dịch vụ của Google. Có một số cách để chỉ định tài khoản dịch vụ Google mà SDK Quản trị Firebase sẽ sử dụng để ký mã thông báo tuỳ chỉnh:

• Sử dụng tệp JSON của tài khoản dịch vụ – Bạn có thể sử dụng phương thức này trong bất kỳ môi trường nào, nhưng bạn phải đóng gói tệp JSON của tài khoản dịch vụ cùng với mã của mình. Bạn phải đặc biệt cẩn thận để đảm bảo rằng tệp JSON của tài khoản dịch vụ không bị bên ngoài tiếp cận.
• Cho phép SDK quản trị viên khám phá tài khoản dịch vụ – Bạn có thể sử dụng phương thức này trong các môi trường do Google quản lý, chẳng hạn như Hàm trên Google Cloud và App Engine. Bạn có thể phải định cấu hình một số quyền bổ sung thông qua bảng điều khiển Google Cloud.
• Sử dụng mã tài khoản dịch vụ – Khi được sử dụng trong môi trường do Google quản lý, phương thức này sẽ ký mã thông báo bằng khoá của tài khoản dịch vụ được chỉ định. Tuy nhiên, ứng dụng này sử dụng dịch vụ web từ xa và bạn có thể phải định cấu hình thêm quyền cho tài khoản dịch vụ này thông qua bảng điều khiển Google Cloud.

Sử dụng tệp JSON của tài khoản dịch vụ

Tệp JSON của tài khoản dịch vụ chứa tất cả thông tin tương ứng với tài khoản dịch vụ (bao gồm cả khoá riêng tư RSA). Bạn có thể tải các tệp này xuống từ bảng điều khiển Firebase. Làm theo hướng dẫn thiết lập SDK quản trị để biết thêm thông tin về cách khởi chạy SDK quản trị bằng tệp JSON của tài khoản dịch vụ.

Phương thức khởi chạy này phù hợp với nhiều phương thức triển khai SDK quản trị. Ngoài ra, tính năng này cho phép SDK quản trị tạo và ký mã thông báo tuỳ chỉnh trên máy mà không cần thực hiện bất kỳ lệnh gọi API từ xa nào. Hạn chế chính của phương pháp này là bạn phải đóng gói tệp JSON của tài khoản dịch vụ cùng với mã của mình. Ngoài ra, xin lưu ý rằng khoá riêng tư trong tệp JSON của tài khoản dịch vụ là thông tin nhạy cảm và bạn phải đặc biệt cẩn thận để giữ bí mật khoá này. Cụ thể, hãy tránh thêm tệp JSON của tài khoản dịch vụ vào hệ thống kiểm soát phiên bản công khai.

Cho phép SDK quản trị viên khám phá tài khoản dịch vụ

Nếu mã của bạn được triển khai trong một môi trường do Google quản lý, thì SDK dành cho quản trị viên có thể cố gắng tự động khám phá phương thức ký mã thông báo tuỳ chỉnh:

• Nếu mã của bạn được triển khai trong môi trường chuẩn App Engine cho Java, Python hoặc Go, thì SDK dành cho quản trị viên có thể sử dụng Dịch vụ danh tính ứng dụng có trong môi trường đó để ký mã thông báo tuỳ chỉnh. Dịch vụ Danh tính ứng dụng ký dữ liệu bằng một tài khoản dịch vụ do Công cụ ứng dụng của Google cung cấp cho ứng dụng của bạn.

• Nếu mã của bạn được triển khai trong một số môi trường được quản lý khác (ví dụ: Hàm trên Google Cloud, Google Compute Engine), thì SDK Quản trị Firebase có thể tự động khám phá chuỗi mã nhận dạng tài khoản dịch vụ từ máy chủ siêu dữ liệu cục bộ. Sau đó, mã tài khoản dịch vụ được phát hiện sẽ được sử dụng cùng với dịch vụ IAM để ký mã thông báo từ xa.

Để sử dụng các phương thức ký này, hãy khởi chạy SDK bằng thông tin xác thực mặc định của ứng dụng Google và không chỉ định chuỗi mã nhận dạng tài khoản dịch vụ:

initializeApp();

FirebaseApp.initializeApp();

default_app = firebase_admin.initialize_app()

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

FirebaseApp.Create();

Để kiểm thử cùng một mã trên máy, hãy tải tệp JSON của tài khoản dịch vụ xuống và đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS để trỏ đến tệp đó.

Nếu SDK quản trị Firebase phải khám phá chuỗi mã nhận dạng tài khoản dịch vụ, thì SDK này sẽ làm như vậy khi mã của bạn tạo mã thông báo tuỳ chỉnh lần đầu tiên. Kết quả được lưu vào bộ nhớ đệm và sử dụng lại cho các thao tác ký mã thông báo tiếp theo. Mã tài khoản dịch vụ được tự động phát hiện thường là một trong các tài khoản dịch vụ mặc định do Google Cloud cung cấp:

• Tài khoản dịch vụ Compute Engine mặc định
• Tài khoản dịch vụ mặc định của Cloud Functions

Giống như mã tài khoản dịch vụ được chỉ định rõ ràng, mã tài khoản dịch vụ được tự động phát hiện phải có quyền iam.serviceAccounts.signBlob để quá trình tạo mã thông báo tuỳ chỉnh hoạt động. Bạn có thể phải sử dụng phần IAM và quản trị của bảng điều khiển Google Cloud để cấp cho các tài khoản dịch vụ mặc định các quyền cần thiết. Hãy xem phần khắc phục sự cố bên dưới để biết thêm thông tin.

Sử dụng mã tài khoản dịch vụ

Để duy trì tính nhất quán giữa các phần của ứng dụng, bạn có thể chỉ định mã tài khoản dịch vụ có khoá sẽ được dùng để ký mã thông báo khi chạy trong môi trường do Google quản lý. Điều này có thể giúp các chính sách IAM đơn giản và an toàn hơn, đồng thời tránh việc phải đưa tệp JSON của tài khoản dịch vụ vào mã của bạn.

Bạn có thể tìm thấy mã tài khoản dịch vụ trong bảng điều khiển Google Cloud hoặc trong trường client_email của tệp JSON tài khoản dịch vụ đã tải xuống. Mã tài khoản dịch vụ là địa chỉ email có định dạng sau: <client-id>@<project-id>.iam.gserviceaccount.com. Các mã này giúp xác định riêng tài khoản dịch vụ trong dự án Firebase và Google Cloud.

Để tạo mã thông báo tuỳ chỉnh bằng mã tài khoản dịch vụ riêng biệt, hãy khởi chạy SDK như minh hoạ bên dưới:

initializeApp({
  serviceAccountId: 'my-client-id@my-project-id.iam.gserviceaccount.com',
});

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setServiceAccountId("my-client-id@my-project-id.iam.gserviceaccount.com")
    .build();
FirebaseApp.initializeApp(options);

options = {
    'serviceAccountId': 'my-client-id@my-project-id.iam.gserviceaccount.com',
}
firebase_admin.initialize_app(options=options)

conf := &firebase.Config{
	ServiceAccountID: "my-client-id@my-project-id.iam.gserviceaccount.com",
}
app, err := firebase.NewApp(context.Background(), conf)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}
init.go

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
    ServiceAccountId = "my-client-id@my-project-id.iam.gserviceaccount.com",
});

Mã tài khoản dịch vụ không phải là thông tin nhạy cảm, do đó, việc tiết lộ mã này không quan trọng. Tuy nhiên, để ký mã thông báo tuỳ chỉnh bằng tài khoản dịch vụ được chỉ định, SDK Quản trị Firebase phải gọi một dịch vụ từ xa. Ngoài ra, bạn cũng phải đảm bảo rằng tài khoản dịch vụ mà SDK Quản trị đang sử dụng để thực hiện lệnh gọi này (thường là {project-name}@appspot.gserviceaccount.com) có quyền iam.serviceAccounts.signBlob. Hãy xem phần khắc phục sự cố bên dưới để biết thêm thông tin.

Tạo mã thông báo tuỳ chỉnh bằng SDK Quản trị Firebase

SDK Quản trị Firebase có một phương thức tích hợp để tạo mã thông báo tuỳ chỉnh. Ít nhất, bạn cần cung cấp một uid. Đây có thể là bất kỳ chuỗi nào nhưng phải xác định duy nhất người dùng hoặc thiết bị mà bạn đang xác thực. Các mã thông báo này sẽ hết hạn sau một giờ.

const uid = 'some-uid';

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

String uid = "some-uid";

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

uid = 'some-uid'

custom_token = auth.create_custom_token(uid)
index.py

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

var uid = "some-uid";

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

Bạn cũng có thể tuỳ ý chỉ định các thông báo xác nhận bổ sung để đưa vào mã thông báo tuỳ chỉnh. Ví dụ: bên dưới, trường premiumAccount đã được thêm vào mã thông báo tuỳ chỉnh. Mã thông báo này sẽ có trong các đối tượng auth / request.auth trong Quy tắc bảo mật:

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

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

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

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

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

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

Tên mã thông báo tuỳ chỉnh được đặt trước

Đăng nhập bằng mã thông báo tuỳ chỉnh trên ứng dụng

Sau khi tạo mã thông báo tuỳ chỉnh, bạn nên gửi mã đó đến ứng dụng khách. Ứng dụng khách xác thực bằng mã thông báo tuỳ chỉnh bằng cách gọi signInWithCustomToken():

[[FIRAuth auth] signInWithCustomToken:customToken
                           completion:^(FIRAuthDataResult * _Nullable authResult,
                                        NSError * _Nullable error) {
  // ...
}];

Auth.auth().signIn(withCustomToken: customToken ?? "") { user, error in
  // ...
}

mAuth.signInWithCustomToken(mCustomToken)
        .addOnCompleteListener(this, new OnCompleteListener<AuthResult>() {
            @Override
            public void onComplete(@NonNull Task<AuthResult> task) {
                if (task.isSuccessful()) {
                    // Sign in success, update UI with the signed-in user's information
                    Log.d(TAG, "signInWithCustomToken:success");
                    FirebaseUser user = mAuth.getCurrentUser();
                    updateUI(user);
                } else {
                    // If sign in fails, display a message to the user.
                    Log.w(TAG, "signInWithCustomToken:failure", task.getException());
                    Toast.makeText(CustomAuthActivity.this, "Authentication failed.",
                            Toast.LENGTH_SHORT).show();
                    updateUI(null);
                }
            }
        });

auth.SignInWithCustomTokenAsync(custom_token).ContinueWith(task => {
  if (task.IsCanceled) {
    Debug.LogError("SignInWithCustomTokenAsync was canceled.");
    return;
  }
  if (task.IsFaulted) {
    Debug.LogError("SignInWithCustomTokenAsync encountered an error: " + task.Exception);
    return;
  }

  Firebase.Auth.AuthResult result = task.Result;
  Debug.LogFormat("User signed in successfully: {0} ({1})",
      result.User.DisplayName, result.User.UserId);
});

firebase::Future<firebase::auth::AuthResult> result =
    auth->SignInWithCustomToken(custom_token);

firebase.auth().signInWithCustomToken(token)
  .then((userCredential) => {
    // Signed in
    var user = userCredential.user;
    // ...
  })
  .catch((error) => {
    var errorCode = error.code;
    var errorMessage = error.message;
    // ...
  });
custom.js

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

const auth = getAuth();
signInWithCustomToken(auth, token)
  .then((userCredential) => {
    // Signed in
    const user = userCredential.user;
    // ...
  })
  .catch((error) => {
    const errorCode = error.code;
    const errorMessage = error.message;
    // ...
  });
auth_sign_in_custom.js

Nếu xác thực thành công, người dùng sẽ đăng nhập vào ứng dụng khách bằng tài khoản do uid chỉ định trong mã thông báo tuỳ chỉnh. Nếu trước đó tài khoản đó chưa tồn tại, thì hệ thống sẽ tạo một bản ghi cho người dùng đó.

Tương tự như các phương thức đăng nhập khác (chẳng hạn như signInWithEmailAndPassword() và signInWithCredential()), đối tượng auth trong Realtime Database Security Rules và đối tượng request.auth trong Cloud Storage Security Rules sẽ được điền bằng uid của người dùng. Trong trường hợp này, uid sẽ là mã bạn đã chỉ định khi tạo mã thông báo tuỳ chỉnh.

{
  "rules": {
    "adminContent": {
      ".read": "auth.uid === 'some-uid'"
    }
  }
}

service firebase.storage {
  match /b/<your-firebase-storage-bucket>/o {
    match /adminContent/{filename} {
      allow read, write: if request.auth != null && request.auth.uid == "some-uid";
    }
  }
}

Nếu mã thông báo tuỳ chỉnh chứa các thông báo xác nhận bổ sung, thì bạn có thể tham chiếu các thông báo xác nhận đó từ đối tượng auth.token (Firebase Realtime Database) hoặc request.auth.token (Cloud Storage) trong quy tắc:

{
  "rules": {
    "premiumContent": {
      ".read": "auth.token.premiumAccount === true"
    }
  }
}

service firebase.storage {
  match /b/<your-firebase-storage-bucket>/o {
    match /premiumContent/{filename} {
      allow read, write: if request.auth.token.premiumAccount == true;
    }
  }
}

Tạo mã thông báo tuỳ chỉnh bằng thư viện JWT của bên thứ ba

Nếu phần phụ trợ của bạn sử dụng ngôn ngữ không có SDK quản trị Firebase chính thức, bạn vẫn có thể tạo mã thông báo tuỳ chỉnh theo cách thủ công. Trước tiên, hãy tìm thư viện JWT của bên thứ ba cho ngôn ngữ của bạn. Sau đó, hãy sử dụng thư viện JWT đó để tạo một JWT bao gồm các thông báo xác nhận sau:

Dưới đây là một số ví dụ về cách triển khai cách tạo mã thông báo tuỳ chỉnh bằng nhiều ngôn ngữ mà SDK Firebase dành cho quản trị viên không hỗ trợ:

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

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

Sau khi bạn tạo mã thông báo tuỳ chỉnh, hãy gửi mã đó đến ứng dụng khách để sử dụng nhằm xác thực bằng Firebase. Hãy xem các mã mẫu ở trên để biết cách thực hiện việc này.

Khắc phục sự cố

Phần này trình bày một số vấn đề thường gặp mà nhà phát triển có thể gặp phải khi tạo mã thông báo tuỳ chỉnh và cách giải quyết các vấn đề đó.

Chưa bật IAM API

Nếu đang chỉ định mã tài khoản dịch vụ để ký mã thông báo, bạn có thể gặp lỗi tương tự như sau:

Identity and Access Management (IAM) API has not been used in project
1234567890 before or it is disabled. Enable it by visiting
https://console.developers.google.com/apis/api/iam.googleapis.com/overview?project=1234567890
then retry. If you enabled this API recently, wait a few minutes for the action
to propagate to our systems and retry.

SDK Quản trị Firebase sử dụng IAM API để ký mã thông báo. Lỗi này cho biết rằng API IAM hiện không được bật cho dự án Firebase. Mở đường liên kết trong thông báo lỗi trong trình duyệt web rồi nhấp vào nút "Bật API" để bật API cho dự án của bạn.

Tài khoản dịch vụ không có các quyền cần thiết

Nếu tài khoản dịch vụ mà SDK quản trị Firebase đang chạy không có quyền iam.serviceAccounts.signBlob, bạn có thể nhận được thông báo lỗi như sau:

Permission iam.serviceAccounts.signBlob is required to perform this operation
on service account projects/-/serviceAccounts/{your-service-account-id}.

Cách dễ nhất để giải quyết vấn đề này là cấp vai trò IAM "Trình tạo mã thông báo tài khoản dịch vụ" cho tài khoản dịch vụ có liên quan, thường là {project-name}@appspot.gserviceaccount.com:

1. Mở trang IAM và quản trị trong bảng điều khiển Google Cloud.
2. Chọn dự án của bạn rồi nhấp vào "Tiếp tục".
3. Nhấp vào biểu tượng chỉnh sửa tương ứng với tài khoản dịch vụ mà bạn muốn cập nhật.
4. Nhấp vào "Thêm vai trò khác".
5. Nhập "Trình tạo mã thông báo tài khoản dịch vụ" vào bộ lọc tìm kiếm rồi chọn trình tạo đó trong kết quả.
6. Nhấp vào "Lưu" để xác nhận việc cấp vai trò.

Hãy tham khảo tài liệu về IAM để biết thêm thông tin chi tiết về quy trình này hoặc tìm hiểu cách cập nhật vai trò bằng các công cụ dòng lệnh gcloud.

Không xác định được tài khoản dịch vụ

Nếu bạn nhận được thông báo lỗi tương tự như sau, thì SDK Quản trị Firebase chưa được khởi chạy đúng cách.

Failed to determine service account ID. Initialize the SDK with service account
credentials or specify a service account ID with iam.serviceAccounts.signBlob
permission.

Nếu bạn đang dựa vào SDK để tự động khám phá mã tài khoản dịch vụ, hãy đảm bảo rằng mã được triển khai trong môi trường Google được quản lý bằng máy chủ siêu dữ liệu. Nếu không, hãy nhớ chỉ định tệp JSON của tài khoản dịch vụ hoặc mã tài khoản dịch vụ khi khởi chạy SDK.