Nếu Tiện ích bổ sung Google Workspace kết nối với một dịch vụ hoặc API của bên thứ ba yêu cầu được cho phép, thì tiện ích bổ sung đó có thể nhắc người dùng đăng nhập và cho phép truy cập.
Trang này giải thích cách xác thực người dùng bằng một quy trình uỷ quyền (chẳng hạn như OAuth), bao gồm các bước sau:
- Phát hiện thời điểm yêu cầu uỷ quyền.
- Trả về giao diện thẻ nhắc người dùng đăng nhập vào dịch vụ.
- Làm mới tiện ích bổ sung để người dùng có thể truy cập vào dịch vụ hoặc tài nguyên được bảo vệ.
Nếu tiện ích bổ sung của bạn chỉ yêu cầu danh tính người dùng, thì bạn có thể trực tiếp xác thực người dùng bằng cách sử dụng địa chỉ email hoặc mã Google Workspace của họ. Nếu bạn muốn dùng địa chỉ email để xác thực, hãy xem phần xác thực yêu cầu JSON. Nếu bạn đã tạo tiện ích bổ sung bằng Google Apps Script, hãy truy cập tài liệu về Apps Script để tìm hiểu cách kết nối tiện ích bổ sung của bạn với dịch vụ của bên thứ ba.
Phát hiện thấy việc bắt buộc phải được uỷ quyền
Khi sử dụng tiện ích bổ sung, người dùng có thể không được phép truy cập vào tài nguyên được bảo vệ vì nhiều lý do, chẳng hạn như:
- Mã truy cập để kết nối với dịch vụ bên thứ ba chưa được tạo hoặc đã hết hạn.
- Mã truy cập không bao gồm tài nguyên được yêu cầu.
- Mã truy cập không bao gồm phạm vi bắt buộc của yêu cầu.
Tiện ích bổ sung của bạn phải phát hiện các trường hợp này để người dùng có thể đăng nhập và truy cập vào dịch vụ của bạn.
Nhắc người dùng đăng nhập vào dịch vụ của bạn
Khi tiện ích bổ sung của bạn phát hiện thấy cần phải uỷ quyền, tiện ích bổ sung phải trả về giao diện thẻ để nhắc người dùng đăng nhập vào dịch vụ. Thẻ đăng nhập phải chuyển hướng người dùng để hoàn tất quy trình xác thực và uỷ quyền của bên thứ ba trên cơ sở hạ tầng của bạn.
Bạn nên bảo vệ ứng dụng đích bằng tính năng Đăng nhập bằng Google và lấy mã nhận dạng người dùng bằng cách sử dụng mã thông báo nhận dạng được cấp trong quá trình đăng nhập. Thông báo xác nhận quyền sở hữu phụ chứa mã nhận dạng duy nhất của người dùng và có thể được tương quan với mã nhận dạng từ tiện ích bổ sung của bạn.
Tạo và trả lại thẻ đăng nhập
Đối với thẻ đăng nhập của dịch vụ, bạn có thể sử dụng thẻ uỷ quyền cơ bản của Google hoặc bạn có thể tuỳ chỉnh thẻ để cho thấy thêm thông tin, chẳng hạn như biểu trưng của tổ chức. Nếu đang phát hành công khai tiện ích bổ sung, bạn phải sử dụng thẻ tuỳ chỉnh.
Thẻ uỷ quyền cơ bản
Hình ảnh sau đây cho thấy ví dụ về thẻ uỷ quyền cơ bản của Google:
Để sử dụng thẻ uỷ quyền cơ bản, hãy trả về phản hồi JSON sau:
{
"basic_authorization_prompt": {
"authorization_url": "AUTHORIZATION_REDIRECT",
"resource": "RESOURCE_DISPLAY_NAME"
}
}
Thay thế đoạn mã sau:
AUTHORIZATION_REDIRECT: URL của ứng dụng web xử lý việc uỷ quyền.RESOURCE_DISPLAY_NAME: Tên hiển thị của tài nguyên hoặc dịch vụ được bảo vệ. Tên này sẽ hiển thị cho người dùng trên lời nhắc cấp quyền. Ví dụ: nếuRESOURCE_DISPLAY_NAMEcủa bạn làExample Account, thì lời nhắc cho biết "Tiện ích bổ sung này muốn hiển thị thêm thông tin, nhưng nó cần được chấp thuận để truy cập vào Tài khoản mẫu của bạn".
Sau khi hoàn tất việc uỷ quyền, người dùng sẽ được nhắc làm mới tiện ích bổ sung để truy cập vào tài nguyên được bảo vệ.
Thẻ uỷ quyền tuỳ chỉnh
Để sửa đổi lời nhắc uỷ quyền, bạn có thể tạo một thẻ tuỳ chỉnh cho trải nghiệm đăng nhập của dịch vụ.
Nếu đang phát hành công khai tiện ích bổ sung, bạn phải sử dụng thẻ uỷ quyền tuỳ chỉnh. Để tìm hiểu thêm về các yêu cầu khi phát hành ứng dụng trên Google Workspace Marketplace, hãy xem bài viết Giới thiệu về quy trình xem xét ứng dụng.
Các hình ảnh sau đây minh hoạ một thẻ uỷ quyền tuỳ chỉnh mẫu cho trang chủ của tiện ích bổ sung. Thẻ này có biểu trưng, nội dung mô tả và nút đăng nhập:
Để sử dụng ví dụ về thẻ tuỳ chỉnh này, hãy trả về phản hồi JSON sau:
{
"custom_authorization_prompt": {
"action": {
"navigations": [
{
"pushCard": {
"sections": [
{
"widgets": [
{
"image": {
"imageUrl": "LOGO_URL",
"altText": "LOGO_ALT_TEXT"
}
},
{
"divider": {}
},
{
"textParagraph": {
"text": "DESCRIPTION"
}
},
{
"buttonList": {
"buttons": [
{
"text": "Sign in",
"onClick": {
"openLink": {
"url": "AUTHORIZATION_REDIRECT",
"onClose": "RELOAD",
"openAs": "OVERLAY"
}
},
"color": {
"red": 0,
"green": 0,
"blue": 1,
"alpha": 1,
}
}
]
}
},
{
"textParagraph": {
"text": "TEXT_SIGN_UP"
}
}
]
}
]
}
}
]
}
}
}
Thay thế đoạn mã sau:
LOGO_URL: URL của một biểu trưng hoặc hình ảnh. Phải là URL công khai.LOGO_ALT_TEXT: Văn bản thay thế cho biểu trưng hoặc hình ảnh, chẳng hạn nhưCymbal Labs Logo.DESCRIPTION: Lời kêu gọi hành động để người dùng đăng nhập, chẳng hạn nhưSign in to get started.- Cách cập nhật nút đăng nhập:
AUTHORIZATION_REDIRECT: URL của ứng dụng web xử lý việc uỷ quyền.- Không bắt buộc: Để thay đổi màu nút, hãy cập nhật giá trị số thực RGBA của trường
color.
TEXT_SIGN_UP: Một văn bản nhắc người dùng tạo tài khoản nếu họ chưa có. Ví dụ:New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here.