מדריך למתחילים: אבטחת התעבורה לשירות באמצעות ה-CLI של gcloud

בדף הזה מוסבר איך לפרוס API ב-API Gateway כדי לאבטח את תעבורת הנתונים לשירות לקצה העורפי.

כדי לפרוס API חדש כדי לגשת לשירות לקצה העורפי בפונקציות Cloud Run באמצעות Google Cloud CLI, פועלים לפי השלבים הבאים. במדריך למתחילים הזה מוסבר גם איך להשתמש במפתח API כדי להגן על הבק-אנד מפני גישה לא מורשית.

לפני שמתחילים

  1. במסוף Google Cloud , עוברים לדף Dashboard ובוחרים פרויקט ב- Google Cloud או יוצרים אותו.

    אל לוח הבקרה

  2. מוודאים שהחיוב מופעל בפרויקט.

    הפעלת החיוב

  3. מוודאים ש-Google Cloud CLI הורד והותקן במחשב.

    הורדת ה-CLI של gcloud

  4. עדכון רכיבים של gcloud:

    gcloud components update

  5. מגדירים את פרויקט ברירת המחדל. מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud .

    gcloud config set project PROJECT_ID

הפעלת שירותים נדרשים

כדי להשתמש ב-API Gateway, צריך להפעיל את השירותים הבאים של Google Cloud :

שם שם השירות
API Gateway API apigateway.googleapis.com
Service Management API servicemanagement.googleapis.com
Service Control API servicecontrol.googleapis.com

כדי להפעיל את השירותים הנדרשים:

מסוף Google Cloud

  1. במסוף Google Cloud , נכנסים לדף APIs & Services > API Library.

    לדף API Library

  2. בדף API Library, מזינים את שם ה-API הנדרש בסרגל החיפוש.
  3. בתוצאות החיפוש, בוחרים את דף ה-API.
  4. בדף ה-API, לוחצים על הפעלה.
  5. חוזרים על השלבים האלה לכל אחד מהשירותים שמפורטים בטבלה הקודמת.

Google Cloud CLI

משתמשים בפקודות הבאות כדי להפעיל את השירותים:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

מידע נוסף על שירותי gcloud זמין במאמר בנושא שירותי gcloud.

פריסת קצה עורפי של API

‫API Gateway נמצא לפני שירות קצה עורפי שמוטמע ומטפל בכל הבקשות הנכנסות. במדריך למתחילים הזה, API Gateway מעביר קריאות נכנסות אל קצה עורפי של פונקציית Cloud Run בשם helloGET, שמכיל את פונקציית Node.js שמוצגת בהמשך.

const functions = require('@google-cloud/functions-framework');

// Register an HTTP function with the Functions Framework that will be executed
// when you make an HTTP request to the deployed function's endpoint.
functions.http('helloGET', (req, res) => {
  res.send('Hello World!');
});

פועלים לפי השלבים במאמר מדריך למתחילים: פריסת פונקציית Cloud Run באמצעות Google Cloud CLI כדי להוריד את קוד הדוגמה של פונקציות Cloud Run ולפרוס את שירות ה-Backend של פונקציית Cloud Run. האדמין יצטרך להעניק תפקידים נוספים לחשבון שלכם ולחשבון השירות של Cloud Build, כמו שמתואר בתחילת העבודה המהירה הזו.

מעתיקים את כתובת ה-URL של השירות שמוצגת כשפורסים את פונקציית Cloud Run. תצטרכו אותו כשתיצרו את הגדרת ה-API בשלב הבא.

יצירת API

עכשיו אפשר ליצור את ה-API ב-API Gateway.

  1. מזינים את הפקודה הבאה, כאשר:

    • ‫API_ID מציין את השם של ה-API. הנחיות למתן שמות ל-API מופיעות במאמר בנושא דרישות לגבי מזהה API. 
      gcloud api-gateway apis create API_ID

    לדוגמה:

    gcloud api-gateway apis create my-api

  2. אחרי שהפעולה תושלם בהצלחה, תוכלו להשתמש בפקודה הבאה כדי לראות פרטים על ה-API החדש:

    gcloud api-gateway apis describe API_ID

    לדוגמה:

    gcloud api-gateway apis describe my-api

    הפקודה הזו מחזירה את הפלט הבא:

      createTime: '2020-02-29T21:52:20.297426875Z'
  displayName: my-api
  managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog
  name: projects/my-project/locations/global/apis/my-api
  state: ACTIVE
  updateTime: '2020-02-29T21:52:20.647923711Z'

מעתיקים את הערך של המאפיין managedService. הערך הזה משמש להפעלת ה-API בשלב הבא.

יצירת הגדרת API

כדי להשתמש ב-API Gateway לניהול התנועה אל קצה העורפי של ה-API שפרסתם, צריך להגדיר את ה-API.

אפשר ליצור הגדרת API באמצעות תיאור OpenAPI שמכיל הערות מיוחדות להגדרת ההתנהגות של API Gateway שנבחר. פרטים נוספים על תוספי OpenAPI נתמכים זמינים במאמרים הבאים:

תיאור ה-OpenAPI שמשמש במדריך למתחילים הזה מכיל הוראות ניתוב ל-Backend של פונקציית Cloud Run:

OpenAPI 2.0

# openapi-functions.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: SERVICE_URL/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

‫OpenAPI 3.x

# openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    functions_backend:
      address: SERVICE_URL/helloGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: functions_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

כדי להעלות את תיאור ה-OpenAPI הזה וליצור הגדרת API באמצעות ה-CLI של gcloud:

  1. משורת הפקודה, יוצרים קובץ חדש בשם openapi-functions.yaml.

  2. מעתיקים ומדביקים את התוכן של תיאור OpenAPI בקובץ החדש שיצרתם.

  3. עורכים את הקובץ באופן הבא:

    1. בשדה title, מחליפים את API_ID בשם ה-API ואת optional-string בתיאור קצר לבחירתכם. הערך של השדה הזה משמש ליצירת מפתחות API שמעניקים גישה ל-API הזה.
    2. בשדה address, מחליפים את SERVICE_URL בכתובת ה-URL שבה פועל שירות לקצה העורפי של פונקציית Cloud Run, שהעתקתם בשלב הקודם.

  4. מזינים את הפקודה הבאה, כאשר:

    • ‫CONFIG_ID מציין את השם של הגדרת ה-API.
    • ‫API_ID מציין את השם של ה-API.
    • ‫API_DEFINITION מציין את שם הקובץ של מפרט OpenAPI.
    • ‫SERVICE_ACCOUNT_EMAIL מציין את חשבון השירות שמשמש לחתימה על אסימונים עבור שרתי קצה עורפיים שהוגדר להם אימות. מידע נוסף מופיע במאמר הגדרת חשבון שירות. 
    gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
   --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

    לדוגמה:

    gcloud api-gateway api-configs create my-config \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com

    יכול להיות שיחלפו כמה דקות עד שהפעולה תושלם, כי הגדרות ה-API מועברות למערכות במורד הזרם. יצירת הגדרת API מורכבת עשויה להימשך עד עשר דקות.

  5. אחרי שיוצרים את הגדרת ה-API, אפשר להריץ את הפקודה הבאה כדי לראות את הפרטים שלה:

    gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID

    לדוגמה:

    gcloud api-gateway api-configs describe my-config \
  --api=my-api

    הפלט מציג את פרטי ההגדרה של ה-API, כולל השם והסטטוס, כמו בדוגמה הבאה:

    createTime: '2020-02-07T18:17:01.839180746Z'
displayName: my-config
gatewayConfig:
backendConfig:
  googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com
name: projects/my-project/locations/global/apis/my-api/configs/my-config
serviceRollout:
rolloutId: 2020-02-07r0
state: ACTIVE
updateTime: '2020-02-07T18:17:02.173778118Z'

יצירת שער

עכשיו פורסים את הגדרת ה-API בשער. פריסת הגדרת API בשער מגדירה כתובת URL חיצונית שלקוחות API יכולים להשתמש בה כדי לגשת ל-API.

מריצים את הפקודה הבאה כדי לפרוס את הגדרת ה-API שיצרתם ב-API Gateway:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION

where:

  • ‫GATEWAY_ID מציין את שם השער.
  • ‫API_ID מציין את השם של ה-API של API Gateway שמשויך לשער הזה.
  • ‫CONFIG_ID מציין את השם של הגדרת ה-API שנפרסה בשער.

  • ‫GCP_REGION הוא Google Cloud האזור של השער שנפרס.

  • ‫PROJECT_ID מציין את שם הפרויקט ב- Google Cloud .

לדוגמה:

gcloud api-gateway gateways create my-gateway \
  --api=my-api --api-config=my-config \
  --location=us-central1

אחרי שהפעולה מסתיימת בהצלחה, מריצים את הפקודה הבאה כדי לראות את הפרטים של השער:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION

לדוגמה:

gcloud api-gateway gateways describe my-gateway \
  --location=us-central1

הפקודה הזו מחזירה את הפלט הבא:

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: my-gateway
name: projects/my-project/locations/us-central1/gateways/my-gateway
serviceAccount:
      email: 0000000000000-compute@developer.gserviceaccount.com
state: ACTIVE
updateTime: '2020-02-05T13:45:00.844705087Z'

רושמים את הערך של המאפיין defaultHostname. זהו שם המארח של כתובת ה-URL של השער שבה תשתמשו כדי לבדוק את הפריסה בשלב הבא.

בדיקת פריסת ה-API

עכשיו אפשר לשלוח בקשות ל-API באמצעות כתובת ה-URL שנוצרה כשפרסתם את השער.

מזינים את הפקודה curl הבאה, כאשר:

  • ‫DEFAULT_HOSTNAME מציין את החלק של שם המארח בכתובת ה-URL של השער שפרסתם, שהעתקתם בשלב הקודם.
  • ‫hello הוא הנתיב שצוין בהגדרת ה-API.
curl https://DEFAULT_HOSTNAME/hello

לדוגמה: 

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

הפלט שיתקבל:

Hello World!

יצרתם ופרסתם בהצלחה API Gateway.

אבטחת הגישה באמצעות מפתח API

כדי לאבטח את הגישה לקצה העורפי של ה-API באמצעות מפתח API:

  1. יוצרים מפתח API שמשויך לפרויקט.
  2. יוצרים ומפעילים הגדרת API חדשה כדי לאבטח את הגישה ל-API באמצעות מפתחות API.
  3. בדיקת מפתח ה-API

אפשר לעיין גם במאמר בנושא הגבלת הגישה ל-API באמצעות מפתחות API.

יצירה של מפתח API

אם עדיין אין לכם מפתח API שמשויך לפרויקט Google Cloud שבו אתם משתמשים במדריך הזה, אתם צריכים להוסיף אותו כמו שמתואר במאמר יצירת מפתח API.

מעתיקים את מחרוזת המפתח שמוחזרת ומוודאים שהיא מאובטחת. זהו ערך המפתח שבו תשתמשו כשבודקים את מפתח ה-API.

יצירה ופריסה של הגדרת API חדשה

כדי ליצור ולפרוס הגדרת API חדשה שמאבטחת את הגישה ל-API באמצעות מפתחות API:

  1. מפעילים את השירות. מזינים את הפקודה הבאה, כאשר:
    • ‫MANAGED_SERVICE_NAME מציין את השם של השירות המנוהל שנוצר כשפרסתם את ה-API. אפשר לראות את המאפיין הזה ברשימת המאפיינים של השירות המנוהל באמצעות הפקודה gcloud api-gateway apis describe.
    • ‫PROJECT_ID מציין את שם הפרויקט ב- Google Cloud .
    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
     לדוגמה: 
    gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
  2. משנים את תיאור ה-OpenAPI שמשמש ליצירת הגדרות ה-API כך שיכלול הוראות לאכיפת מדיניות אבטחה של אימות מפתח API על כל התנועה. מוסיפים את security type ואת securityDefinitions כמו שמוצג:

    OpenAPI 2.0

      # openapi2-functions.yaml
  swagger: '2.0'
  info:
    title: API_ID optional-string
    description: Sample API on API Gateway with a Google Cloud Functions backend
    version: 1.0.0
  schemes:
    - https
  produces:
    - application/json
  paths:
    /hello:
      get:
        summary: Greet a user
        operationId: hello
        x-google-backend:
          address: SERVICE_URL/helloGET
        security:
        - api_key: []
        responses:
          '200':
            description: A successful response
            schema:
              type: string
  securityDefinitions:
    # This section configures basic authentication with an API key.
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"
     ההגדרה securityDefinition קובעת שמפתח API נדרש כדי לגשת ל-API, ושהמפתח מועבר כפרמטר של שאילתה בשם key כשמבקשים גישה לכל הנתיבים שמוגדרים במפרט.

    ‫OpenAPI 3.x

    # openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    functions_backend:
      address: SERVICE_URL/helloGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: functions_backend
components:
# This section configures basic authentication with an API key.
  securitySchemes:
    google_api_key:
      type: apiKey
      name: x-api-key
      in: header
security:
  - google_api_key: []
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string
     ההגדרה securitySchemes קובעת שמפתח API נדרש כדי לגשת ל-API, ושצריך להעביר אותו כפרמטר של שאילתה בשם key כשמבקשים גישה לכל הנתיבים שמוגדרים במפרט.
  3. יוצרים הגדרת API חדשה עם מפרט OpenAPI ששונה באמצעות הפקודה הבאה: 
    gcloud api-gateway api-configs create NEW_CONFIG_ID \
--api=API_ID --openapi-spec=NEW_API_DEFINITION \
--backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
     לדוגמה: 
    gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com
  4. מריצים את הפקודה הבאה כדי לעדכן את השער הקיים עם הגדרת ה-API החדשה: 
    gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GCP_REGION
    לדוגמה: 
    gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1

בדיקת מפתח ה-API

אחרי שיוצרים את ה-API ששונה ומפעילים אותו, מנסים לשלוח אליו בקשה.

מזינים את הפקודה curl הבאה, כאשר:

  • ‫DEFAULT_HOSTNAME מציין את החלק של שם המארח בכתובת ה-URL של השער שפרסתם, שהעתקתם בשלב הקודם.
  • ‫hello הוא הנתיב שצוין בהגדרת ה-API.
curl https://DEFAULT_HOSTNAME/hello

לדוגמה: 

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

אמורה להופיע השגיאה הבאה:

UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.

עכשיו מזינים את הפקודה curl הבאה, שבה:

  • ‫DEFAULT_HOSTNAME מציין את החלק של שם המארח בכתובת ה-URL של השער שפרסתם, שהעתקתם בשלב הקודם.
  • ‫hello הוא הנתיב שצוין בהגדרת ה-API.
  • ‫API_KEY מציין את מפתח ה-API שיצרתם בשלב הקודם.
curl https://DEFAULT_HOSTNAME/hello?key=API_KEY

עכשיו אמור להופיע Hello World! בתגובה מה-API.

כל הכבוד! הצלחתם להגן על קצה העורפי של ה-API באמצעות API Gateway. עכשיו אפשר להתחיל לצרף לקוחות API חדשים על ידי יצירת מפתחות API נוספים.

הסרת המשאבים

כדי להימנע מחיובים בחשבון על המשאבים שבהם השתמשתם במדריך למתחילים הזה, אתם יכולים: Google Cloud

אפשר גם למחוק את Google Cloud הפרויקט שבו השתמשתם במדריך הזה.

המאמרים הבאים