OAuth 2.1 প্রয়োগ করার নির্দেশিকা

আপনার পরিষেবা অ্যাক্সেস করার জন্য Connected Apps Platform-কে কীভাবে নিরাপদে অনুমতি দেবেন তা এই নির্দেশিকায় উল্লেখ করা হয়েছে। কানেক্ট করা অ্যাপের MCP ইন্টিগ্রেশনের জন্য, আমরা OAuth 2.1 ব্যবহার করার জন্য সুপারিশ করি, যা ডেলিগেটেড অথরাইজেশনের জন্য ইন্ডাস্ট্রি স্ট্যান্ডার্ড, ব্যবহারকারীর ডেটার জন্য সর্বোচ্চ নিরাপত্তা এবং "এজেন্টিক" ফ্লোতে নির্ভরযোগ্যতা নিশ্চিত করতে প্রুফ কী ফর কোড এক্সচেঞ্জ (PKCE) সহ। কানেক্ট করা অ্যাপ প্ল্যাটফর্ম প্রুফ কী ফর কোড এক্সচেঞ্জ (PKCE) প্যারামিটার সহ অথরাইজেশন কোড গ্র্যান্ট টাইপ সমর্থন করে।

সব OAuth 2.1-এর জন্য PKCE বাধ্যতামূলক এবং OAuth2.0-এর জন্য ঐচ্ছিক।

অটোমেটিক ডিসকভারি চালু করতে এবং অনবোর্ডিং প্রসেস স্ট্রিমলাইন করতে, আপনার অথরাইজেশন সার্ভারকে অবশ্যই অথরাইজেশন সার্ভার মেটাডেটা এক্সটেনশন সাপোর্ট করতে হবে, যাকে OAuth ডিসকভারিও বলা হয়।

Gemini MCP কীভাবে কনফিগারেশন JSON ফেচ করে

Gemini MCP কনসোল নিম্নলিখিত URL থেকে আপনার কনফিগারেশন JSON আনার চেষ্টা করে, এই বিভাগে দেখানো ক্রম অনুসারে।

আপনার অথরাইজেশন সার্ভার URL আপনার ডোমেনের টপ লেভেলে থাকলে (যেমন, https://auth.example.com), Gemini আপনার ডোমেনে স্ট্যান্ডার্ড "well-known" ডিরেক্টরি যোগ করে এবং নিম্নলিখিত ক্রমে সার্ভার খোঁজে:

  1. https://auth.example.com/.well-known/oauth-authorization-server
  2. https://auth.example.com/.well-known/openid-configuration

আপনার অথরাইজেশন সার্ভার URL যদি আপনার ডোমেনের কোনও নির্দিষ্ট সাবডিরেক্টরি বা পাথের মধ্যে থাকে, যেমন, https://auth.example.com/realms/master, তাহলে Gemini একই "সুপরিচিত" পাথ সরাসরি সেই সাবডিরেক্টরিতে নিম্নলিখিত ক্রমে যোগ করে।

  1. .../realms/master/.well-known/oauth-authorization-server
  2. .../realms/master/.well-known/openid-configuration
  3. .../realms/master/.well-known/openid-configuration (নেস্টেড পাথ সাপোর্ট)

প্রয়োজনীয় JSON ক্ষমতা

আপনার মেটাডেটা উত্তরে নিম্নলিখিত ফিল্ডগুলি অবশ্যই থাকতে হবে। আবশ্যিক ফিল্ড পূরণ করা না হলে বা সঠিক ধরনের ডেটা না পাওয়া গেলে ইন্টিগ্রেশন করা যায় না।

authorization_endpoint
অবশ্যই সঠিক স্ট্রিং URL হতে হবে।
token_endpoint
অবশ্যই সঠিক স্ট্রিং URL হতে হবে।
response_types_supported
এতে code স্ট্রিং থাকতে হবে।
registration_endpoint

বর্তমানে, Play Console ডায়নামিক ক্লায়েন্টের উপর নির্ভর করে।

রেজিস্ট্রেশন (RFC 7591)। আপনার মেটাডেটাতে রেজিস্ট্রেশন এন্ডপয়েন্ট প্রদান করতে হবে অথবা Play Console UI-তে সরাসরি ক্লায়েন্ট আইডি/গোপন তথ্য ইনপুট করতে হবে।

আপনার অথরাইজেশন সার্ভার যদি ডায়নামিক ক্লায়েন্ট রেজিস্ট্রেশন (DCR) সাপোর্ট না করে, তাহলে ইন্টিগ্রেশন সম্পূর্ণ করতে আপনাকে Play Console UI-এর মধ্যে ম্যানুয়ালি ক্লায়েন্ট আইডি এবং ক্লায়েন্ট সিক্রেট ফিল্ড পূরণ করতে হবে।

আপনার ইমপ্লিমেন্টেশন যদি প্রুফ কী ফর কোড এক্সচেঞ্জ (PKCE) বা স্থায়ী সেশন সাপোর্ট করে, তাহলে আপনার ডিসকভারি JSON-এ প্রাসঙ্গিক ক্যাপাবিলিটি ফিল্ড (যেমন চ্যালেঞ্জ পদ্ধতি এবং গ্র্যান্ট টাইপ) অন্তর্ভুক্ত করতে হবে। এটি Gemini-র নিরাপত্তা ও কানেক্টিভিটি স্ট্যান্ডার্ডের সাথে মানানসই কিনা তা নিশ্চিত করতে সাহায্য করে। আপনি স্কোপ সমর্থন করলে, আপনাকে অবশ্যই scopes_supported ফিল্ড অন্তর্ভুক্ত করতে হবে।

কনফিগারেশনের উদাহরণ

নিম্নলিখিতটি হল একটি সঠিক JSON রেসপন্স যা আমাদের ক্লায়েন্টের প্রয়োজনীয়তা পূরণ করে।

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

আপনি PKCE অন্তর্ভুক্ত করলে, JSON ব্লকে কী অন্তর্ভুক্ত করা যেতে পারে তার একটি উদাহরণ নিম্নলিখিত স্নিপেটে দেখানো হয়েছে।

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

যেসব ক্ষেত্রে আপনি scopes_supported ফিল্ড অন্তর্ভুক্ত করেন, নিম্নলিখিত স্নিপেট JSON ব্লকে কী অন্তর্ভুক্ত করা যেতে পারে তার একটি উদাহরণ দেখায়।

"scopes_supported": ["mcp", "cart.order"],

অথরাইজেশন কোডের ফ্লো (সহজ ভার্সন)

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

  1. অনুমোদনের অনুরোধ: Google সারফেস নির্ধারণ করে যে আপনার ফাংশন কল করতে হবে, কিন্তু ব্যবহারকারী এখনও অনুমোদিত নন। চ্যাটবট ব্যবহারকারীর ব্রাউজারকে আপনার অনুমোদন এন্ডপয়েন্টে রিডাইরেক্ট করে (বা একটি লিঙ্ক দেখিয়ে) প্রক্রিয়াটি শুরু করে।

    এই অনুরোধে আপনার ক্লায়েন্ট আইডি (বা DCR-এর মাধ্যমে অটোমেটিক জেনারেট করা), Gemini রিডাইরেক্ট URI এবং গুরুত্বপূর্ণ PKCE প্যারামিটার (code_challenge এবং code_challenge_method) অন্তর্ভুক্ত থাকে।

    OAuth সেট-আপের জন্য নিম্নলিখিত URLগুলি অনুমোদিত তালিকায় যোগ করুন:

    • https://oauth-redirect.googleusercontent.com/r/*
    • https://oauth-redirect-sandbox.googleusercontent.com/r/*
    • https://oauth-redirect-test.googleusercontent.com/r/*
    • https://oauth-redirect.googleusercontent.com/a/*
    • https://oauth-redirect-sandbox.googleusercontent.com/a/*
    • https://oauth-redirect-test.googleusercontent.com/a/*
  2. ব্যবহারকারীর সম্মতি: আপনার অথরাইজেশন সার্ভার অনুরোধ যাচাই করে, ব্যবহারকারীকে যাচাই করে (লগ-ইন) এবং ব্যবহারকারীকে Google সারফেসকে তার ডেটা বা পরিষেবা অ্যাক্সেস করার অনুমতি দিতে বলে।

  3. কোড গ্র্যান্ট: ব্যবহারকারী সম্মতি দেওয়ার পরে, আপনার সার্ভার ব্যবহারকারীর ব্রাউজারকে আবার Gemini RedirectURI-তে রিডাইরেক্ট করে, URL-এ একটি সাময়িক অনুমোদন কোড যোগ করে।

  4. টোকেন এক্সচেঞ্জ: Gemini-র ব্যাকএন্ড আপনার টোকেন এন্ডপয়েন্টে POST অনুরোধ পাঠায়, অ্যাক্সেস টোকেনের জন্য অথরাইজেশন কোড এক্সচেঞ্জ করে।

  5. অ্যাক্সেস দেওয়া হয়েছে: আপনার টোকেন এন্ডপয়েন্ট কোড ও PKCE প্যারামিটার যাচাই করে, অ্যাক্সেস টোকেন ও ঐচ্ছিকভাবে রিফ্রেশ টোকেন ইস্যু করে এবং সেগুলি Gemini-তে ফেরত পাঠায়।

PKCE-এর মূল প্রয়োজনীয়তা

অননুমোদিতভাবে অথরাইজেশন কোড ইন্টারসেপ্ট করা আটকানোর জন্য PKCE সুরক্ষার একটি স্তর যোগ করে।

  • code_verifier: ফ্লো শুরু হওয়ার সময় Gemini-র মাধ্যমে জেনারেট করা ক্রিপ্টোগ্রাফিক্যালি র‍্যান্ডম স্ট্রিং। এটি ব্যক্তিগত রাখা হয়।
  • code_challenge: code_verifier-এর ট্রান্সফর্মেশন, সাধারণত SHA256 হ্যাশিং। এটি সর্বজনীনভাবে পাঠানো হয়, যেমনটি অথরাইজেশন কোডের ফ্লোয়ের ১ নম্বর ধাপে বর্ণনা করা হয়েছে।
  • যাচাইকরণ: আপনার টোকেন এন্ডপয়েন্ট (অথরাইজেশন কোডের ফ্লোয়ের ৪ নম্বর ধাপে বর্ণনা করা হয়েছে) অবশ্যই যাচাই করবে যে প্রাপ্ত code_verifier, ট্রান্সফর্ম করার পরে, আসল code_challenge-এর সাথে ম্যাচ করছে।

ডিবাগিং

লিঙ্ক করার সময় হওয়া সমস্যার বিস্তারিত তথ্য Logs Explorer-এ উপলভ্য আছে, সমস্যা চালু ও দেখতে আপনার Google Console প্রোজেক্টে অ্যাকাউন্ট লিঙ্ক করার সময় হওয়া সমস্যা মনিটর করুন লিঙ্কে দেওয়া নির্দেশাবলী অনুসরণ করুন।

Google অ্যাকাউন্ট লিঙ্ক করার কনফিগারেশন সংক্রান্ত প্রয়োজনীয়তা

Google অ্যাকাউন্ট লিঙ্ক করার কনফিগারেশন সম্পর্কে তথ্য পেতে নিম্নলিখিত API নির্দেশিকা পড়ুন।

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

কনফিগারেশন ফিল্ড

বিবরণ

ডেভেলপারের দায়িত্ব

ক্লায়েন্ট আইডি ও সিক্রেট

আপনার অথরাইজেশন সার্ভার, কানেক্ট করা অ্যাপ প্ল্যাটফর্মের জন্য বিশেষভাবে যে অনন্য ক্রেডেনশিয়াল তৈরি করে। ক্লায়েন্ট সিক্রেট হল ক্লায়েন্ট আইডির সাথে যুক্ত সুরক্ষিত ক্রেডেনশিয়াল (পাসওয়ার্ড)।

মনে রাখবেন: ডেভেলপার ক্লায়েন্ট আইডি ইস্যু করলে, তাকে অবশ্যই এটি প্রদান করতে হবে। Google যদি ক্লায়েন্ট আইডি ইস্যু করে, তাহলে ডেভেলপারকে হয়ত একটি সিক্রেট রেজিস্টার বা যাচাই করতে হবে।

সব অনুমোদনের অনুরোধে প্ল্যাটফর্মের দেওয়া আইডি ব্যবহার করুন।

অনুমোদনের এন্ডপয়েন্ট

ব্যবহারকারীদের যাচাইকরণ ও সম্মতি প্রদানের জন্য রিডাইরেক্ট করার URL

এন্ডপয়েন্ট হোস্ট করুন—যেমন, https://yourdomain.com/oauth/authorize

টোকেন এন্ডপয়েন্ট

অ্যাক্সেস/রিফ্রেশ টোকেনের জন্য অনুমোদন কোড এক্সচেঞ্জ করতে এবং মেয়াদ শেষ হয়ে যাওয়া টোকেন রিফ্রেশ করতে ব্যাকএন্ড এন্ডপয়েন্ট।

এই এন্ডপয়েন্ট হোস্ট করুন—যেমন, https://yourdomain.com/oauth/token

প্রত্যাহার করার এন্ডপয়েন্ট
ঐচ্ছিক

ব্যবহারকারী ডিসকানেক্ট করলে, টোকেন বাতিল করার জন্য আপনার সিস্টেমকে বিজ্ঞপ্তি পাঠানোর URL।

কোনও ব্যবহারকারী কানেক্ট করা অ্যাপ প্ল্যাটফর্মের মধ্যে থেকে আপনার ইন্টিগ্রেশন আনলিঙ্ক বা ডিসকানেক্ট করলে, আমরা অ্যাক্সেস বা রিফ্রেশ টোকেন সহ /revoke এন্ডপয়েন্টে একটি POST অনুরোধ করব।

আরও তথ্যের জন্য অ্যাকাউন্ট আনলিঙ্ক করা দেখুন।

এন্ডপয়েন্ট হোস্ট করুন—যেমন, https://yourdomain.com/oauth/revoke

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

রিডাইরেক্ট URI

প্ল্যাটফর্মের মাধ্যমে প্রদান করা নির্দিষ্ট কলব্যাক URL যেখানে সম্মতি পাওয়ার পরে অথরাইজেশন সার্ভার কোডটি ফেরত পাঠায়।

প্ল্যাটফর্ম থেকে শুধুমাত্র অফিসিয়াল, রেজিস্টার করা রিডাইরেক্ট URI গ্রহণ করার জন্য আপনার অথরাইজেশন সার্ভার কনফিগার করুন।

রিফ্রেশ

grant_type=refresh_token থাকা /token

এমন একটি পদ্ধতি যা বর্তমান অ্যাক্সেস টোকেনের মেয়াদ শেষ হয়ে গেলে Connected Apps Platform-কে নতুন অ্যাক্সেস টোকেন পেতে সাহায্য করে। এর ফলে, ব্যবহারকারীকে বারবার লগ-ইন করতে হয় না এবং ইন্টিগ্রেশন নির্বিঘ্নে কানেক্টেড থাকে।

আগে থেকে থাকা অ্যাক্সেস টোকেনের মেয়াদ শেষ হয়ে গেলে, কানেক্ট করা অ্যাপ প্ল্যাটফর্ম অটোমেটিক আপনার /token এন্ডপয়েন্টে POST অনুরোধ করবে। অনুরোধের পেলোডে grant_type=refresh_token-এর সাথে আপনার সার্ভার থেকে আগে ইস্যু করা রিফ্রেশ টোকেনও থাকবে।

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

উত্তরের ধরন

অথরাইজেশন কোডের ফ্লো কাজ করার জন্য এটি CODE-এ কনফিগার করতে হবে।

স্কোপ

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

আপনাকে ডিফল্ট স্কোপের (যেমন, openid, profile, email) একটি তালিকা প্রদান করতে হবে যা ফ্লো শুরু করার সময় Connected Apps Platform-এর অনুরোধ করা উচিত।

অনুরোধ করা স্কোপ যতটা সম্ভব কম হওয়া উচিত (ন্যূনতম বিশেষাধিকারের নীতি) তবে আপনার MCP ইন্টিগ্রেশন যে ক্রিটিকাল ইউজার জার্নি (CUJ) সমর্থন করে তার জন্য সম্পূর্ণ পর্যাপ্ত হতে হবে।

UI অ্যাসেট: লোগো

অ্যাকাউন্ট লিঙ্ক করা ও সম্মতি সংক্রান্ত স্ক্রিনে দেখানোর জন্য ডেভেলপারের লোগো।

এটি অবশ্যই বৃত্তাকার আকৃতির একটি বর্গাকার ভেক্টর ইমেজ (SVG) হতে হবে এবং কমপক্ষে ৫০০ x ৫০০ পিক্সেল হতে হবে। যেমন, https://[partner-domain]/assets/logo.svg বা র SVG ফাইল দেখুন।

নেটিভ অ্যাপ লিঙ্কিং (অ্যাপ ফ্লিপ)

আপনার নেটিভ Android বা iOS অ্যাপ্লিকেশন থেকে সরাসরি অ্যাকাউন্ট লিঙ্ক করার জন্য স্ট্যান্ডার্ড ওয়েবভিউয়ের উপর নির্ভর করাকে একেবারেই উৎসাহিত করা হয় না। পরিবর্তে, ব্যবহারকারীর নির্বিঘ্ন অভিজ্ঞতার জন্য অ্যাপ ফ্লিপ প্রয়োগ করার জন্য বিশেষভাবে সাজেস্ট করা হয়।

আরও তথ্যের জন্য OAuth-ভিত্তিক অ্যাপ ফ্লিপের মাধ্যমে Google অ্যাকাউন্ট লিঙ্ক করা দেখুন।

Play Store এবং App Store যাচাইকরণ সম্পূর্ণ করুন এবং একটি নিরাপদ, অ্যাপ-টু-অ্যাপ অথরাইজেশন ফ্লিপ নিশ্চিত করতে সরাসরি আপনার নেটিভ অ্যাপ্লিকেশনে Google-এর রিডাইরেক্ট URI এম্বেড করুন।

টোকেনের লাইফটাইম

(ঐচ্ছিক) রিফ্রেশ করার আগে অ্যাক্সেস টোকেন যত সময় পর্যন্ত বৈধ থাকে। GAL-এ টাইমআউট নীতি কনফিগার করার জন্য উপযোগী।

নিরাপত্তা সংক্রান্ত প্রয়োজনের উপর নির্ভর করে মেয়াদ শেষ হওয়ার সাধারণ সময়সীমা মিনিট, ঘণ্টা, দিন হতে পারে—যেমন, 30 days)

ইন্টিগ্রেশন সংক্রান্ত সাধারণ সমস্যা

ইন্টিগ্রেশন প্রসেসে প্রযোজ্য সাধারণ সমস্যা ও সম্ভাব্য সমাধানের তালিকা এখানে দেওয়া হল।

  • "কোড" গ্র্যান্ট নেই: Gemini প্ল্যাটফর্মের অটোমেটিক সিস্টেম স্পষ্টভাবে "কোড" ভ্যালুর জন্য response_types_supported চেক করে।
  • রেজিস্ট্রেশন এন্ডপয়েন্ট নেই: আপনার সার্ভার ক্লায়েন্ট আইডি মেটাডেটা ডকুমেন্ট সমর্থন করলেও, Gemini অ্যাপের (আপনার সার্ভারের সাথে কানেক্ট করা OAuth ক্লায়েন্ট হিসেবে কাজ করে) বর্তমানে ডিসকভারি JSON-এ একটি ডেডিকেটেড registration_endpoint প্রয়োজন।
  • Non-200 error: Gemini-র অটোমেটেড মেটাডেটা ডিসকভারি মেকানিজম আপনার সুপরিচিত URL-এ হিট করে 404 বা 500 পেলে, এটি অন্য URL অনুমান করার চেষ্টা করবে না। ডিসকভারি URL যাতে সর্বজনীনভাবে অ্যাক্সেস করা যায় তা নিশ্চিত করুন।