Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

API Anahtarı Yönetimi ve Güvenliği

1. Giriş

Geçmişte, diğer yöntemler kullanılamadığında veya uygunsuz kabul edildiğinde Google API'lerine erişmek için Google API anahtarları kullanılıyordu. Popüler kullanım alanları arasında Google Haritalar API'sine ve Firebase tarafından kullanıma sunulan Google API'lerine erişim yer alıyordu. Yapay zeka modellerinin, Gemini gibi yapay zeka aracıların, AI Studio ve Agent Development Kit gibi aracı geliştirme çerçevelerinin kullanıma sunulmasıyla birlikte API anahtarları, Google'ın büyük dil modellerine erişmek için kullanılan temel yöntemlerden biri haline geldi.

API anahtarları düşük düzeyde koruma sağlar. Google Cloud, anahtarların kötüye kullanımını önlemek için çeşitli yöntemler sunsa da etkin bir API anahtarına sahip olmak, ek kimlik doğrulama veya yetkilendirme doğrulamaları olmadan Google API'lerine erişime olanak tanır. API anahtarlarının kullanımını kısıtlama yöntemleri belgelerde açıklanmıştır. Cloud Blog'daki Securing Your Gemini and Google API (Gemini ve Google API Anahtarlarınızın Güvenliğini Sağlama) başlıklı yayında, API anahtarı bakımıyla ilgili ek öneriler sunulmaktadır. Bu Codelab'de bu önerileri uygulamaya koyacaksınız.

Yapacaklarınız

Google Cloud'da yeni API anahtarları oluştururken zorunlu kılınan kısıtlamaları inceleme
Tüm API anahtarlarınızı kataloglayın ve güvenlik koruması olmayan anahtarları bulun.
Mevcut API anahtarlarına, kullanımlarına göre kısıtlamalar uygulama
Anormal kullanım durumunda anahtarı silen bir otomasyon tanımlayın.

İhtiyacınız olanlar

Modern bir web tarayıcısı (ör. Chrome)
Bir Google Hesabı

2. Kurulum

Bu Codelab'deki talimatlarda, komutları Google Cloud Console'daki Cloud Shell'de çalıştırdığınız varsayılır. Yerel ortamınızda gcloud CLI varsa komutları burada çalıştırabilirsiniz.

Adımlardaki işlemler Cloud Console kullanıcı arayüzü kullanılarak yapılabilir ancak yöntemler farklıdır. Bu Codelab, etkileşimleri basitleştirmek ve modern yapay zeka aracılarıyla (ör. Antigravity CLI) daha kolay entegrasyon sağlamak için komut satırı arayüzünü kullanır.

Cloud Shell terminali başlatma

Yeni bir tarayıcı penceresinde https://console.cloud.google.com/ adresini kullanarak Google Cloud Console'u açın. En iyi kullanıcı deneyimi için Chrome'u kullanmanız önerilir.
Google Cloud'da Google Hesabınızda oturum açın.
Google Cloud konsolunun üst kısmından Activate Cloud Shell 'i (Cloud Shell'i etkinleştir) tıklayın.
Gösteriliyorsa aşağıdaki pencereleri tıklayın:
- Cloud Shell bilgi penceresinde devam edin.
- Google Cloud API çağrıları yapmak için Cloud Shell'e kimlik bilgilerinizi kullanma yetkisi verin.

Bir Google Cloud projesi seçin

Cloud Console'u açtıktan sonra kimliğiniz doğrulanır ve genellikle çalışmanız için bir proje seçimi yapılır. Proje kimliği, küçük harfler, rakamlar ve tire sembollerinden oluşan 6-30 karakterlik bir dizidir (ör. qwiklabs-gcp-04-3075fc9fd77f). Cloud Shell terminali, gcloud CLI'yı seçilen projeyle yapılandırır. Aşağıdakine benzer bir çıkış görürsünüz:

Your Cloud Platform project in this session is set to qwiklabs-gcp-04-3075fc9fd77f

Bu, gcloud ile ilgili diğer komutlarınızda qwiklabs-gcp-04-3075fc9fd77f proje kimliğinin kullanılacağı anlamına gelir.

Proje kimliğini ortam değişkeni olarak ayarlayın PROJECT_ID. Aşağıdaki komutu kullanarak tüm projelerinizin listesini görebilirsiniz:

gcloud projects list

your-project-id yerine kendi proje kimliğinizi girin ve gcloud içinde yapılandırılmış olandan farklı bir proje kimliği kullanmak istiyorsanız komutu çalıştırın.
```
export PROJECT_ID="your-project-id"
```
Örneğin:
```
export PROJECT_ID="qwiklabs-gcp-04-3075fc9fd77f"
```
Seçili proje kimliğini kullanmak istiyorsanız aşağıdaki komutu çalıştırın:
```
export PROJECT_ID=$(gcloud config get project)
```

3. Yeni bir API anahtarını kısıtlama

Geçmişte kullanıcılar tamamen kısıtlanmamış API anahtarları oluşturabiliyordu. Kısıtlanmamış anahtarlar, anahtarın oluşturulduğu projede etkinleştirilen HERHANGİ BİR Google API'sini çağırmak için kullanılabilir. Google Cloud Console, kullanıcıların sınırsız anahtar oluşturmasını engellese de gcloud CLI veya doğrudan API çağrıları kullanılarak bu işlem yapılabilir.

Aşağıdaki adımlarda, kullanımı belirli bir API ve belirtilen web sitesiyle sınırlayan kısıtlanmış bir API anahtarının nasıl oluşturulacağı gösterilmektedir.

Yalnızca Google Haritalar coğrafi konum API'si ile kullanılmak üzere kısıtlanmış yeni bir API anahtarı oluşturmak için kabuk terminalinde aşağıdaki komutu çalıştırın:
```
gcloud services api-keys create --key-id=restricted-api-key \
  --display-name="restricted api key" \
  --api-target=service=geolocation.googleapis.com \
  --project=${PROJECT_ID}
```
Bu komut, YALNIZCA Google Haritalar coğrafi konum hizmetini çağırmak için kullanılabilecek yeni bir API anahtarı oluşturur.
ℹ️ Not: Kısıtlanmış listeye birden fazla API ekleyebilirsiniz. --api-target parametresini, SERVICE Google hizmetlerinden biri olacak şekilde =service=SERVICE.googleapis.com değeriyle birlikte birden fazla kez kullanın.
Uygulama kısıtlaması ekleyerek anahtar güvenliğini artırın. Anahtarın kullanımını yalnızca web sitesi example.com içindeki tüm yollarla sınırlayın. Anahtara uygulama kısıtlaması eklemek için aşağıdaki komutu çalıştırın:
gcloud services api-keys update restricted-api-key \ --location=global \ --allowed-referrers="example.com/*" \ --project=${PROJECT_ID}
Anahtarın belirli web sitelerinde kullanılmasına izin vermek yerine, izin verilen Android uygulamasını tanımlamak için --allowed-application'ı, izin verilen IP adreslerini tanımlamak için allowed-ips'ı kullanabilirsiniz. Tüm seçenekler için belgelerin tamamını inceleyin.
ℹ️ Not: Birden fazla parametre (ör. --allowed-referrers) sağlayarak AYNI türden birden fazla uygulama kısıtlaması ekleyebilirsiniz. Birden fazla türde uygulama kısıtlaması eklediğinizde parametre listesine yalnızca en son tür kaydedilir.

Temizleme

Kullanmayı planlamıyorsanız oluşturduğunuz API anahtarını silin:

gcloud services api-keys delete --key-id=restricted-api-key \
  --project=${PROJECT_ID}

4. API anahtarlarınızı kataloglama

Bu adımda, API anahtarlarınızın envanterini almak için gcloud KSA'yı kullanacaksınız. Sonuçta elde edilen listede, erişebildiğiniz tüm etkin (silinmemiş) API anahtarları gösterilir.

Tüm anahtar adlarını, kimliklerini ve oluşturma tarihlerini görmek için aşağıdaki komutu çalıştırın:
```
gcloud services api-keys list --project=${PROJECT_ID} \
  --format='value(displayName,name.basename(),createTime.date())'
```
Çıktıda, anahtarın okunabilir adı, anahtar kimliği ve anahtarın oluşturulduğu tarih gösterilir. Bu, aşağıdaki gibi olur:
```
api key 1	api-key-1	2024-05-10T07:53:24
api key 2	api-key-2	2025-06-12T14:47:57
```
Önemli kimliklerden birini seçin ve anahtarda kısıtlama olup olmadığını kontrol etmek için aşağıdaki komutu yapıştırın. your-key-id yerine seçilen anahtar kimliğinin değerini girin:
```
gcloud services api-keys describe "your-key-id" --project=${PROJECT_ID}
```

Çıkış (YAML biçiminde), restrictions altında bir kısıtlama listesi içerir.

createTime: '2024-05-10T07:53:24.986528Z'
displayName: api key 1
etag: W/"u1WuY41K2tPKUZd7cfLoKg=="
name: projects/123456789012/locations/global/keys/api-key-1
restrictions:
  apiTargets:
  - service: geolocation.googleapis.com
  browserKeyRestrictions:
    allowedReferrers:
    - https://example.com/*
uid: 1a2b3c4d-1234-abcd-1234-a1b2c3d4e5f6
updateTime: '2024-05-10T07:53:24.071228Z'

Anahtar hiç güncellenmediyse createTime ve updateTime alanlarının aynı zaman damgasına sahip olacağını unutmayın.

Tüm projelerinizi inceleyen ve kısıtlama içermeyen tüm API anahtarlarını yazdıran komut dosyasını indirip çalıştırın:

curl -fsSL -o unrestricted_api_keys.sh \
  "https://github.com/GoogleCloudPlatform/devrel-demos/blob/main/security/api-key-audit/unrestricted_api_keys.sh"
chmod +x unrestricted_api_keys.sh
./unrestricted_api_keys.sh

Komut dosyasını çalıştırdıktan sonra şu biçimde bir çıkış görürsünüz:

DISPLAY NAME    KEY ID    PROJECT ID    CREATION DATE
Key 1    1a2b3c4d-1234-abcd-1234-a1b2c3d4e5f6    my-project-1    2024-05-10T07:53:24.071228Z

Bu CodeLab'de kullanılan tüm komut dosyalarını GitHub'daki devrel-demos deposunun Security folder (Güvenlik klasörü) bölümünde bulabilirsiniz.

5. API anahtarının kullanımını keşfetme

Bu adımda, API anahtarınız kullanılarak hangi API'lerin çağrıldığını bulmanıza yardımcı olan Google Cloud metriklerini sorgulayacaksınız. Bu bilgileri kullanarak anahtarların mevcut kullanımını inceleyebilir ve tahminde bulunmak yerine gerçek bilgilere göre anahtara API kısıtlamaları uygulayabilirsiniz.

Önceki adımda kullandığınız anahtar kimliğini kullanın veya başka bir anahtar kimliği seçin. Aşağıdaki komutta your-key-id yerine seçilen anahtar kimliğini girin:
```
export KEY_UID=$(
   gcloud services api-keys describe "your-key-id" \
   --format='value(uid)' \
   --project=${PROJECT_ID})
```
Aramayı, bir yıllık kullanım geçmişine bakacak şekilde ayarlayın. Daha uzun veya daha kısa bir süre aramak istiyorsanız 365 (gün sayısı) yerine başka bir pozitif sayı girin.
```
export DAYS=365
```
Cloud Monitoring API'ye doğrudan çağrı yapılmasını sağlamak için Uygulama Varsayılan Kimlik Bilgileri'ni (ADC) yenileyin. Aşağıdaki komutu çalıştırın ve terminaldeki talimatları uygulayın:
```
gcloud auth application-default login
```
Hizmet kullanımı metrik verileri için Cloud Monitoring API'ye istek göndermek üzere aşağıdaki komutu çalıştırın:

curl -s -G -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  --data-urlencode "filter=metric.type=\"serviceruntime.googleapis.com/api/request_count\" AND resource.labels.credential_id=\"apikey:${KEY_UID}\"" \
  --data-urlencode "interval.startTime=$(date -u -d "${DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)" \
  --data-urlencode "interval.endTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  "https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries" \
  | jq -r '.timeSeries[]?.resource.labels.service' | sort -u

Komut, seçilen API anahtarı benzersiz kimliğiyle eşleşen credential_id etiketine sahip veri noktaları için serviceruntime/api/request_count yerleşik metriğini sorgular. Ardından, service etiketiyle ilgili değerleri alır ve tekrarları ortadan kaldırarak değerleri yazdırır.

API anahtarını sağlamlaştırma

Bu adımda, API anahtarının kısıtlama yapılandırmasını kullanım bilgilerine göre güncellemek için önceki adımlarda toplanan bilgileri kullanacaksınız.

Önceki adımda kullanılan API anahtarını kullanacaksınız. Gerekirse ortam değişkenleri PROJECT_ID, KEY_UID ve DAYS'nin ayarlandığından emin olmak için önceki adımlardaki talimatları yeniden çalıştırın.

API anahtarı kullanılarak çağrılan Google API'lerinin listesini almak için aşağıdaki komutu çalıştırın:

SERVICES=$(curl -s -G -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"
–data-urlencode "filter=metric.type="serviceruntime.googleapis.com/api/request_count" AND resource.labels.credential_id="apikey:${KEY_UID}""
–data-urlencode "interval.startTime=$(date -u -d "${DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)"
–data-urlencode "interval.endTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
"https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries"
| jq -r ‘.timeSeries[]?.resource.labels.service' | sort -u)

1. Build the list of arguments to restrict the API usage for the API key based
on the retrieved list.

```shell
API_TARGET_ARGS=()
for SERVICE in $SERVICES; do
  API_TARGET_ARGS+=("--api-target=service=${SERVICE}")
done

Boş olmayan liste için kısıtlanmış API'lerin listesini değiştirin:

if [ ${#API_TARGET_ARGS[@]} -gt 0 ]; then
    gcloud services api-keys update "projects/${PROJECT_ID}/locations/global/keys/${KEY_UID}" \
    ${API_TARGET_ARGS}
fi

6. Anormallik Kullanımı Algılamayı Tanımlama

Önceki adımlarda API anahtarlarının nasıl keşfedileceği ve güvenli hale getirileceği gösterilmişti. Bu adımda, izleme uyarıları yardımıyla anahtar kullanımındaki beklenmedik zirveye nasıl otomatik yanıt verileceği gösterilmektedir.

Aşağıdaki talimatlar, API anahtarı kullanan API çağrılarının oranı son 5 dakikada% 10'dan fazla arttığında tetiklenen bir uyarı oluşturur. Uyarı, daha fazla kullanımı önlemek için API anahtarını silen bir Cloud Build komut dosyasını tetikleyecek şekilde yapılandırılır. Anahtar, önümüzdeki 30 gün içinde geri yüklenebilir. Anahtarı nasıl geri yükleyeceğinizi öğrenmek için belgelere bakın.

Talimatlarda, önceki adımlarda kullandığınız PROJECT_ID ve KEY_UID değişkenleri yeniden kullanılır. Farklı bir anahtar ve/veya proje seçmek istiyorsanız bu değişkenler için yeni değerleri API anahtarının kurulumu ve kullanımının keşfi adımlarında açıklandığı şekilde ayarlayın.

Uyarı politikası dosyası oluşturmak için aşağıdaki komut dosyasını çalıştırın:

cat <<EOF > alert_policy.json
{
  "displayName": "Credential API Request Count Increase Alert (Project: ${PROJECT_ID})",
  "combiner": "OR",
  "conditions": [
    {
      "displayName": "API Request Count Increase > 10% in 5m with Min Volume",
      "conditionPrometheusQueryLanguage": {
        "query": "(sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m])) / (sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m] offset 5m)) or on() vector(1)) > 1.10) and (sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m])) > 50)",
        "duration": "0s",
        "evaluationInterval": "60s"
      }
    }
  ],
  "enabled": true
}
EOF

Uyarı politikası, uyarıyı tetiklemek için aşağıdaki PromQL filtresini kullanır:

 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id="API_KEY_UID"}[5m])
 ) /
 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id="API_KEY_UID"}[5m] offset 5m)
 ) or on() vector(1)) > 1.10)
and
 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\"YOUR_CREDENTIAL_ID_HERE\"}[5m])) > 50)

Artış oranını hesaplar ve önceki bir dönemle karşılaştırır. Ayrıca uyarıyı yalnızca% 10'dan fazla artış olduğunda tetikler. Toplam çağrı sayısı ihmal edilebilir olduğunda uyarının tetiklenmesini önlemek için tetikleme koşulu, pencerede 50'den fazla API çağrısı olmasını gerektirir. Önceki 5 dakikalık oran 0 olduğunda NaN (sıfıra bölme) hesaplamasını önlemek için önceki pencere oranı sıfırsa payda 1 ile değiştirilir.Pencere uzunluğu (5m), minimum eşik (50) veya% 10 artış eşiği (1.10) gibi uyarı parametrelerini değiştirebilirsiniz. Ek politika parametreleri, koşul karşılandığında uyarının tetiklenmesi (duration) ve koşulun her 60 saniyede bir kontrol edilmesi (evaluationInterval) gerektiğini tanımlar.

Uyarı bildirimleri yayınlamak için kullanılacak bir Pub/Sub konusu oluşturmak üzere aşağıdaki komutu çalıştırın:
```
gcloud pubsub topics create api-key-alert-notifications --project=$PROJECT_ID
```

PubSub'ı kullanan uyarılar için bildirim kanalları oluşturmak üzere aşağıdaki komutu çalıştırın.

CHANNEL_NAME=$(gcloud beta monitoring channels create \
  --display-name="Pub/Sub Alert Channel" \
  --type="pubsub" \
  --channel-labels="topic=projects/$PROJECT_ID/topics/api-key-alert-notifications" \
  --format='value(name)' \
  --project=$PROJECT_ID)

Temizleme adımında CHANNEL_NAME ortam değişkenini kullanacaksınız.

Yeni bir izleme uyarısı oluşturmak için aşağıdaki komutu çalıştırın:

gcloud monitoring policies create --policy-from-file=alert_policy.json \
  --project=$PROJECT_ID

Cloud Build hizmetine projedeki API anahtarlarını silme izni vermek için aşağıdaki komutu çalıştırın.
```
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
  --role="roles/apikeys.admin"
```
apikeys.admin rolünün yalnızca API anahtarlarının belirli bir örneğini değiştirmesi sınırlandırılabilir. Daha fazla bilgi için IAM koşulları'nı inceleyin.

API anahtarını silen bir Cloud Build derleme tetikleyicisi oluşturmak için aşağıdaki komut dosyasını çalıştırın.

cat <<EOF > trigger_config.yaml
name: "delete-compromised-api-key"
description: "Triggered by Pub/Sub alert to automatically delete the leaking API Key"
pubsubConfig:
  topic: "projects/${PROJECT_ID}/topics/api-key-alert-notifications"
build:
  steps:
  - name: "gcr.io/google.com/cloudsdktool/cloud-sdk:slim"
    args:
    - "gcloud"
    - "services"
    - "api-keys"
    - "delete"
    - "${KEY_UID}"
    - "--quiet"
EOF

Yeni bir Monitoring uyarısı tetikleyicisi oluşturmak için aşağıdaki komutu çalıştırın:

gcloud builds triggers create pubsub \
  --trigger-config=trigger_config.yaml \
  --project=$PROJECT_ID

Artık uyarı politikası ve Cloud Build derleme tetikleyicisi yapılandırma dosyalarını silebilirsiniz:

rm alert_policy.json trigger_config.yaml

Alternatif olarak, bu otomasyonu Terraform planını kullanarak da ayarlayabilirsiniz. Google Cloud DevRel deposundaki abnormal-usage-detection klasöründen Terraform dosyalarını indirin. Plan, giriş parametreleri olarak bir proje kimliği ve API anahtarı UID'si kabul eder ve bu adımda gördüğünüz kaynakları ve yapılandırmaları ayarlar.

7. Temizleme

Google Cloud hesabınızda beklenmedik ücretlerle karşılaşmamak için bu alıştırma sırasında oluşturulan Pub/Sub konusu, Cloud Build derleme tetikleyicisini ve uyarı politikalarını silmeyi unutmayın.

Oluşturduğunuz tüm kaynakları silmek için aşağıdaki komutları çalıştırın:

gcloud builds triggers delete delete-compromised-api-key \
  --project=$PROJECT_ID
gcloud beta monitoring channels delete $CHANNEL_NAME \
  --project=$PROJECT_ID \
  --quiet
gcloud pubsub topics delete api-key-alert-notifications \
  --project=$PROJECT_ID
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
  --role="roles/apikeys.admin"

8. Özet

Bu codelab'de, Google Cloud API anahtarları için uçtan uca sağlam bir güvenlik ve otomasyon çerçevesi uyguladınız:

Güçlendirilmiş Varsayılan Yapılandırmalar: API anahtarlarını yalnızca gerekli API'lere ve güvenilir platformlara (ör. belirli HTTP yönlendirenleri) erişimi sınırlayacak şekilde oluşturup kısıtladınız.
Anahtar envanterinizi denetlediniz: Proje ortamlarınızı tarayarak anında güvenlik riski oluşturan sınırsız anahtarları tespit edip izole ettiniz.
Analiz Edilen Kullanım Verileri: Geçmişteki anahtar kullanımını profillemek için Cloud Monitoring metrik verilerini programatik olarak sorguladınız. Bu sayede, doğrulanmış kullanım izlerine göre anahtarları kısıtlayabilirsiniz.
Otomatik Tehdit Azaltma: Cloud Monitoring uyarı politikasını bir Pub/Sub konusuna ve Cloud Build derleme tetikleyicisine bağlayarak reaktif bir "devre kesici" oluşturdunuz. Bu sayede, anormal trafik artışları sırasında güvenliği ihlal edilmiş anahtarları otomatik olarak silebilirsiniz.

Sonraki Adımlar

Tüm API anahtarlarınıza kısıtlamalar uygulama: Kısmen kısıtlanmış veya kısıtlanmamış tüm API anahtarlarını tespit etmek ve API ile istemci kısıtlamaları uygulamak için bu laboratuvarda öğrendiklerinizi kullanın.
API anahtarlarında "devre kesici" ayarlama: Ani tüketim artışı durumunda anahtarın otomatik olarak silinmesini ayarlayarak API anahtarlarınızı beklenmedik kullanıma karşı daha fazla koruyun. Laboratuvarda gösterilen gcloud komutlarını veya Terraform'u kullanın. IAM koşullarını kullanarak izinleri sıkılaştırmayı düşünün.
Monitoring Alerting'i keşfedin: Google Cloud Monitoring hizmetini kullanarak uyarı ayarlama hakkında daha fazla bilgi edinin.
Google Cloud'da kullanılabilen erişim denetimi hakkında daha fazla bilgi edinin: Erişim sınırı politikalarını ve erişim değişikliği yayılımını inceleyin.