OAuth 2.1 uygulama kılavuzu

Bu kılavuzda, Bağlı Uygulamalar Platformu'na hizmetlerinize erişmesi için güvenli bir şekilde nasıl yetki vereceğiniz açıklanmaktadır. Bağlı uygulamalar MCP entegrasyonları için, kullanıcı verilerinin en yüksek düzeyde güvenliğini ve "aracı" akışlarında güvenilirliği sağlamak amacıyla, yetkilendirme için endüstri standardı olan OAuth 2.1'i Kod Değişimi İçin Doğrulama Anahtarı (PKCE) ile kullanmanızı önemle tavsiye ederiz. Bağlı Uygulamalar Platformu, Kod Değişimi İçin Doğrulama Anahtarı (PKCE) parametreleriyle yetkilendirme kodu yetkilendirme türünü destekler.

PKCE, tüm OAuth 2.1 için zorunlu, OAuth 2.0 için isteğe bağlıdır.

Otomatik keşfi etkinleştirmek ve oryantasyon sürecini kolaylaştırmak için yetkilendirme sunucunuzun, OAuth Keşfi olarak da adlandırılan Yetkilendirme Sunucusu Meta Verileri uzantısını desteklemesi gerekir.

Gemini MCP, yapılandırma JSON'unu nasıl getirir?

Gemini MCP konsolu, yapılandırma JSON'unuzu aşağıdaki URL'lerden bu bölümde gösterilen sırayla getirmeye çalışır.

Yetkilendirme sunucusu URL'niz alanınızın en üst düzeyindeyse (örneğin, https://auth.example.com) Gemini, alanınıza standart "well-known" dizinleri ekler ve sunucuyu aşağıdaki sırayla arar:

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

Yetkilendirme sunucunuzun URL'si, alanınızdaki belirli bir alt dizinde veya yolda (ör. https://auth.example.com/realms/master) bulunuyorsa Gemini, aynı "well-known" yollarını doğrudan bu alt dizine aşağıdaki sırayla ekler.

  1. .../realms/master/.well-known/oauth-authorization-server
  2. .../realms/master/.well-known/openid-configuration
  3. .../realms/master/.well-known/openid-configuration (iç içe yerleştirilmiş yol desteği)

Gerekli JSON özellikleri

Meta veri yanıtınız aşağıdaki alanları içermelidir. Zorunlu alanlar eksikse veya geçerli türler bulunamazsa entegrasyon başarısız olur.

authorization_endpoint
Geçerli bir dize URL'si olmalıdır.
token_endpoint
Geçerli bir dize URL'si olmalıdır.
response_types_supported
code dizesini içermelidir.
registration_endpoint

Google Play Console şu anda Dynamic Client'ı kullanmaktadır.

Registration (RFC 7591). Meta verilerinizde bir kayıt uç noktası sağlamanız veya istemci kimliğini/gizli anahtarını doğrudan Google Play Console kullanıcı arayüzüne girmeniz gerekir.

Yetkilendirme sunucunuz Dynamic Client Registration'ı (DCR) desteklemiyorsa entegrasyonu tamamlamak için Google Play Console kullanıcı arayüzündeki İstemci Kimliği ve İstemci Gizli Anahtarı alanlarını manuel olarak uygulamanız ve doldurmanız gerekir.

Uygulamanız Kod Değişimi İçin Doğrulama Anahtarı'nı (PKCE) veya kalıcı oturumları destekliyorsa keşif JSON'unuza ilgili özellik alanlarını (ör. Challenge Methods ve Yetkilendirme Türleri) eklemeniz gerekir. Bu sayede Gemini'ın güvenlik ve bağlantı standartlarıyla uyumluluk sağlanır. Kapsamı destekliyorsanız scopes_supported alanını eklemeniz gerekir.

Örnek yapılandırma

Aşağıda, müşterimizin şartlarını karşılayan geçerli bir JSON yanıtı verilmiştir.

{
  "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'yi dahil ettiğiniz durumlarda, JSON bloğuna nelerin dahil edilebileceğini gösteren bir örneği aşağıdaki snippet'te bulabilirsiniz.

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

scopes_supported alanını eklediğiniz durumlarda, aşağıdaki snippet JSON bloğuna nelerin dahil edilebileceğini gösteren bir örnek sunar.

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

Yetkilendirme kodu akışı (basitleştirilmiş sürüm)

Aşağıdaki adımlarda standart yetkilendirme kodu akışı açıklanmaktadır. Bu sıra, Bağlı Uygulamalar Platformu'nun kullanıcı adına işlem yapmak için gerekli erişim jetonlarını sunucunuzdan güvenli bir şekilde nasıl aldığını tam olarak gösterir.

  1. Yetkilendirme isteği: Google platformu, işlevinizi çağırması gerektiğini belirler ancak kullanıcı henüz yetkilendirilmemiştir. Chatbot, kullanıcının tarayıcısını yetkilendirme uç noktanıza yönlendirerek (veya bir bağlantı göstererek) akışı başlatır.

    Bu istek, istemci kimliğinizi (veya DCR ile otomatik olarak oluşturulan kimliği), Gemini yönlendirme URI'sini ve kritik PKCE parametrelerini (code_challenge ve code_challenge_method) içerir.

    OAuth kurulumu için aşağıdaki URL'leri izin verilenler listesine ekleyin:

    • 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. Kullanıcı izni: Yetkilendirme sunucunuz isteği doğrular, kullanıcının kimliğini doğrular (giriş) ve kullanıcıdan Google yüzeyinin verilerine veya hizmetine erişmesine izin vermesini ister.

  3. Kod izni: Kullanıcı izin verdikten sonra sunucunuz, kullanıcının tarayıcısını Gemini RedirectURI'ya yönlendirir ve URL'ye geçici bir yetkilendirme kodu ekler.

  4. Jeton değişimi: Gemini'ın arka ucu, jeton uç noktanıza bir POST isteği göndererek yetkilendirme kodunu erişim jetonuyla değiştirir.

  5. Erişim izni verildi: Jeton uç noktanız kodu ve PKCE parametrelerini doğrular, bir erişim jetonu ve isteğe bağlı olarak bir yenileme jetonu oluşturur ve bunları Gemini'a döndürür.

Temel PKCE şartları

PKCE, yetkilendirme kodlarının yetkisiz olarak ele geçirilmesini önlemek için bir güvenlik katmanı ekler.

  • code_verifier: Akışın başında Gemini tarafından oluşturulan, kriptografik olarak rastgele bir dize. Bu bilgi gizli tutulur.
  • code_challenge: code_verifier değerinin dönüşümü (genellikle SHA256 karma oluşturma işlemi). Bu, yetkilendirme kodu akışının 1. adımında açıklandığı gibi herkese açık olarak gönderilir.
  • Doğrulama: Jeton uç noktanız (yetkilendirme kodu akışının 4. adımında açıklanmıştır), alınan code_verifier değerinin dönüştürüldüğünde orijinal code_challenge ile eşleştiğini doğrulamalıdır.

Hata ayıklama

Bağlantı hatasıyla ilgili ayrıntılı bilgileri Günlük Gezgini'nde bulabilirsiniz. Hataları etkinleştirmek ve görüntülemek için Google Console projenizde hesap bağlama hatalarını izleme başlıklı makaledeki talimatları uygulayın.

Google Hesabı bağlantısı yapılandırma koşulları

Google Hesabı bağlantısı yapılandırması hakkında bilgi edinmek için aşağıdaki API kılavuzunu okuyun.

OAuth entegrasyonunuzu başarıyla kaydetmek için yetkilendirme sunucunuzla ilgili belirli ayrıntıları yapılandırmanız gerekir. Aşağıdaki uç noktaları, kimlik bilgilerini ve öğeleri hazırladığınızdan emin olun.

Yapılandırma Alanı

Açıklama

Geliştirici Sorumluluğu

İstemci Kimliği ve Gizli Anahtar

Yetkilendirme sunucunuzun Bağlı Uygulamalar Platformu için özel olarak oluşturduğu benzersiz kimlik bilgileri. İstemci gizli anahtarı, istemci kimliğiyle ilişkili güvenlik amaçlı kimlik bilgisidir (şifre).

Not: İstemci kimliğini geliştirici oluşturduysa bu bilgiyi geliştiricinin sağlaması gerekir. İstemci kimliği Google tarafından verildiyse geliştiricinin bir gizli anahtar kaydetmesi veya doğrulaması gerekebilir.

Tüm yetkilendirme isteklerinde platform tarafından sağlanan kimliği kullanın.

Yetkilendirme uç noktası

Kullanıcıların kimlik doğrulaması ve izin vermesi için yönlendirileceği URL

Uç noktayı barındırın (ör. https://yourdomain.com/oauth/authorize)

Token Endpoint (Jeton Uç Noktası)

Yetkilendirme kodlarını erişim/yenileme jetonlarıyla değiştirmek ve süresi dolmuş jetonları yenilemek için kullanılan arka uç uç noktası.

Bu uç noktayı barındırın (ör. https://alanadiniz.com/oauth/token)

İptal Uç Noktası
İsteğe bağlı

Bir kullanıcı bağlantıyı kestiğinde sisteminize bir jetonu geçersiz kılmasını bildiren URL.

Bir kullanıcı, Bağlı Uygulamalar Platformu'ndan entegrasyonunuzun bağlantısını kaldırdığında veya bağlantısını kestiğinde, erişim ya da yenileme jetonunu içeren /revoke uç noktasına bir POST isteği göndeririz.

Daha fazla bilgi için Hesapların bağlantısını kaldırma bölümüne bakın.

Uç noktayı barındırın (ör. https://yourdomain.com/oauth/revoke)

Sunucunuz, sağlanan jetonu kalıcı olarak geçersiz kılarak bu isteği işlemelidir. Bu sayede, Bağlı Uygulamalar Platformu'nun bu jetonu kullanmaya yönelik sonraki girişimleri başarısız olur ve bağlantı kesildikten sonra kullanıcının verileri güvende kalır.

Yönlendirme URI'si

Yetkilendirme sunucusunun, izin verildikten sonra kodu geri gönderdiği, platform tarafından sağlanan özel geri çağırma URL'si.

Yetkilendirme sunucunuzu, platformdan yalnızca resmi ve kayıtlı yönlendirme URI'sini kabul edecek şekilde yapılandırın.

Yenileme

grant_type=refresh_token ile /token

Bağlı Uygulamalar Platformu'nun, mevcut erişim jetonunun süresi dolduğunda yeni bir erişim jetonu almasını sağlayan bir mekanizmadır. Bu sayede, kullanıcının tekrar tekrar giriş yapmasına gerek kalmadan entegrasyonun sorunsuz bir şekilde bağlı kalması sağlanır.

Mevcut bir erişim jetonunun süresi dolduğunda Bağlı Uygulamalar Platformu, /token uç noktanıza otomatik olarak bir POST isteği gönderir. İstek yükü, sunucunuzun daha önce verdiği yenileme jetonuyla birlikte grant_type=refresh_token değerini içerir.

Sunucunuz, sağlanan yenileme jetonunu doğrulamalı ve JSON yanıtında yeni bir erişim jetonu döndürmelidir. Ayrıca, Kalıcı Bağlantı'yı uygulamak için bu değişim sırasında yenileme jetonunu döndürmekten kaçınmanız gerekir. Yeni bir yenileme jetonu vermek yerine, JSON yanıtında aynı yenileme jetonunu döndürün ve arka ucunuzda geçerlilik bitiş tarihini uzatın.

Yanıt Türü

Yetkilendirme kodu akışını desteklemek için bu değer CODE olarak yapılandırılmalıdır.

Kapsamlar

Jetonun ne yapmaya yetkili olduğunu tanımlayan belirli izinler ve erişim düzeyleri. Bunlar, yapılandırmanızda önceden tanımlanmalıdır. Böylece Google, ilk yetkilendirme el sıkışması sırasında bunları isteyebilir.

Bağlı Uygulamalar Platformu'nun akışı başlatırken istemesi gereken varsayılan kapsamların (ör. openid, profile, email) listesini sağlamanız gerekir.

İstenen kapsamlar mümkün olduğunca daraltılmalı (en az ayrıcalık ilkesi) ancak MCP entegrasyonunuzun desteklediği kritik kullanıcı yolculukları (CUJ'ler) için tamamen yeterli olmalıdır.

Kullanıcı arayüzü öğeleri: Logo

Hesap bağlama ve kullanıcı rızası ekranlarında gösterilecek geliştirici logosu.

Dairesel görünüme sahip ve en az 500 x 500 piksel boyutunda kare bir vektörel görüntü (SVG) olmalıdır. Örneğin, https://[partner-domain]/assets/logo.svg veya ham SVG dosyasına bakın.

Yerel uygulama bağlama (App Flip)

Doğrudan yerel Android veya iOS uygulamalarınızdan hesap bağlamayı desteklemek için standart web görünümlerini kullanmanız kesinlikle önerilmez. Bunun yerine, sorunsuz bir kullanıcı deneyimi için Uygulama Bağlama'yı uygulamanız önemle tavsiye edilir.

Daha fazla bilgi için OAuth tabanlı Uygulama Bağlama ile Google Hesabı Bağlantısı başlıklı makaleyi inceleyin.

Google Play Store ve uygulama mağazası doğrulamasını tamamlayın ve Google'ın yönlendirme URI'larını doğrudan yerel uygulamalarınıza yerleştirerek uygulamalar arası yetkilendirme geçişinin güvenli bir şekilde yapılmasını sağlayın.

Jeton Geçerlilik Süresi

(İsteğe bağlı) Yenileme gerekmeden önce erişim jetonunun geçerli olduğu süre. GAL'de zaman aşımı politikalarını yapılandırmak için kullanışlıdır.

Yaygın geçerlilik süreleri, güvenlik ihtiyaçlarına bağlı olarak dakikalar, saatler, günler arasında değişir (ör. 30 days).

Sık karşılaşılan entegrasyon hataları

Entegrasyon süreciyle ilgili sık karşılaşılan hataların ve olası çözümlerin listesini aşağıda bulabilirsiniz.

  • "code" izni eksik: Gemini platformunun otomatik sistemi, response_types_supported değerinin "code" olup olmadığını açıkça kontrol eder.
  • Kayıt uç noktası eksik: Sunucunuz istemci kimliği meta veri belgelerini desteklese bile Gemini uygulaması (sunucunuza bağlanan OAuth istemcisi olarak hareket eder) şu anda keşif JSON'unda özel bir registration_endpoint bulunmasını gerektirir.
  • 200 dışı hata: Gemini'ın otomatik meta veri keşif mekanizması, bilinen URL'nize ulaştığında 404 veya 500 hatası alırsa diğer URL'leri tahmin etmeye çalışmaz. Lütfen Discovery URL'sinin herkese açık olduğundan emin olun.