টিভি ও লিমিটেড ইনপুট ডিভাইস অ্যাপ্লিকেশনের জন্য OAuth 2.0

গুরুত্বপূর্ণ নোট: এই OAuth 2.0 ফ্লো সীমিত সংখ্যক স্কোপ সাপোর্ট করে।

এই ডকুমেন্ট থেকে জানতে পারবেন যে টিভি, গেম কনসোল ও প্রিন্টারের মতো ডিভাইসে চলা অ্যাপ্লিকেশনের মাধ্যমে Google API অ্যাক্সেস করার জন্য কীভাবে OAuth 2.0 অথরাইজেশন প্রয়োগ করতে হয়। আরও নির্দিষ্ট করে বলতে গেলে, এই ফ্লো এমন ডিভাইসের জন্য ডিজাইন করা হয়েছে যেগুলির ব্রাউজারে অ্যাক্সেস নেই অথবা ইনপুট করার ক্ষমতা সীমিত।

OAuth 2.0 ব্যবহারকারীদের তাদের ইউজারনেম, পাসওয়ার্ড এবং অন্যান্য তথ্য গোপন রেখে একটি অ্যাপ্লিকেশনের সাথে নির্দিষ্ট ডেটা শেয়ার করতে দেয়। যেমন, Google Drive-এ স্টোর করা ফাইল বেছে নেওয়ার অনুমতি পেতে, কোনও টিভি অ্যাপ্লিকেশন OAuth 2.0 ব্যবহার করতে পারে।

যেহেতু এই ফ্লো ব্যবহার করা অ্যাপ্লিকেশনগুলি আলাদা আলাদা ডিভাইসে ডিস্ট্রিবিউট করা হয়, তাই ধরে নেওয়া হয় যে অ্যাপগুলি গোপনীয়তা বজায় রাখতে পারে না। ব্যবহারকারী অ্যাপে উপস্থিত থাকাকালীন বা অ্যাপটি ব্যাকগ্রাউন্ডে চলাকালীন তারা Google API অ্যাক্সেস করতে পারে।

বিকল্প

আপনি যদি শুধুমাত্র ব্যবহারকারীদের Google অ্যাকাউন্ট দিয়ে সাইন-ইন করাতে চান এবং JWT আইডি টোকেন ব্যবহার করে ব্যবহারকারীর প্রোফাইলের প্রাথমিক তথ্য পেতে চান, তাহলে টিভিতে সাইন-ইন এবং সীমিত ইনপুট ডিভাইস দেখুন।

পূর্বশর্ত

আপনার প্রোজেক্টের জন্য API চালু করা

Google API কল করে এমন যেকোনও অ্যাপ্লিকেশনকে API কনসোলে সেইসব API চালু করতে হবে।

আপনার প্রোজেক্টের জন্য API চালু করতে:

1. Google API Console-এ API লাইব্রেরি খুলুন।
2. প্রম্পট করা হলে, কোনও প্রোজেক্ট বেছে নিন অথবা নতুন একটি তৈরি করুন।
3. API লাইব্রেরিতে উপলভ্য সব API-এর তালিকা থাকে, যা প্রোডাক্ট ফ্যামিলি ও জনপ্রিয়তার ভিত্তিতে গ্রুপ করা থাকে। আপনি যে API চালু করতে চান সেটি তালিকায় দেখতে না পেলে, সার্চ করে সেটি খুঁজে নিন অথবা যে প্রোডাক্ট ফ্যামিলির অন্তর্গত সেটিতে সব দেখুন বিকল্পে ক্লিক করুন।
4. আপনি যে API চালু করতে চান সেটি বেছে নিন, তারপর চালু করুন বোতামে ক্লিক করুন।
5. প্রম্পট করা হলে, বিলিং চালু করুন।
6. প্রম্পট করা হলে, API-এর পরিষেবার শর্তাবলী পড়ে সম্মতি দিন।

অনুমোদনের ক্রেডেনশিয়াল তৈরি করুন

Google API অ্যাক্সেস করার জন্য OAuth 2.0 ব্যবহার করে এমন যেকোনও অ্যাপ্লিকেশনের কাছে অবশ্যই অনুমোদনের ক্রেডেনশিয়াল থাকতে হবে যা Google-এর OAuth 2.0 সার্ভারে অ্যাপ্লিকেশনটিকে শনাক্ত করে। আপনার প্রোজেক্টের জন্য কীভাবে ক্রেডেনশিয়াল তৈরি করবেন তা নিম্নলিখিত ধাপগুলি থেকে জানতে পারবেন। আপনার অ্যাপ্লিকেশন তখন ক্রেডেনশিয়াল ব্যবহার করে সেইসব API অ্যাক্সেস করতে পারবে যেগুলি আপনি সেই প্রোজেক্টের জন্য চালু করেছেন।

1. ক্লায়েন্ট পৃষ্ঠায় যান।
2. ক্লায়েন্ট তৈরি করুন বিকল্পে ক্লিক করুন।
3. টিভি ও লিমিটেড ইনপুট ডিভাইস অ্যাপ্লিকেশন টাইপ বেছে নিন।
4. আপনার OAuth 2.0 ক্লায়েন্টের নাম দিন এবং তৈরি করুন বিকল্পে ক্লিক করুন।

অ্যাক্সেস স্কোপ শনাক্ত করা

স্কোপ আপনার অ্যাপ্লিকেশনকে শুধুমাত্র প্রয়োজনীয় রিসোর্স অ্যাক্সেস করার অনুরোধ করতে দেয় এবং ব্যবহারকারীদের আপনার অ্যাপ্লিকেশনকে দেওয়া অ্যাক্সেসের পরিমাণ নিয়ন্ত্রণ করতে দেয়। তাই, অনুরোধ করা স্কোপের সংখ্যা এবং ব্যবহারকারীর সম্মতি পাওয়ার সম্ভাবনার মধ্যে বিপরীত সম্পর্ক থাকতে পারে।

OAuth 2.0 অনুমোদন প্রয়োগ করা শুরু করার আগে, আমরা সাজেস্ট করি যে আপনি সেইসব স্কোপ শনাক্ত করুন যেগুলি অ্যাক্সেস করার জন্য আপনার অ্যাপের অনুমতি প্রয়োজন হবে।

মনে রাখবেন: ইনস্টল করা অ্যাপ বা ডিভাইসের ক্ষেত্রে ইনক্রিমেন্টাল অথরাইজেশন কাজ করে না।

ইনস্টল করা অ্যাপ বা ডিভাইসের জন্য অনুমোদিত স্কোপ-এর তালিকা দেখুন।

আপনার পাবলিক অ্যাপ্লিকেশন যদি এমন স্কোপ ব্যবহার করে যা নির্দিষ্ট ব্যবহারকারীর ডেটা অ্যাক্সেস করার অনুমতি দেয়, তাহলে এটিকে অবশ্যই যাচাইকরণ প্রক্রিয়া সম্পূর্ণ করতে হবে। আপনার অ্যাপ্লিকেশন পরীক্ষা করার সময় স্ক্রিনে যাচাই না করা অ্যাপ দেখতে পেলে, এটি সরানোর জন্য আপনাকে যাচাইকরণের অনুরোধ জমা দিতে হবে। যাচাই না করা অ্যাপ সম্পর্কে আরও জানুন এবং সহায়তা কেন্দ্র থেকে অ্যাপ যাচাইকরণ সম্পর্কে প্রায়শই জিজ্ঞাসিত প্রশ্নের উত্তর পান।

OAuth 2.0 অ্যাক্সেস টোকেন পাওয়া

আপনার অ্যাপ্লিকেশন সীমিত ইনপুট ক্ষমতা সহ ডিভাইসে চললেও, এই অনুমোদনের ফ্লো সম্পূর্ণ করার জন্য ব্যবহারকারীদের কাছে আরও বেশি ইনপুট ক্ষমতা সহ ডিভাইসে আলাদা অ্যাক্সেস থাকতে হবে। ফ্লোতে নিম্নলিখিত ধাপগুলি রয়েছে:

1. আপনার অ্যাপ্লিকেশন Google-এর অনুমোদন সার্ভারে একটি অনুরোধ পাঠায় যা আপনার অ্যাপ্লিকেশন অ্যাক্সেস করার জন্য অনুমতি চাইবে এমন স্কোপ শনাক্ত করে।
2. সার্ভার বিভিন্ন তথ্য দিয়ে উত্তর দেয় যা পরবর্তী ধাপে ব্যবহার করা হয়, যেমন ডিভাইস কোড ও ব্যবহারকারী কোড।
3. আপনি এমন তথ্য দেখান যা ব্যবহারকারী আপনার অ্যাপকে অনুমতি দেওয়ার জন্য আলাদা ডিভাইসে লিখতে পারেন।
4. ব্যবহারকারী আপনার অ্যাপকে অনুমতি দিয়েছেন কিনা তা নির্ধারণ করতে আপনার অ্যাপ্লিকেশন Google-এর অনুমোদন সার্ভার পোল করা শুরু করে।
5. ব্যবহারকারী আরও ভাল ইনপুট ক্ষমতা সহ ডিভাইসে পাল্টে নেন, ওয়েব ব্রাউজার চালু করেন, ৩ নম্বর ধাপে দেখানো URL-এ যান এবং ৩ নম্বর ধাপে দেখানো কোডটি লেখেন। ব্যবহারকারী তখন আপনার অ্যাপ্লিকেশনকে অ্যাক্সেস দিতে (বা অস্বীকার করতে) পারেন।
6. আপনার পোলিং অনুরোধের পরবর্তী উত্তরে সেই টোকেন থাকে যা আপনার অ্যাপের ব্যবহারকারীর হয়ে অনুরোধ অনুমোদন করার জন্য প্রয়োজন। (ব্যবহারকারী আপনার অ্যাপ্লিকেশন অ্যাক্সেস করতে না দিলে, উত্তরে টোকেন থাকে না।)

ছবিতে এই প্রসেসটি দেখানো হয়েছে:

নিচের বিভাগগুলিতে এইসব ধাপের ব্যাপারে বিস্তারিতভাবে ব্যাখ্যা করা হয়েছে। ডিভাইসের ক্ষমতা এবং রানটাইম এনভায়রনমেন্টের পরিসীমা বিবেচনা করে, এই ডকুমেন্টে দেখানো উদাহরণগুলি curl কমান্ড লাইন ইউটিলিটি ব্যবহার করে। এইসব উদাহরণ বিভিন্ন ভাষা ও রানটাইমে পোর্ট করা যেতে পারে।

ধাপ ১: ডিভাইস ও ব্যবহারকারীর কোডের জন্য অনুরোধ করা

এই ধাপে, আপনার ডিভাইস Google-এর অথরাইজেশন সার্ভারে, https://oauth2.googleapis.com/device/code-এ, একটি HTTP POST অনুরোধ পাঠায়, যা আপনার অ্যাপ্লিকেশন এবং ব্যবহারকারীর হয়ে আপনার অ্যাপ্লিকেশন যে অ্যাক্সেস স্কোপ অ্যাক্সেস করতে চায় তা শনাক্ত করে। device_authorization_endpoint মেটাডেটা ভ্যালু ব্যবহার করে ডিসকভারি ডকুমেন্ট থেকে আপনাকে এই URL ফিরিয়ে আনতে হবে। নিম্নলিখিত HTTP অনুরোধের প্যারামিটার যোগ করুন:

প্যারামিটারগুলি
client_id	আবশ্যক আপনার অ্যাপ্লিকেশনের জন্য ক্লায়েন্ট আইডি। আপনি এই ভ্যালু Cloud Console ক্লায়েন্ট পৃষ্ঠায় দেখতে পাবেন।
scope	আবশ্যক ব্যবহারকারীর হয়ে আপনার অ্যাপ্লিকেশন যেসব রিসোর্স অ্যাক্সেস করতে পারে, সেগুলি শনাক্ত করার জন্য স্পেস-ডিলিমিটেড স্কোপের তালিকা। এইসব ভ্যালু সম্মতি সংক্রান্ত স্ক্রিনকে জানায় যে Google ব্যবহারকারীকে কী দেখায়। ইনস্টল করা অ্যাপ বা ডিভাইসের জন্য অনুমোদিত স্কোপ তালিকা দেখুন। স্কোপ আপনার অ্যাপ্লিকেশনকে শুধুমাত্র প্রয়োজনীয় রিসোর্স অ্যাক্সেস করার অনুরোধ করতে দেয় এবং ব্যবহারকারীদের আপনার অ্যাপ্লিকেশনকে দেওয়া অ্যাক্সেসের পরিমাণ নিয়ন্ত্রণ করতে দেয়। তাই, অনুরোধ করা স্কোপের সংখ্যা এবং ব্যবহারকারীর সম্মতি পাওয়ার সম্ভাবনার মধ্যে বিপরীত সম্পর্ক রয়েছে।

উদাহরণ

নিম্নলিখিত স্নিপেট একটি নমুনা অনুরোধ দেখায়:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=email%20profile

এই উদাহরণে একই অনুরোধ পাঠানোর জন্য curl কমান্ড দেখানো হয়েছে:

curl -d "client_id=client_id&scope=email%20profile" \
     https://oauth2.googleapis.com/device/code

ধাপ ২: অথরাইজেশন সার্ভারের উত্তর ম্যানেজ করা

অনুমোদন সার্ভার নিম্নলিখিত উত্তরগুলির মধ্যে একটি ফেরত দেবে:

সফল উত্তর

অনুরোধটি সঠিক হলে, আপনার উত্তরটি একটি JSON অবজেক্ট হবে যাতে নিম্নলিখিত প্রপার্টি থাকবে:

প্রপার্টি
device_code	অনুমোদনের অনুরোধ করা অ্যাপটি যে ডিভাইসে চলছে তা শনাক্ত করার জন্য Google একটি অনন্য মান নির্ধারণ করে। ব্যবহারকারী আরও উন্নত ইনপুট ক্ষমতা সহ অন্য ডিভাইস থেকে সেই ডিভাইসটি অনুমোদন করবেন। যেমন, কোনও ব্যবহারকারী টিভিতে চলা অ্যাপকে অনুমতি দিতে ল্যাপটপ বা মোবাইল ফোন ব্যবহার করতে পারেন। এই ক্ষেত্রে, device_code টিভিকে শনাক্ত করে। এই কোডটি অ্যাপ চালানো ডিভাইসটিকে নিরাপদে নির্ধারণ করতে দেয় যে ব্যবহারকারী অ্যাক্সেস দিয়েছেন নাকি অস্বীকার করেছেন।
expires_in	device_code এবং user_code কতক্ষণ বৈধ থাকবে, সেকেন্ডে সেই সময়সীমা। সেই সময়ের মধ্যে ব্যবহারকারী যদি অনুমোদনের প্রসেস সম্পূর্ণ না করেন এবং ব্যবহারকারীর সিদ্ধান্তের ব্যাপারে তথ্য পাওয়ার জন্য আপনার ডিভাইস যদি পোল না করে, তাহলে আপনাকে হয়ত ১ নম্বর ধাপ থেকে এই প্রসেস আবার শুরু করতে হবে।
interval	পোলিং অনুরোধের মধ্যে আপনার ডিভাইসকে কতক্ষণ অপেক্ষা করতে হবে, সেকেন্ডে সেই সময়। যেমন, ভ্যালু 5 হলে, আপনার ডিভাইসকে প্রতি পাঁচ সেকেন্ডে Google-এর অনুমোদন সার্ভারে পোলিং অনুরোধ পাঠাতে হবে। আরও বিবরণের জন্য ধাপ ৩ দেখুন।
user_code	একটি ছোট ও বড় হাতের অক্ষরের মধ্যে পার্থক্য করা হয় এমন ভ্যালু যা Google-এর কাছে সেই স্কোপ শনাক্ত করে যার অ্যাক্সেস অ্যাপ্লিকেশন অনুরোধ করছে। আপনার ইউজার ইন্টারফেস ব্যবহারকারীকে আরও ভাল ইনপুট ক্ষমতা সহ একটি পৃথক ডিভাইসে এই মানটি লিখতে নির্দেশ দেবে। Google তখন আপনার অ্যাপ্লিকেশনে অ্যাক্সেস দেওয়ার জন্য ব্যবহারকারীকে অনুরোধ করার সময় সঠিক সেট অফ স্কোপ দেখানোর জন্য মানটি ব্যবহার করে।
verification_url	ব্যবহারকারীকে আলাদা ডিভাইসে যে URL-এ নেভিগেট করতে হবে, যাতে তিনি user_code লিখতে পারেন এবং আপনার অ্যাপ্লিকেশনকে অ্যাক্সেস দিতে বা অ্যাক্সেস প্রত্যাখ্যান করতে পারেন। আপনার ইউজার ইন্টারফেসও এই ভ্যালু দেখাবে।

নিম্নলিখিত স্নিপেট একটি স্যাম্পেল উত্তর দেখায়:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

কোটা ছাড়িয়ে গেছে সংক্রান্ত উত্তর

আপনার ডিভাইস কোডের অনুরোধ যদি আপনার ক্লায়েন্ট আইডির সাথে যুক্ত কোটা অতিক্রম করে, তাহলে আপনি নিম্নলিখিত ত্রুটি সহ একটি 403 প্রতিক্রিয়া পাবেন:

{
  "error_code": "rate_limit_exceeded"
}

সেই ক্ষেত্রে, অনুরোধের হার কমাতে ব্যাকঅফ স্ট্র্যাটেজি ব্যবহার করুন।

ধাপ ৩: ব্যবহারকারীর কোড দেখানো

ধাপ ২-এ পাওয়া verification_url এবং user_code ব্যবহারকারীকে দেখান। উভয় ভ্যালুতে US-ASCII অক্ষর সেট থেকে যেকোনও প্রিন্ট করা যায় এমন অক্ষর থাকতে পারে। ব্যবহারকারীকে যে কন্টেন্ট দেখানো হবে তাতে যেন ব্যবহারকারীকে আলাদা ডিভাইসে verification_url-এ নেভিগেট করতে এবং user_code লিখতে নির্দেশ দেওয়া হয়।

নিম্নলিখিত নিয়মগুলি মাথায় রেখে আপনার ইউজার ইন্টারফেস (UI) ডিজাইন করুন:

• user_code
  • user_code অবশ্যই এমন একটি ফিল্ডে দেখাতে হবে যা ১৫টি 'W' সাইজের অক্ষর হ্যান্ডেল করতে পারে। অন্যভাবে বলতে গেলে, আপনি যদি কোড WWWWWWWWWWWWWWW সঠিকভাবে দেখাতে পারেন, তাহলে আপনার UI বৈধ এবং আপনার UI-তে user_code যেভাবে দেখানো হয় তা পরীক্ষা করার সময় আমরা সেই স্ট্রিং ভ্যালু ব্যবহার করার সাজেশন দিই।
  • user_code-এ ছোট ও বড় হাতের অক্ষরের মধ্যে পার্থক্য করা হয় এবং কোনওভাবেই এটি পরিবর্তন করা উচিত নয়, যেমন অক্ষরের কেস পরিবর্তন করা বা অন্যান্য ফর্ম্যাটিং অক্ষর যোগ করা।
• verification_url
  • যে স্পেসে আপনি verification_url দেখান সেটি ৪০টি অক্ষর দীর্ঘ URL স্ট্রিং হ্যান্ডেল করার জন্য যথেষ্ট চওড়া হতে হবে।
  • আপনি কোনওভাবেই verification_url পরিবর্তন করতে পারবেন না, তবে ঐচ্ছিকভাবে ডিসপ্লে থেকে স্কিম সরিয়ে দিতে পারবেন। আপনি যদি দেখানোর জন্য URL থেকে স্কিম (যেমন, https://) বাদ দেওয়ার পরিকল্পনা করেন, তাহলে আপনার অ্যাপ যাতে http এবং https ভেরিয়েন্ট দুটিই ম্যানেজ করতে পারে তা নিশ্চিত করুন।

সতর্কতা: এই দুটি ভ্যালুই পরিবর্তন হতে পারে এবং আপনার কোডে কোনও ভ্যালুই হার্ডকোড করা উচিত নয়। একইভাবে, verification_url থেকে স্কিমটি ঐচ্ছিকভাবে সরিয়ে দেওয়া ছাড়া অন্য কোনও উপায়ে আপনার ভ্যালু পরিবর্তন করা উচিত নয়।

ধাপ ৪: Google-এর অথরাইজেশন সার্ভার পোল করা

যেহেতু ব্যবহারকারী verification_url-এ নেভিগেট করতে এবং অ্যাক্সেস দিতে (বা অস্বীকার করতে) একটি আলাদা ডিভাইস ব্যবহার করবেন, তাই ব্যবহারকারী অ্যাক্সেসের অনুরোধের উত্তর দিলে অনুরোধকারী ডিভাইসটি অটোমেটিক বিজ্ঞপ্তি পায় না। সেই কারণে, ব্যবহারকারী কখন অনুরোধের উত্তর দিয়েছেন তা নির্ধারণ করতে, অনুরোধকারী ডিভাইসকে Google-এর অথরাইজেশন সার্ভার পোল করতে হবে।

অনুরোধকারী ডিভাইসকে পোলিং অনুরোধ পাঠানো চালিয়ে যেতে হবে যতক্ষণ না এটি কোনও উত্তর পায় যা ইঙ্গিত করে যে ব্যবহারকারী অ্যাক্সেসের অনুরোধে সাড়া দিয়েছেন বা যতক্ষণ না device_code এবং user_code ধাপ ২-এ প্রাপ্তির মেয়াদ শেষ হয়ে যায়। ২ নম্বর ধাপে দেখানো interval-এর মাধ্যমে অনুরোধের মধ্যে অপেক্ষা করার সময়, সেকেন্ডে, নির্দিষ্ট করা হয়।

পোল করার জন্য এন্ডপয়েন্টের URL হল https://oauth2.googleapis.com/token। পোলিং অনুরোধে নিম্নলিখিত প্যারামিটার থাকে:

প্যারামিটারগুলি
client_id	আপনার অ্যাপ্লিকেশনের জন্য ক্লায়েন্ট আইডি। আপনি এই ভ্যালু Cloud Console ক্লায়েন্ট পৃষ্ঠায় দেখতে পাবেন।
client_secret	প্রদত্ত client_id-এর জন্য ক্লায়েন্ট সিক্রেট। আপনি এই ভ্যালু Cloud Console ক্লায়েন্ট পৃষ্ঠায় দেখতে পাবেন।
device_code	ধাপ ২-এ অথরাইজেশন সার্ভার থেকে পাওয়া device_code।
grant_type	এই ভ্যালু urn:ietf:params:oauth:grant-type:device_code-এ সেট করুন।

উদাহরণ

নিম্নলিখিত স্নিপেট একটি নমুনা অনুরোধ দেখায়:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

এই উদাহরণে একই অনুরোধ পাঠানোর জন্য curl কমান্ড দেখানো হয়েছে:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

ধাপ ৫: ব্যবহারকারী অ্যাক্সেসের অনুরোধে উত্তর দেন

মনে রাখবেন: এই পর্যায়ে আপনার অ্যাপ্লিকেশনকে পূর্ববর্তী ধাপে বর্ণিত অনুমোদন সার্ভার পোলিং করা ছাড়া আর কিছু করতে হবে না।

নিচের ছবিতে এমন একটি পৃষ্ঠা দেখানো হয়েছে যা ব্যবহারকারীরা ধাপ ৩-এ আপনার দেখানো verification_url-এ নেভিগেট করার সময় দেখতে পান:

user_code লেখার পরে এবং আগে থেকে লগ-ইন করা না থাকলে, Google-এ লগ-ইন করার পরে, ব্যবহারকারী একটি সম্মতি স্ক্রিন দেখতে পান:

ধাপ ৬: পোলিং অনুরোধের উত্তর ম্যানেজ করা

Google-এর অথরাইজেশন সার্ভার প্রতিটি পোলিং অনুরোধের উত্তরে নিম্নলিখিতগুলির মধ্যে একটি উত্তর দেয়:

অ্যাক্সেস দেওয়া হয়েছে

ব্যবহারকারী ডিভাইসে অ্যাক্সেস দিলে (সম্মতি স্ক্রিনে Allow-এ ক্লিক করে), উত্তরে একটি অ্যাক্সেস টোকেন এবং একটি রিফ্রেশ টোকেন থাকে। টোকেন আপনার ডিভাইসকে ব্যবহারকারীর হয়ে Google API অ্যাক্সেস করার অনুমতি দেয়। (উত্তরে scope প্রপার্টি নির্ধারণ করে যে ডিভাইসটি কোন API অ্যাক্সেস করতে পারবে।)

এই ক্ষেত্রে, API রেসপন্সে নিম্নলিখিত ফিল্ডগুলি থাকে:

ফিল্ড
access_token	Google API অনুরোধ অনুমোদন করার জন্য আপনার অ্যাপ্লিকেশন যে টোকেন পাঠায়।
expires_in	সেকেন্ডে অ্যাক্সেস টোকেনের বাকি লাইফটাইম।
refresh_token	একটি টোকেন যা আপনি একটি নতুন অ্যাক্সেস টোকেন পেতে ব্যবহার করতে পারেন। ব্যবহারকারী অ্যাক্সেস প্রত্যাহার না করা বা রিফ্রেশ টোকেনের মেয়াদ শেষ না হওয়া পর্যন্ত রিফ্রেশ টোকেন বৈধ থাকে। মনে রাখবেন, ডিভাইসের জন্য রিফ্রেশ টোকেন সবসময় ফেরত দেওয়া হয়।
scope	access_token-এর মাধ্যমে মঞ্জুর করা অ্যাক্সেসের স্কোপ স্পেস-ডিলিমিটেড, ছোট ও বড় হাতের অক্ষরের মধ্যে পার্থক্য করা হয় এমন স্ট্রিংয়ের তালিকা হিসেবে প্রকাশ করা হয়।
token_type	ফেরত পাঠানো টোকেনের ধরন। এই ভ্যালু সবসময় Bearer হয়।

নিম্নলিখিত স্নিপেট একটি স্যাম্পেল উত্তর দেখায়:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

অ্যাক্সেস টোকেনের মেয়াদ সীমিত। আপনার অ্যাপ্লিকেশনকে যদি দীর্ঘ সময় ধরে কোনও API অ্যাক্সেস করতে হয়, তাহলে এটি নতুন অ্যাক্সেস টোকেন পাওয়ার জন্য রিফ্রেশ টোকেন ব্যবহার করতে পারে। আপনার অ্যাপ্লিকেশনের এই ধরনের অ্যাক্সেসের প্রয়োজন হলে, পরে ব্যবহার করার জন্য এটি রিফ্রেশ টোকেন স্টোর করে রাখবে।

অ্যাক্সেস দেওয়া হয়নি

ব্যবহারকারী ডিভাইসে অ্যাক্সেস দিতে অস্বীকার করলে, সার্ভার রেসপন্সে 403 HTTP রেসপন্স স্ট্যাটাস কোড (Forbidden) থাকে। রেসপন্সে নিম্নলিখিত সমস্যা থাকে:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

অনুমোদন বাকি আছে

ব্যবহারকারী এখনও অনুমোদনের ফ্লো সম্পূর্ণ না করে থাকলে, সার্ভার 428 HTTP রেসপন্স স্ট্যাটাস কোড (Precondition Required) দেখায়। রেসপন্সে নিম্নলিখিত সমস্যা থাকে:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

খুব ঘন ঘন পোলিং করা হচ্ছে

ডিভাইস খুব ঘন ঘন পোলিং অনুরোধ পাঠালে, সার্ভার 403 HTTP রেসপন্স স্ট্যাটাস কোড (Forbidden) পাঠায়। রেসপন্সে নিম্নলিখিত সমস্যা থাকে:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

অন্যান্য সমস্যা

পোলিং অনুরোধে কোনও প্রয়োজনীয় প্যারামিটার না থাকলে বা ভুল প্যারামিটার মান থাকলে, অনুমোদন সার্ভারও ত্রুটি দেখায়। এইসব অনুরোধে সাধারণত 400 (Bad Request) বা 401 (Unauthorized) HTTP রেসপন্স স্ট্যাটাস কোড থাকে। এইসব সমস্যার মধ্যে রয়েছে:

সমস্যা	HTTP স্ট্যাটাস কোড	বিবরণ
admin_policy_enforced	400	Google Workspace অ্যাডমিনিস্ট্রেটরের নীতির কারণে Google অ্যাকাউন্ট অনুরোধ করা এক বা একাধিক স্কোপ অনুমোদন করতে পারছে না। আপনার OAuth ক্লায়েন্ট আইডিতে অ্যাক্সেস স্পষ্টভাবে মঞ্জুর না করা পর্যন্ত, একজন অ্যাডমিনিস্ট্রেটর কীভাবে স্কোপে অ্যাক্সেস সীমাবদ্ধ করতে পারেন সে সম্পর্কে আরও তথ্যের জন্য, Google Workspace অ্যাডমিন সহায়তা নিবন্ধ কোন থার্ড-পার্টি এবং ইন্টার্নাল অ্যাপ Google Workspace ডেটা অ্যাক্সেস করে তা নিয়ন্ত্রণ করুন দেখুন।
invalid_client	401	OAuth ক্লায়েন্ট খুঁজে পাওয়া যায়নি। যেমন, client_id প্যারামিটারের ভ্যালু ভুল হলে এই সমস্যা হয়। OAuth ক্লায়েন্টের ধরন সঠিক নয়। নিশ্চিত করুন যে ক্লায়েন্ট আইডির জন্য অ্যাপ্লিকেশনের ধরন টিভি এবং সীমিত ইনপুট ডিভাইস হিসেবে সেট করা আছে।
invalid_grant	400	code প্যারামিটারের মান ভুল, এটি আগেই দাবি করা হয়েছে অথবা পার্স করা যাবে না।
unsupported_grant_type	400	grant_type প্যারামিটারের ভ্যালু সঠিক নয়।
org_internal	403	অনুরোধে থাকা OAuth ক্লায়েন্ট আইডি হল এমন একটি প্রোজেক্টের অংশ যা নির্দিষ্ট Google Cloud সংস্থায় Google অ্যাকাউন্টের অ্যাক্সেস সীমিত করে। আপনার OAuth অ্যাপ্লিকেশনের জন্য ব্যবহারকারীর ধরন কনফিগারেশন কনফার্ম করুন।

Google API কল করা হচ্ছে

আপনার অ্যাপ্লিকেশন অ্যাক্সেস টোকেন পাওয়ার পরে, আপনি টোকেন ব্যবহার করে কোনও নির্দিষ্ট ব্যবহারকারীর অ্যাকাউন্টের হয়ে Google API-এ কল করতে পারবেন, যদি API-এর জন্য প্রয়োজনীয় অ্যাক্সেসের স্কোপ মঞ্জুর করা হয়ে থাকে। এটি করতে, API-তে অনুরোধ করার সময় access_token কোয়েরি প্যারামিটার বা Authorization HTTP হেডার Bearer ভ্যালু যোগ করে অ্যাক্সেস টোকেন অন্তর্ভুক্ত করুন। সম্ভব হলে, HTTP হেডার ব্যবহার করা ভালো, কারণ কোয়েরি স্ট্রিং সার্ভার লগে দেখা যায়। বেশিরভাগ ক্ষেত্রে, আপনি Google API-তে কল সেট-আপ করার জন্য ক্লায়েন্ট লাইব্রেরি ব্যবহার করতে পারেন (যেমন, Drive Files API কল করার সময়)।

আপনি সব Google API ব্যবহার করে দেখতে এবং OAuth 2.0 Playground-এ সেগুলির স্কোপ দেখতে পারবেন।

HTTP GET-এর উদাহরণ

Authorization: Bearer HTTP হেডার ব্যবহার করে drive.files এন্ডপয়েন্টে (Drive Files API) কল করলে তা নিম্নলিখিত উদাহরণের মতো দেখতে হতে পারে। মনে রাখবেন যে আপনাকে নিজের অ্যাক্সেস টোকেন উল্লেখ করতে হবে:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

access_token কোয়েরি স্ট্রিং প্যারামিটার ব্যবহার করে যাচাই করা ব্যবহারকারীর জন্য একই API-তে কল করার পদ্ধতি এখানে দেওয়া হল:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curlটি উদাহরণ

আপনি curl কমান্ড-লাইন অ্যাপ্লিকেশনের মাধ্যমে এইসব কমান্ড পরীক্ষা করতে পারবেন। HTTP হেডার বিকল্প ব্যবহার করে এমন একটি উদাহরণ এখানে দেওয়া হল (পছন্দসই):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

অথবা, বিকল্প হিসেবে, কোয়েরি স্ট্রিং প্যারামিটার বিকল্প:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

অ্যাক্সেস টোকেন রিফ্রেশ করা হচ্ছে

অ্যাক্সেস টোকেনের মেয়াদ নির্দিষ্ট সময় অন্তর শেষ হয়ে যায় এবং সংশ্লিষ্ট API অনুরোধের জন্য ক্রেডেনশিয়াল ভুল হয়ে যায়। আপনি ব্যবহারকারীর কাছে অনুমতি না চেয়েই (এমনকি ব্যবহারকারী উপস্থিত না থাকলেও) অ্যাক্সেস টোকেন রিফ্রেশ করতে পারবেন, যদি আপনি টোকেনের সাথে যুক্ত স্কোপের অফলাইন অ্যাক্সেসের অনুরোধ করে থাকেন।

অ্যাক্সেস টোকেন রিফ্রেশ করতে, আপনার অ্যাপ্লিকেশন Google-এর অনুমোদন সার্ভারে (https://oauth2.googleapis.com/token) একটি HTTPS POST অনুরোধ পাঠায়, যার অনুরোধের বডিতে নিম্নলিখিত প্যারামিটার অন্তর্ভুক্ত থাকে:

নাম	ভ্যালু
client_id	API কনসোল থেকে পাওয়া ক্লায়েন্ট আইডি।
client_secret	ঐচ্ছিক API কনসোল থেকে পাওয়া ক্লায়েন্ট সিক্রেট।
grant_type	OAuth 2.0 স্পেসিফিকেশনে যেমন বলা হয়েছে, এই ফিল্ডের ভ্যালু refresh_token হিসেবে সেট করতে হবে।
refresh_token	অথরাইজেশন কোড এক্সচেঞ্জ থেকে রিফ্রেশ টোকেন ফেরত এসেছে।

নিম্নলিখিত স্নিপেট একটি নমুনা অনুরোধ দেখায়:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

ব্যবহারকারী যতক্ষণ না অ্যাপ্লিকেশনকে দেওয়া অ্যাক্সেস প্রত্যাহার করে নিচ্ছেন, ততক্ষণ টোকেন সার্ভার একটি JSON অবজেক্ট ফেরত পাঠায় যাতে নতুন অ্যাক্সেস টোকেন থাকে। নিম্নলিখিত স্নিপেট একটি নমুনা উত্তর দেখায়:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

মনে রাখবেন যে ইস্যু করা রিফ্রেশ টোকেনের সংখ্যার উপর সীমা আছে; একটি সীমা প্রতি ক্লায়েন্ট/ব্যবহারকারীর কম্বিনেশনের জন্য এবং অন্যটি সব ক্লায়েন্ট জুড়ে প্রতি ব্যবহারকারীর জন্য। আপনাকে দীর্ঘমেয়াদী স্টোরেজে রিফ্রেশ টোকেন সেভ করতে হবে এবং সেগুলি বৈধ থাকা পর্যন্ত ব্যবহার করা চালিয়ে যেতে হবে। আপনার অ্যাপ্লিকেশন অনেক বেশি রিফ্রেশ টোকেনের অনুরোধ করলে, এটি এই সীমার মধ্যে চলে যেতে পারে, সেক্ষেত্রে পুরনো রিফ্রেশ টোকেন কাজ করা বন্ধ করে দেবে।

টোকেন প্রত্যাহার

কিছু ক্ষেত্রে, কোনও ব্যবহারকারী কোনও অ্যাপ্লিকেশনকে দেওয়া অ্যাক্সেস প্রত্যাহার করতে চাইতে পারেন। ব্যবহারকারী অ্যাকাউন্ট সেটিংস-এ গিয়ে অ্যাক্সেস প্রত্যাহার করতে পারবেন। আরও তথ্যের জন্য আপনার অ্যাকাউন্টে অ্যাক্সেস আছে এমন থার্ড-পার্টি সাইট ও অ্যাপের সাইট বা অ্যাপ অ্যাক্সেস সরান সহায়তা ডকুমেন্ট দেখুন।

এছাড়াও, কোনও অ্যাপ্লিকেশনকে দেওয়া অ্যাক্সেস প্রোগ্রাম্যাটিক্যালি প্রত্যাহার করা সম্ভব। প্রোগ্রাম্যাটিক প্রত্যাহার সেইসব ক্ষেত্রে গুরুত্বপূর্ণ যেখানে কোনও ব্যবহারকারী আনসাবস্ক্রাইব করেন, কোনও অ্যাপ্লিকেশন সরিয়ে দেন অথবা কোনও অ্যাপের জন্য প্রয়োজনীয় API রিসোর্স উল্লেখযোগ্যভাবে পরিবর্তিত হয়। অন্যভাবে বলতে গেলে, অ্যাপ্লিকেশনকে আগে দেওয়া অনুমতি সরিয়ে দেওয়া হয়েছে কিনা তা নিশ্চিত করতে, সরানোর প্রসেসের অংশ হিসেবে API অনুরোধ অন্তর্ভুক্ত থাকতে পারে।

প্রোগ্রাম্যাটিক্যালি টোকেন তুলে নিতে, আপনার অ্যাপ্লিকেশন https://oauth2.googleapis.com/revoke-এ অনুরোধ করে এবং প্যারামিটার হিসেবে টোকেন অন্তর্ভুক্ত করে:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

টোকেনটি অ্যাক্সেস টোকেন বা রিফ্রেশ টোকেন হতে পারে। টোকেনটি যদি অ্যাক্সেস টোকেন হয় এবং সেটির সাথে সংশ্লিষ্ট রিফ্রেশ টোকেন থাকে, তাহলে রিফ্রেশ টোকেনও তুলে নেওয়া হবে।

প্রত্যাহার করার অনুরোধ সফলভাবে প্রসেস করা হলে, উত্তরের HTTP স্ট্যাটাস কোড হল 200। সমস্যার ক্ষেত্রে, HTTP স্ট্যাটাস কোড 400-এর সাথে একটি ত্রুটি কোড পাঠানো হয়।

গুরুত্বপূর্ণ পয়েন্ট: প্রত্যাহার করার ফলে কোনও প্রোজেক্টে আগে মঞ্জুর করা সমস্ত OAuth 2.0 স্কোপ সরিয়ে দেওয়া হয়, যার ফলে সেই প্রোজেক্টের অধীনে রেজিস্টার করা সমস্ত ক্লায়েন্টের জন্য ইস্যু করা যেকোনও অ্যাক্সেস বা রিফ্রেশ টোকেন বাতিল হয়ে যায়।

মনে রাখবেন: প্রত্যাহার করার অনুরোধ সফলভাবে প্রসেস হওয়ার পরে, প্রত্যাহার করার প্রক্রিয়া সম্পূর্ণ হতে কিছুটা সময় লাগতে পারে।

অনুমোদিত স্কোপ

ডিভাইসের জন্য OAuth 2.0 ফ্লো শুধুমাত্র নিম্নলিখিত স্কোপের জন্য কাজ করে:

OpenID Connect, Google Sign-In

• email
• openid
• profile

Drive API

• https://www.googleapis.com/auth/drive.appdata
• https://www.googleapis.com/auth/drive.file

YouTube API

• https://www.googleapis.com/auth/youtube
• https://www.googleapis.com/auth/youtube.readonly

সময়-ভিত্তিক অ্যাক্সেস

সময়-ভিত্তিক অ্যাক্সেস কোনও ব্যবহারকারীকে সীমিত সময়ের জন্য আপনার অ্যাপকে তার ডেটা অ্যাক্সেস করার অনুমতি দিতে দেয় যাতে কোনও অ্যাকশন সম্পূর্ণ করা যায়। সম্মতি ফ্লো চলাকালীন বেছে নেওয়া Google প্রোডাক্টে সময়-ভিত্তিক অ্যাক্সেস উপলভ্য, যা ব্যবহারকারীদের সীমিত সময়ের জন্য অ্যাক্সেস দেওয়ার বিকল্প প্রদান করে। যেমন, Data Portability API-এর মাধ্যমে একবার ডেটা ট্রান্সফার করা যায়।

কোনও ব্যবহারকারী আপনার অ্যাপ্লিকেশনকে সময়-ভিত্তিক অ্যাক্সেস দিলে, নির্দিষ্ট সময়সীমা শেষ হওয়ার পরে রিফ্রেশ টোকেনের মেয়াদ শেষ হয়ে যাবে। মনে রাখবেন, নির্দিষ্ট পরিস্থিতিতে রিফ্রেশ টোকেন আগেই বাতিল হয়ে যেতে পারে; বিস্তারিত জানতে এইসব পরিস্থিতি দেখুন। যাচাইকরণ কোড এক্সচেঞ্জ রেসপন্সে ফেরত আসা refresh_token_expires_in ফিল্ডটি এই ধরনের ক্ষেত্রে রিফ্রেশ টোকেনের মেয়াদ শেষ না হওয়া পর্যন্ত বাকি সময়কে দেখায়।

ক্রস-অ্যাকাউন্ট সুরক্ষা প্রয়োগ করা

আপনার ব্যবহারকারীদের অ্যাকাউন্ট সুরক্ষিত রাখতে আপনাকে একটি অতিরিক্ত পদক্ষেপ নিতে হবে, সেটি হল Google-এর ক্রস-অ্যাকাউন্ট সুরক্ষা পরিষেবা ব্যবহার করে ক্রস-অ্যাকাউন্ট সুরক্ষা প্রয়োগ করা। এই পরিষেবা আপনাকে নিরাপত্তা সংক্রান্ত ইভেন্টের বিজ্ঞপ্তিতে সাবস্ক্রাইব করতে দেয় যা আপনার অ্যাপ্লিকেশনকে ব্যবহারকারীর অ্যাকাউন্টে বড় পরিবর্তন সম্পর্কে তথ্য প্রদান করে। আপনি ইভেন্টে কীভাবে প্রতিক্রিয়া জানাবেন তার উপর নির্ভর করে অ্যাকশন নিতে এই তথ্য ব্যবহার করতে পারেন।

Google-এর ক্রস-অ্যাকাউন্ট সুরক্ষা পরিষেবার মাধ্যমে আপনার অ্যাপে পাঠানো ইভেন্টের ধরনের কিছু উদাহরণ হল:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

ক্রস-অ্যাকাউন্ট সুরক্ষা কীভাবে প্রয়োগ করবেন এবং উপলভ্য ইভেন্টের সম্পূর্ণ তালিকা সম্পর্কে আরও তথ্য পেতে ক্রস-অ্যাকাউন্ট সুরক্ষার মাধ্যমে ব্যবহারকারীর অ্যাকাউন্ট সুরক্ষিত করুন পৃষ্ঠা দেখুন।