আপনার Google Workspace অ্যাড-অন যদি কোনও থার্ড-পার্টি পরিষেবা বা API-এর সাথে কানেক্ট করে, যার অনুমোদন প্রয়োজন, তাহলে অ্যাড-অন ব্যবহারকারীদের সাইন-ইন করতে ও অ্যাক্সেস অনুমোদন করতে প্রম্পট দেখাতে পারে।
এই পৃষ্ঠায় অনুমোদনের ফ্লো (যেমন, OAuth) ব্যবহার করে কীভাবে ব্যবহারকারীদের যাচাই করা যায় তা ব্যাখ্যা করা হয়েছে। এর মধ্যে নিম্নলিখিত ধাপগুলি অন্তর্ভুক্ত:
- অনুমোদন কখন প্রয়োজন তা শনাক্ত করা।
- এমন একটি কার্ড ইন্টারফেস রিটার্ন করুন যা ব্যবহারকারীদের পরিষেবায় সাইন-ইন করার জন্য প্রম্পট করে।
- অ্যাড-অন রিফ্রেশ করুন যাতে ব্যবহারকারীরা পরিষেবা বা সুরক্ষিত রিসোর্স অ্যাক্সেস করতে পারেন।
আপনার অ্যাড-অনের জন্য শুধুমাত্র ব্যবহারকারীর পরিচয় প্রয়োজন হলে, আপনি সরাসরি ব্যবহারকারীর Google Workspace আইডি বা ইমেল আইডি ব্যবহার করে তাদের যাচাই করতে পারবেন। যাচাইকরণের জন্য ইমেল আইডি ব্যবহার করতে, JSON অনুরোধ যাচাই করা দেখুন। আপনি Google Apps স্ক্রিপ্ট ব্যবহার করে অ্যাড-অন তৈরি করে থাকলে, Google Apps স্ক্রিপ্ট লাইব্রেরির জন্য OAuth2 ব্যবহার করে এই প্রসেস আরও সহজ করতে পারবেন (এছাড়াও, একটি OAuth1 ভার্সন আছে)।
অনুমোদন প্রয়োজন কিনা তা শনাক্ত করা
আপনার অ্যাড-অন ব্যবহার করার সময়, ব্যবহারকারীকে বিভিন্ন কারণে সুরক্ষিত রিসোর্স অ্যাক্সেস করার অনুমতি নাও দেওয়া হতে পারে, যেমন নিচে উল্লেখ করা কারণগুলি:
- থার্ড-পার্টি পরিষেবার সাথে কানেক্ট করার জন্য অ্যাক্সেস টোকেন এখনও তৈরি করা হয়নি অথবা সেটির মেয়াদ শেষ হয়ে গেছে।
- অ্যাক্সেস টোকেন অনুরোধ করা রিসোর্স কভার করে না।
- অ্যাক্সেস টোকেন অনুরোধের প্রয়োজনীয় স্কোপ কভার করে না।
আপনার অ্যাড-অনকে এইসব কেস শনাক্ত করতে হবে যাতে ব্যবহারকারীরা সাইন-ইন করে আপনার পরিষেবা অ্যাক্সেস করতে পারেন।
আপনি Apps স্ক্রিপ্টে তৈরি করলে, OAuth লাইব্রেরি
hasAccess ফাংশন আপনাকে বলতে পারবে যে আপনার কোনও পরিষেবায় অ্যাক্সেস আছে কিনা।
অথবা, UrlFetchApp.fetch
অনুরোধ ব্যবহার করার সময়, আপনি muteHttpExceptions প্যারামিটারকে true হিসেবে সেট করতে পারবেন। এর ফলে
অনুরোধ ব্যর্থ হলে অনুরোধটি কোনও ব্যতিক্রম তৈরি করে না এবং আপনি
ফেরত আসা HttpResponse অবজেক্টে অনুরোধের
রেসপন্স কোড ও কন্টেন্ট পরীক্ষা করতে পারেন।
আপনার পরিষেবায় সাইন-ইন করার জন্য ব্যবহারকারীদের প্রম্পট করা
আপনার অ্যাড-অন যখন শনাক্ত করে যে অনুমোদনের প্রয়োজন আছে, তখন অ্যাড-অনকে অবশ্যই একটি কার্ড ইন্টারফেস রিটার্ন করতে হবে যাতে ব্যবহারকারীকে পরিষেবায় সাইন-ইন করার জন্য প্রম্পট করা যায়। সাইন-ইন কার্ডকে অবশ্যই ব্যবহারকারীদের আপনার ইনফ্রাস্ট্রাকচারে থার্ড-পার্টি যাচাইকরণ ও অনুমোদন প্রক্রিয়া সম্পূর্ণ করার জন্য রিডাইরেক্ট করতে হবে।
HTTP এন্ডপয়েন্ট ব্যবহার করে আপনার অ্যাড-অন তৈরি করার সময়, আমরা সাজেস্ট করি যে আপনি Google সাইন-ইন ব্যবহার করে ডেস্টিনেশন অ্যাপকে সুরক্ষিত করুন এবং সাইন-ইন করার সময় ইস্যু করা পরিচয় টোকেন ব্যবহার করে ব্যবহারকারীর আইডি পান। সাব-ক্লেমে ব্যবহারকারীর অনন্য আইডি থাকে এবং এটি আপনার অ্যাড-অন থেকে পাওয়া আইডির সাথে কোরিলেট করা যেতে পারে।
সাইন-ইন কার্ড তৈরি ও রিটার্ন করা
আপনার পরিষেবার সাইন-ইন কার্ডের জন্য, আপনি Google-এর প্রাথমিক অনুমোদন কার্ড ব্যবহার করতে পারেন অথবা আপনার সংস্থার লোগোর মতো অতিরিক্ত তথ্য দেখাতে, আপনি কার্ড কাস্টমাইজ করতে পারেন। আপনি নিজের অ্যাড-অন সর্বজনীনভাবে প্রকাশ করলে, আপনাকে অবশ্যই কাস্টম কার্ড ব্যবহার করতে হবে।
প্রাথমিক অনুমোদনের কার্ড
নিচের ছবিতে Google-এর সাধারণ অনুমোদন কার্ডের একটি উদাহরণ দেখানো হয়েছে:
ব্যবহারকারীদের একটি প্রাথমিক অনুমোদন কার্ড সহ প্রম্পট করতে, আপনাকে অবশ্যই অবজেক্ট
AuthorizationError রিটার্ন করতে হবে। নিচের কোডে একটি
AuthorizationError অবজেক্টের উদাহরণ দেখানো হয়েছে:
Apps Script
CardService.newAuthorizationException()
.setAuthorizationUrl('AUTHORIZATION_URL')
.setResourceDisplayName('RESOURCE_DISPLAY_NAME')
.throwException();JSON
নিম্নলিখিত JSON উত্তর দিন:
{
"basic_authorization_prompt": {
"authorization_url": "AUTHORIZATION_URL",
"resource": "RESOURCE_DISPLAY_NAME"
}
}
নিম্নলিখিত বিষয়গুলি পরিবর্তন করুন:
AUTHORIZATION_URL: ওয়েব অ্যাপের URL যা অনুমোদন ম্যানেজ করে।RESOURCE_DISPLAY_NAME: সুরক্ষিত রিসোর্স বা পরিষেবার ডিসপ্লে নাম। অনুমতি সংক্রান্ত প্রম্পটে ব্যবহারকারীকে এই নাম দেখানো হয়। যেমন, আপনারRESOURCE_DISPLAY_NAMEহলExample Account, তাহলে প্রম্পটে বলা হবে, "এই অ্যাড-অন অতিরিক্ত তথ্য দেখাতে চায়, কিন্তু আপনার Example Account অ্যাক্সেস করার জন্য এটির অনুমতি প্রয়োজন।"
অনুমোদন সম্পূর্ণ করার পরে, সুরক্ষিত রিসোর্স অ্যাক্সেস করতে অ্যাড-অন রিফ্রেশ করার জন্য ব্যবহারকারীকে প্রম্পট করা হয়।
Google Chat-এ রিটার্ন অথরাইজেশন কার্ড
আপনার অ্যাড-অন Google Chat-এর কার্যকারিতা বাড়ালে এবং ব্যবহারকারী
Google Chat-এর মধ্যে এটি এক্সিকিউট করলে, ব্যবহারকারী ম্যানুয়াল রিফ্রেশ
করা ছাড়াই অনুমোদন প্রক্রিয়া সম্পূর্ণ করতে পারবেন। Google Chat-এ, আগের এক্সিকিউশন অটোমেটিক আবার চেষ্টা করা যায়, যদি
ট্রিগার
মেসেজ, স্পেসে যোগ করা হয়েছে বা অ্যাপ কমান্ড হয়। এইসব ট্রিগারের জন্য, আপনার
অ্যাড-অন ইভেন্ট পেলোড-এ completeRedirectUri পায়।
অটোমেটিক আবার চেষ্টা করার প্রসেস ট্রিগার করতে, আপনাকে কনফিগারেশন URL-এ completeRedirectUri এনকোড করতে হবে।
এই URL-এ রিডাইরেক্ট করা হলে Google Chat বুঝতে পারে যে
কনফিগারেশন সংক্রান্ত অনুরোধটি সম্পূর্ণ হয়েছে এবং Google Chat-কে
আগের এক্সিকিউশন আবার চেষ্টা করার অনুমতি দেয়।
ব্যবহারকারীকে আসল মেসেজে দেওয়া configCompleteRedirectUrl
লিঙ্কে সফলভাবে রিডাইরেক্ট করা হলে, Google Chat নিম্নলিখিত ধাপগুলি সম্পূর্ণ করে:
- যে ব্যবহারকারী প্রম্পট শুরু করেছেন তাকে দেখানো প্রম্পট মুছে দেয়।
- একই অ্যাড-অনে দ্বিতীয়বার আসল ইভেন্ট অবজেক্ট পাঠায়।
আপনি কনফিগারেশন URL-এ completeRedirectUri এনকোড না করলেও, ব্যবহারকারী
এখনও অনুমোদন ফ্লো সম্পূর্ণ করতে পারবেন। তবে, Google Chat আগের এক্সিকিউশন আবার
করে না এবং ব্যবহারকারীকে আপনার অ্যাড-অন আবার
ম্যানুয়ালি ইনভোক করতে হবে।
নিম্নলিখিত কোড স্যাম্পেল থেকে বোঝা যায় যে কীভাবে কোনও চ্যাট অ্যাপ অফলাইন OAuth2 ক্রেডেনশিয়াল অনুরোধ করতে, সেগুলি ডেটাবেসে সেভ করতে এবং ব্যবহারকারী যাচাইকরণ সহ API কল করতে ব্যবহার করতে পারে।
Apps Script
Node.js
Python
Java
কাস্টম অনুমোদনের কার্ড
অনুমোদন প্রম্পট পরিবর্তন করতে, আপনার পরিষেবার সাইন-ইন অভিজ্ঞতার জন্য কাস্টম কার্ড তৈরি করতে পারেন।
আপনি নিজের অ্যাড-অন সর্বজনীনভাবে প্রকাশ করলে, আপনাকে Chat ছাড়া সব Google Workspace হোস্ট অ্যাপ্লিকেশনের জন্য কাস্টম অনুমোদনের কার্ড ব্যবহার করতে হবে। Google Workspace Marketplace-এ প্রকাশ করার প্রয়োজনীয়তা সম্পর্কে আরও জানতে, অ্যাপ পর্যালোচনা সম্পর্কে দেখুন।
ফেরত পাঠানো কার্ডে নিম্নলিখিত বিষয়গুলি থাকতে হবে:
- ব্যবহারকারীকে স্পষ্টভাবে জানিয়ে দিন যে অ্যাড-অনটি তার হয়ে অ্যাক্সেস করার জন্য Google-এর নয় এমন কোনও পরিষেবার অনুমতি চাইছে।
- অনুমোদিত হলে অ্যাড-অন কী কী করতে পারবে তা স্পষ্ট করে বলো।
- এতে একটি বোতাম বা একই ধরনের উইজেট থাকতে হবে যা ব্যবহারকারীকে পরিষেবার অনুমোদন URL-এ নিয়ে যায়। নিশ্চিত করুন যে ব্যবহারকারী এই উইজেটের ফাংশন বুঝতে পারছেন।
- আগের উইজেটের
OpenLinkঅবজেক্টেOnClose.RELOADসেটিং ব্যবহার করতে হবে, যাতে অনুমোদন পাওয়ার পরে অ্যাড-অন আবার লোড করা যায়। - অনুমতি সংক্রান্ত প্রম্পট থেকে খোলা সব লিঙ্কে HTTPS ব্যবহার করতে হবে।
নিচের ছবিতে অ্যাড-অনের হোমপেজের জন্য কাস্টম অনুমোদনের কার্ডের একটি উদাহরণ দেখানো হয়েছে। কার্ডে লোগো, বিবরণ ও সাইন-ইন বোতাম থাকে:
এই কাস্টম কার্ডের উদাহরণ কীভাবে ব্যবহার করতে হয় তা নিম্নলিখিত কোড থেকে জানতে পারবেন:
Apps Script
function customAuthorizationCard() {
let cardSection1Image1 = CardService.newImage()
.setImageUrl('LOGO_URL')
.setAltText('LOGO_ALT_TEXT');
let cardSection1Divider1 = CardService.newDivider();
let cardSection1TextParagraph1 = CardService.newTextParagraph()
.setText('DESCRIPTION');
let cardSection1ButtonList1Button1 = CardService.newTextButton()
.setText('Sign in')
.setBackgroundColor('#0055ff')
.setTextButtonStyle(CardService.TextButtonStyle.FILLED)
.setAuthorizationAction(CardService.newAuthorizationAction()
.setAuthorizationUrl('AUTHORIZATION_URL'));
let cardSection1ButtonList1 = CardService.newButtonSet()
.addButton(cardSection1ButtonList1Button1);
let cardSection1TextParagraph2 = CardService.newTextParagraph()
.setText('TEXT_SIGN_UP');
let cardSection1 = CardService.newCardSection()
.addWidget(cardSection1Image1)
.addWidget(cardSection1Divider1)
.addWidget(cardSection1TextParagraph1)
.addWidget(cardSection1ButtonList1)
.addWidget(cardSection1TextParagraph2);
let card = CardService.newCardBuilder()
.addSection(cardSection1)
.build();
return [card];
}
function startNonGoogleAuth() {
CardService.newAuthorizationException()
.setAuthorizationUrl('AUTHORIZATION_URL')
.setResourceDisplayName('RESOURCE_DISPLAY_NAME')
.setCustomUiCallback('customAuthorizationCard')
.throwException();
}
JSON
নিম্নলিখিত JSON উত্তর দিন:
{
"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_URL",
"onClose": "RELOAD",
"openAs": "OVERLAY"
}
},
"color": {
"red": 0,
"green": 0,
"blue": 1,
"alpha": 1,
}
}
]
}
},
{
"textParagraph": {
"text": "TEXT_SIGN_UP"
}
}
]
}
]
}
}
]
}
}
}
নিম্নলিখিত বিষয়গুলি পরিবর্তন করুন:
LOGO_URL: লোগো বা ছবির URL. অবশ্যই পাবলিক URL হতে হবে।LOGO_ALT_TEXT: লোগো বা ছবির জন্য বিকল্প টেক্সট, যেমনCymbal Labs Logo।DESCRIPTION: ব্যবহারকারীদের সাইন-ইন করার জন্য কল টু অ্যাকশন, যেমনSign in to get started।- সাইন-ইন বোতাম আপডেট করতে:
AUTHORIZATION_URL: ওয়েব অ্যাপের URL যা অনুমোদন ম্যানেজ করে।- ঐচ্ছিক: বোতামের রঙ পরিবর্তন করতে,
colorফিল্ডের RGBA ফ্লোট ভ্যালু আপডেট করুন। Apps Script-এর জন্য, হেক্সাডেসিমাল ভ্যালু ব্যবহার করেsetBackgroundColorমেথড আপডেট করুন।
TEXT_SIGN_UP: ব্যবহারকারীর অ্যাকাউন্ট না থাকলে, অ্যাকাউন্ট তৈরি করার জন্য প্রম্পট করা টেক্সট। যেমন,New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here
Google Workspace অ্যাপ জুড়ে থার্ড-পার্টি লগ-ইন ম্যানেজ করা
Google Workspace অ্যাড-অনের একটি সাধারণ অ্যাপ্লিকেশন হল Google Workspace-এর হোস্ট অ্যাপ্লিকেশন-এর মধ্যে থেকে থার্ড-পার্টি সিস্টেমের সাথে ইন্টার্যাক্ট করার জন্য একটি ইন্টারফেস প্রদান করা।
থার্ড-পার্টি সিস্টেমে প্রায়ই ব্যবহারকারীকে ইউজার আইডি, পাসওয়ার্ড বা অন্যান্য ক্রেডেনশিয়াল ব্যবহার করে সাইন-ইন করতে হয়। কোনও ব্যবহারকারী একটি Google Workspace হোস্ট ব্যবহার করার সময় আপনার থার্ড-পার্টি পরিষেবায় সাইন-ইন করলে, তিনি অন্য Google Workspace হোস্টে পরিবর্তন করার সময় তাকে আবার সাইন-ইন করতে হবে না, তা আপনাকে নিশ্চিত করতে হবে।
আপনি Apps Script-এ তৈরি করলে, ব্যবহারকারীর প্রপার্টি বা আইডি টোকেনের মাধ্যমে বারবার লগ-ইন করার অনুরোধ প্রতিরোধ করতে পারবেন। এগুলি নিম্নলিখিত বিভাগে ব্যাখ্যা করা হয়েছে।
ব্যবহারকারীর প্রপার্টি
আপনি Apps স্ক্রিপ্টের user properties-এ ব্যবহারকারীর সাইন-ইন ডেটা সেভ করতে পারবেন। যেমন, আপনি তাদের লগ-ইন পরিষেবা থেকে নিজের JSON ওয়েব টোকেন (JWT) তৈরি করতে পারেন এবং সেটি ব্যবহারকারীর প্রপার্টিতে রেকর্ড করতে পারেন অথবা তাদের পরিষেবার জন্য ইউজারনেম ও পাসওয়ার্ড রেকর্ড করতে পারেন।
ব্যবহারকারীর প্রপার্টি এমনভাবে স্কোপ করা হয় যে সেগুলি শুধুমাত্র আপনার অ্যাড-অনের স্ক্রিপ্টের মধ্যে
সেই ব্যবহারকারীর অ্যাক্সেস করতে পারেন। অন্যান্য ব্যবহারকারী ও অন্যান্য
স্ক্রিপ্ট এইসব প্রপার্টি অ্যাক্সেস করতে পারবে না। আরও বিবরণের জন্য
PropertiesService
দেখুন।
আইডি টোকেন
আপনার পরিষেবার জন্য লগ-ইন ক্রেডেনশিয়াল হিসেবে Google ID টোকেন ব্যবহার করতে পারবেন। এটি সিঙ্গেল সাইন-অন পাওয়ার একটি উপায়। ব্যবহারকারীরা আগেই Google-এ লগ-ইন করেছেন কারণ তারা Google হোস্ট অ্যাপে আছেন।
Google নয় এমন OAuth কনফিগারেশনের উদাহরণ
নিচে দেওয়া Apps Script কোড স্যাম্পেল থেকে জানা যায় যে OAuth-এর প্রয়োজন হয় এমন Google-এর নয় এমন API ব্যবহার করার জন্য কীভাবে কোনও অ্যাড-অন কনফিগার করতে হয়। API অ্যাক্সেস করার জন্য পরিষেবা তৈরি করতে, এই নমুনা Apps Script লাইব্রেরির জন্য OAuth2 ব্যবহার করে।
Apps Script
/**
* Attempts to access a non-Google API using a constructed service
* object.
*
* If your add-on needs access to non-Google APIs that require OAuth,
* you need to implement this method. You can use the OAuth1 and
* OAuth2 Apps Script libraries to help implement it.
*
* @param {String} url The URL to access.
* @param {String} method_opt The HTTP method. Defaults to GET.
* @param {Object} headers_opt The HTTP headers. Defaults to an empty
* object. The Authorization field is added
* to the headers in this method.
* @return {HttpResponse} the result from the UrlFetchApp.fetch() call.
*/
function accessProtectedResource(url, method_opt, headers_opt) {
var service = getOAuthService();
var maybeAuthorized = service.hasAccess();
if (maybeAuthorized) {
// A token is present, but it may be expired or invalid. Make a
// request and check the response code to be sure.
// Make the UrlFetch request and return the result.
var accessToken = service.getAccessToken();
var method = method_opt || 'get';
var headers = headers_opt || {};
headers['Authorization'] =
Utilities.formatString('Bearer %s', accessToken);
var resp = UrlFetchApp.fetch(url, {
'headers': headers,
'method' : method,
'muteHttpExceptions': true, // Prevents thrown HTTP exceptions.
});
var code = resp.getResponseCode();
if (code >= 200 && code < 300) {
return resp.getContentText("utf-8"); // Success
} else if (code == 401 || code == 403) {
// Not fully authorized for this action.
maybeAuthorized = false;
} else {
// Handle other response codes by logging them and throwing an
// exception.
console.error("Backend server error (%s): %s", code.toString(),
resp.getContentText("utf-8"));
throw ("Backend server error: " + code);
}
}
if (!maybeAuthorized) {
// Invoke the authorization flow using the default authorization
// prompt card.
CardService.newAuthorizationException()
.setAuthorizationUrl(service.getAuthorizationUrl())
.setResourceDisplayName("Display name to show to the user")
.throwException();
}
}
/**
* Create a new OAuth service to facilitate accessing an API.
* This example assumes there is a single service that the add-on needs to
* access. Its name is used when persisting the authorized token, so ensure
* it is unique within the scope of the property store. You must set the
* client secret and client ID, which are obtained when registering your
* add-on with the API.
*
* See the Apps Script OAuth2 Library documentation for more
* information:
* https://github.com/googlesamples/apps-script-oauth2#1-create-the-oauth2-service
*
* @return A configured OAuth2 service object.
*/
function getOAuthService() {
return OAuth2.createService('SERVICE_NAME')
.setAuthorizationBaseUrl('SERVICE_AUTH_URL')
.setTokenUrl('SERVICE_AUTH_TOKEN_URL')
.setClientId('CLIENT_ID')
.setClientSecret('CLIENT_SECRET')
.setScope('SERVICE_SCOPE_REQUESTS')
.setCallbackFunction('authCallback')
.setCache(CacheService.getUserCache())
.setPropertyStore(PropertiesService.getUserProperties());
}
/**
* Boilerplate code to determine if a request is authorized and returns
* a corresponding HTML message. When the user completes the OAuth2 flow
* on the service provider's website, this function is invoked from the
* service. In order for authorization to succeed you must make sure that
* the service knows how to call this function by setting the correct
* redirect URL.
*
* The redirect URL to enter is:
* https://script.google.com/macros/d/<Apps Script ID>/usercallback
*
* See the Apps Script OAuth2 Library documentation for more
* information:
* https://github.com/googlesamples/apps-script-oauth2#1-create-the-oauth2-service
*
* @param {Object} callbackRequest The request data received from the
* callback function. Pass it to the service's
* handleCallback() method to complete the
* authorization process.
* @return {HtmlOutput} a success or denied HTML message to display to
* the user.
*/
function authCallback(callbackRequest) {
var authorized = getOAuthService().handleCallback(callbackRequest);
if (authorized) {
return HtmlService.createHtmlOutput(
'Success!');
} else {
return HtmlService.createHtmlOutput('Denied');
}
}
/**
* Unauthorizes the non-Google service. This is useful for OAuth
* development/testing. Run this method (Run > resetOAuth in the script
* editor) to reset OAuth to re-prompt the user for OAuth.
*/
function resetOAuth() {
getOAuthService().reset();
}