OAuth ile Google Hesabı Bağlama

Hesaplar, endüstri standardı OAuth 2.0 yetkilendirme kodu akışı kullanılarak bağlanır.

Aracılar için OAuth 2.1 ve PKCE

Durum bilgisiz yapay zeka aracıları ve çok modlu ardışık düzenler için OAuth 2.1 zorunlu kılınması önerilir.

  • PKCE (Proof Key for Code Exchange): Yetkilendirme kodu akışını güvenli hale getirmek ve araya girme saldırılarını önlemek için kullanılmalıdır.
  • Örtülü Akış Yok: Örtülü akış, URL'deki erişim jetonlarını kullanıma sunar. Bu durum, aracı ortamları için güvenlik riski oluşturur.

Hizmetiniz, OAuth 2.0/2.1 uyumlu yetkilendirme ve jeton değişimi uç noktalarını desteklemelidir.

Create the project

To create your project to use account linking:

  1. Go to the Google API Console.
  2. Click Create project.
  3. Enter a name or accept the generated suggestion.
  4. Confirm or edit any remaining fields.
  5. Click Create.

To view your project ID:

  1. Go to the Google API Console.
  2. Find your project in the table on the landing page. The project ID appears in the ID column.

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

  1. Open the OAuth consent screen page of the Google APIs console.
  2. If prompted, select the project you just created.

  3. On the "OAuth consent screen" page, fill out the form and click the “Save” button.

    Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

    Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

    Support email: For users to contact you with questions about their consent.

    Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

    Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

    Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

    Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

    Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

    Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery

  4. Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

OAuth sunucunuzu uygulama

Yetkilendirme kodu akışının OAuth 2.0 sunucu uygulaması, hizmetinizin HTTPS üzerinden kullanılabilir hale getirdiği iki uç noktadan oluşur. İlk uç nokta, yetkilendirme uç noktasıdır. Bu uç nokta, veri erişimi için kullanıcılardan izin bulmaktan veya izin almaktan sorumludur. Yetkilendirme uç noktası, henüz oturum açmamış kullanıcılarınıza bir oturum açma kullanıcı arayüzü sunar ve istenen erişim için izni kaydeder. İkinci uç nokta, jeton değişimi uç noktasıdır. Bu uç nokta, kullanıcıya hizmetinize erişme yetkisi veren jeton adı verilen şifrelenmiş dizeleri almak için kullanılır.

Bir Google uygulamasının hizmetinizin API'lerinden birini çağırması gerektiğinde Google, kullanıcılarınızdan bu API'leri onlar adına çağırmak için izin almak üzere bu uç noktaları birlikte kullanır.

Google Hesabı bağlantısı: OAuth Yetkilendirme Kodu Akışı

Aşağıdaki sıra diyagramı, Kullanıcı, Google ve hizmetinizin uç noktaları arasındaki etkileşimleri ayrıntılı olarak açıklar.

Kullanıcı Google Uygulaması / Tarayıcı Google Sunucusu Kimlik Doğrulama Uç Noktanız Token Uç Noktanız 1. Kullanıcı, bağlantı oluşturma işlemini başlatır 2. Yetkilendirme uç noktasına yönlendirme (GET) client_id, redirect_uri, state, scope 3. Oturum Açma ve İzin Ekranını Gösterme 4. Kullanıcı Kimliğini Doğrular ve İzin Verir 5. Google'a yönlendirme (GET) code, state 6. Yönlendirmeyi işleme ve kodu/durumu iletme 7. Token Exchange (POST) grant_type=authorization_code, code 8. Jetonları döndürme (200 OK) access_token, refresh_token 9. Kullanıcı jetonlarını saklama � �10. Kullanıcı kaynaklarına erişme
Şekil 1. Google Hesabı bağlantısı için OAuth 2.0 Yetkilendirme Kodu akışındaki etkinlik sırası.

Roller ve sorumluluklar

Aşağıdaki tabloda, Google Hesap Bağlama (GAL) OAuth akışındaki aktörlerin rolleri ve sorumlulukları tanımlanmaktadır. GAL'de Google'ın OAuth istemcisi, hizmetinizin ise kimlik/hizmet sağlayıcı olarak hareket ettiğini unutmayın.

İşlemi gerçekleştiren / Bileşen GAL Rolü Sorumluluklar
Google Uygulaması / Sunucusu OAuth İstemcisi Akışı başlatır, yetkilendirme kodunu alır, jetonlarla değiştirir ve hizmetinizin API'lerine erişmek için bunları güvenli bir şekilde depolar.
Yetkilendirme uç noktanız Yetkilendirme Sunucusu Kullanıcılarınızın kimliğini doğrular ve verilerine erişim iznini Google ile paylaşmak için kullanıcılarınızın iznini alır.
Jeton Değişimi Uç Noktanız Yetkilendirme Sunucusu Yetkilendirme kodlarını ve yenileme jetonlarını doğrular ve Google sunucusuna erişim jetonları verir.
Google Yönlendirme URI'si Geri Arama Uç Noktası Kullanıcı yönlendirmesini, yetkilendirme hizmetinizden code ve state değerleriyle birlikte alır.

Google tarafından başlatılan bir OAuth 2.0 yetkilendirme kodu akışı oturumu aşağıdaki akışa sahiptir:

  1. Google, yetkilendirme uç noktanızı kullanıcının tarayıcısında açar. İşlem için akış yalnızca sesli cihazda başlatıldıysa Google, yürütmeyi telefona aktarır.
  2. Kullanıcı, henüz oturum açmadıysa oturum açar ve Google'a, daha önce izin vermediyse API'nizle verilerine erişme izni verir.
  3. Hizmetiniz bir yetkilendirme kodu oluşturur ve bunu Google'a döndürür. Bunu yapmak için kullanıcının tarayıcısını, isteğe eklenmiş yetkilendirme koduyla birlikte Google'a geri yönlendirin.
  4. Google, yetkilendirme kodunu jeton değişimi uç noktanıza gönderir. Bu uç nokta, kodun gerçekliğini doğrulayıp bir erişim jetonu ve bir yenileme jetonu döndürür. Erişim jetonu, hizmetinizin API'lere erişmek için kimlik bilgisi olarak kabul ettiği kısa ömürlü bir jetondur. Yenileme jetonu, Google'ın saklayabileceği ve süresi dolduğunda yeni erişim jetonları almak için kullanabileceği uzun ömürlü bir jetondur.
  5. Kullanıcı, hesap bağlama akışını tamamladıktan sonra Google'dan gönderilen her sonraki istekte bir erişim jetonu bulunur.

Uygulama Tarifi

Yetkilendirme kodu akışını uygulamak için aşağıdaki adımları uygulayın.

1. adım: Yetkilendirme isteklerini işleme alın

Google, hesap bağlama işlemini başlattığında kullanıcıyı yetkilendirme uç noktanıza yönlendirir. Ayrıntılı protokol sözleşmeleri ve parametre koşulları için Yetkilendirme Uç Noktası'na bakın.

İsteği işlemek için aşağıdaki işlemleri yapın:

  1. İsteği doğrulayın:

    • client_id değerinin Google'a atanan istemci kimliğiyle eşleştiğini onaylayın.
    • redirect_uri değerinin beklenen Google yönlendirme URL'siyle eşleştiğini doğrulayın: none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
    • response_type değerinin code olduğunu doğrulayın.

  2. Kullanıcının kimliğini doğrulayın:

    • Kullanıcının hizmetinizde oturum açıp açmadığını kontrol edin.
    • Kullanıcı oturum açmadıysa oturum açma veya kaydolma akışınızı tamamlamasını isteyin.

  3. Yetkilendirme kodu oluşturma:

    • Kullanıcı ve istemciyle ilişkilendirilmiş, tahmin edilemeyen benzersiz bir yetkilendirme kodu oluşturun.
    • Kodun süresini yaklaşık 10 dakika sonra dolacak şekilde ayarlayın.

  4. Google'a geri yönlendirme:

    • Tarayıcıyı redirect_uri içinde sağlanan URL'ye yönlendirin.
    • Aşağıdaki sorgu parametrelerini ekleyin:
      • code: Oluşturduğunuz yetkilendirme kodu.
      • state: Google'dan alınan değiştirilmemiş durum değeri.

2. adım: Jeton değişimi isteklerini işleme

Jeton değişimi uç noktanız iki tür isteği işler: kodları jetonlarla değiştirme ve süresi dolmuş erişim jetonlarını yenileme. Ayrıntılı protokol sözleşmeleri ve parametre koşulları için Token Exchange Endpoint'i (Jeton Değişimi Uç Noktası) inceleyin.

C. Jetonlar için yetkilendirme kodlarını kullanma

Google, yetkilendirme kodunu aldığında jetonları almak için jeton değişimi uç noktanızı (POST) çağırır.

  1. İsteği doğrulayın:

    • client_id ve client_secret'ı doğrulayın.
    • Yetkilendirme kodunun geçerli olduğunu ve süresinin dolmadığını doğrulayın.
    • redirect_uri değerinin 1. adımda kullanılan değerle eşleştiğini onaylayın.
    • Doğrulama başarısız olursa 400 Bad Request ile birlikte bir HTTP {"error": "invalid_grant"} döndürün.

  2. Jeton verme:

    • Uzun ömürlü refresh_token ve kısa ömürlü access_token (genellikle 1 saat) oluşturun.
    • Standart JSON jetonu yanıtıyla bir HTTP 200 OK döndürün.

B. Erişim jetonlarını yenileme

Erişim jetonunun süresi dolduğunda Google, yenileme jetonunu kullanarak yeni bir jeton ister.

  1. İsteği doğrulayın:

    • client_id, client_secret ve refresh_token işletmelerini doğrulayın.
    • Doğrulama başarısız olursa 400 Bad Request ile birlikte bir HTTP {"error": "invalid_grant"} döndürün.

  2. Yeni erişim jetonu verme:

    • Yeni bir kısa ömürlü access_token oluşturun.
    • JSON jetonu yanıtıyla (isteğe bağlı olarak yeni bir yenileme jetonu da dahil) bir HTTP 200 OK döndürün.
Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

userinfo endpoint request headers
Authorization header The access token of type Bearer.

For example, if your userinfo endpoint is available at https://myservice.example.com/userinfo, a request might look like the following:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

For your userinfo endpoint to handle requests, do the following steps:

  1. Extract access token from the Authorization header and return information for the user associated with the access token.
  2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response: 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

  3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response: 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
     If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

    userinfo endpoint response
    sub A unique ID that identifies the user in your system.
    email Email address of the user.
    given_name Optional: First name of the user.
    family_name Optional: Last name of the user.
    name Optional: Full name of the user.
    picture Optional: Profile picture of the user.

Uygulamanızı doğrulama

OAuth 2.0 Playground aracını kullanarak uygulamanızı doğrulayabilirsiniz.

Araçta aşağıdaki adımları uygulayın:

  1. OAuth 2.0 Yapılandırma penceresini açmak için Yapılandırma'yı tıklayın.
  2. OAuth akışı alanında İstemci tarafı'nı seçin.
  3. OAuth Uç Noktaları alanında Özel'i seçin.
  4. OAuth 2.0 uç noktanızı ve Google'a atadığınız istemci kimliğini ilgili alanlarda belirtin.
  5. 1. adım bölümünde herhangi bir Google kapsamı seçmeyin. Bunun yerine bu alanı boş bırakın veya sunucunuz için geçerli bir kapsam yazın (OAuth kapsamları kullanmıyorsanız rastgele bir dize yazabilirsiniz). İşiniz bittiğinde API'leri yetkilendir'i tıklayın.
  6. 2. adım ve 3. adım bölümlerinde OAuth 2.0 akışını inceleyin ve her adımın beklendiği gibi çalıştığını doğrulayın.

Uygulamanızı Google Hesabı Bağlantısı Demosu aracını kullanarak doğrulayabilirsiniz.

Araçta aşağıdaki adımları uygulayın:

  1. Google ile oturum aç düğmesini tıklayın.
  2. Bağlamak istediğiniz hesabı seçin.
  3. Hizmet kimliğini girin.
  4. İsteğe bağlı olarak, erişim isteğinde bulunacağınız bir veya daha fazla kapsam girin.
  5. Start Demo'yu (Demoyu Başlat) tıklayın.
  6. İstendiğinde, bağlantı isteğini onaylayabileceğinizi ve reddedebileceğinizi onaylayın.
  7. Platformunuza yönlendirildiğinizi onaylayın.