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

תחילת העבודה עם ספריית האימות של Google

סקירה כללית

‫Google Auth Library היא ספריית לקוח בקוד פתוח לאימות ב-Java. במאמר הזה מוסבר איך להשתמש בספרייה הזו כדי לבצע אימות באפליקציות Java כדי לגשת לשירותים של Google Cloud .

במדריך הזה תלמדו איך:

מוסיפים את התלויות הנדרשות של ספריית האימות לפרויקט באמצעות Maven,‏ Gradle או Simple Build Tool ‏ (SBT).
אימות באמצעות שיטות שונות, עם דגש על Application Default Credentials‏ (ADC).
הגדרת תרחישי אימות מתקדמים, כולל איחוד שירותי אימות הזהות של עומסי עבודה, איחוד שירותי אימות הזהות של כוח העבודה והתחזות לחשבון שירות.
ליצור ולהשתמש בטוקנים עם הרשאות מצומצמות כדי להגביל את ההרשאות.
שילוב פרטי כניסה עם ספריות לקוח HTTP של Google.

המסמכים האלה מיועדים למפתחי Java. פרטים מלאים על ה-API זמינים במסמכי התיעוד של Google Auth Library API.

‫Google Auth Library for Java מורכבת מארבעה ארטיפקטים:

‫google-auth-library-credentials מכיל מחלקות בסיסיות וממשקים לפרטי הכניסה של Google.
‫google-auth-library-appengine מכיל פרטי כניסה ל-App Engine ותלוי ב-SDK של App Engine.
‫google-auth-library-oauth2-http מכיל מגוון של פרטי כניסה ושיטות עזר, כולל יכולות לקבל פרטי כניסה שמוגדרים כברירת מחדל לאפליקציה. הוא מספק גם את הגישה בצד השרת ליצירת אסימונים עם היקף הרשאות מצומצם.
‫google-auth-library-cab-token-generator מסביר איך ליצור אסימונים עם היקף מצומצם בצד הלקוח.

אימות ההגדרות האישיות של פרטי הכניסה

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

מידע נוסף זמין במאמר בנושא אישורים ממקור חיצוני. Default Credentials.

ייבוא של ספריית האימות

כדי לייבא את ספריית האימות, משתמשים ב-com.google.cloud:libraries-bom או ב-Google Auth Library מפרט חומרים (BoM) עם Maven או Gradle.

ספריות Java SDK-bom

כדי לבצע אימות לספריית לקוח ב-Java SDK (לדוגמה, google-cloud-datastore) באמצעות ספריית האימות, משתמשים ב-libraries-bom, שימשוך את הגרסאות של ספריית האימות שתואמות לספריית הלקוח הזו.

לדוגמה, כדי לייבא את ספריית האימות באמצעות Maven באמצעות pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.53.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

אם אתם לא משתמשים ב-libraries-bom או בספריות לקוח אחרות, ייבאו את מודולי האימות ישירות באמצעות Google Auth Library מפרט חומרים (BoM).

מפרט החומרים (BoM) של ספריית האימות של Google

אתם יכולים להשתמש ב-Google Auth Library מפרט חומרים (BoM) כדי לוודא שתואמות התלות הטרנזיטיביות הרלוונטיות והמודולים של אימות.

Maven

מוסיפים לקובץ pom.xml את הנתונים הבאים:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.auth</groupId>
      <artifactId>google-auth-library-bom</artifactId>
      <version>1.30.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

בקטע <dependencies>, אפשר לציין את כל מודולי האימות שנדרשים. לדוגמה, כדי לכלול את המודול google-auth-library-oauth2-http מוסיפים את הפריט <dependency> הבא:

<dependency>
  <groupId>com.google.auth</groupId>
  <!-- Let the BOM manage the module and dependency versions -->
  <!-- Replace with the module(s) that are needed -->
  <artifactId>google-auth-library-oauth2-http</artifactId>
</dependency>

מחליפים את google-auth-library-oauth2-http בדוגמה ב-google-auth-library-credentials או ב-google-auth-library-appengine, בהתאם לצרכים של האפליקציה.

Gradle

בדומה ל-Maven, משתמשי Gradle יכולים להשתמש ב-google-auth-library-bom כדי לנהל גרסאות של יחסי תלות ולהבטיח תאימות בין המודולים השונים של google-auth-library.

כדי להשתמש ב-BOM עם Gradle, מוסיפים את ה-BOM כplatform תלות. לאחר מכן מוסיפים את המודולים של google-auth-library שרוצים. רשימת ה-BOM מבטיחה שגרסאות כל המודולים שבהם אתם משתמשים יהיו תואמות. לדוגמה, מוסיפים לקובץ build.gradle את הנתונים הבאים:

dependencies {
    // The BOM will manage the module versions and transitive dependencies
    implementation platform('com.google.auth:google-auth-library-bom:1.30.1')
    // Replace with the module(s) that are needed
    implementation 'com.google.auth:google-auth-library-oauth2-http'
}

Scala

שלא כמו Maven ו-Gradle, ‏ SBT (Scala Build Tool) לא תומך ב-Maven Bills of Materials (BOMs). לכן, כשמשתמשים ב-Scala, אי אפשר לייבא את google-auth-library-bom כדי לטפל באופן אוטומטי בגרסאות תואמות של מודולי ספריית האימות והתלות הטרנזיטיבית שלהם.

במקום זאת, תצטרכו להוסיף כל מודול משנה נדרש ישירות לקובץ build.sbt. חשוב מאוד לציין במפורש את הגרסאות של כל המודולים google-auth-library שבהם אתם משתמשים, ולוודא שהן תואמות. אם לא תדאגו שהגרסאות יהיו עקביות, עלולים להיווצר קונפליקטים בין גרסאות של יחסי תלות טרנזיטיביים, וזה עלול לגרום להתנהגות לא צפויה או לשגיאות בזמן הריצה באפליקציה.

אם משתמשים ב-SBT, מוסיפים את הקוד הבא ליחסי התלות:

// Replace this with the implementation module that suits your needs
libraryDependencies += "com.google.auth" % "google-auth-library-oauth2-http" % "1.30.1"

רישום ביומן של ספריית האימות

ב-Java Auth Library מומלץ להתחבר באמצעות רישום באגים בספריית לקוח. בניפוי הבאגים של הרישום ביומן, הטוקנים הרגישים (למשל access_token, ‏ refresh_token וכו') יעברו גיבוב והערכים יוסתרו. הרישום ביומן באמצעות java.util.logging מושבת בספריית האימות כדי למנוע דליפה של אסימונים רגישים.

הפונקציונליות של רישום מפורט (verbose) של הלקוח ביומן היא אופציונלית ודורשת הגדרה.

רישום ביומן לצורך ניפוי באגים יכול לרשום את הפעולות הבאות בהתאם לרמת היומן:

מידע על הבקשה: כותרות, כתובת URL, שיטה (רמת מידע)
פרטי התגובה: כותרות, סטטוס, הודעה (רמת מידע)
מטען ייעודי (payload) של התגובה (רמת ניפוי באגים)

העברה מ-`GoogleCredential` אל `GoogleCredentials`

‫GoogleCredential מ-google-api-java-client הוצא משימוש ומומלץ להשתמש ב-GoogleCredentials במקומו.

יצירת מופע של GoogleCredentials באמצעות Application Default Credentials ‏ (ADC). זו הגישה המומלצת:

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

אופן השימוש ב-GoogleCredentials משתנה בהתאם לספריית הלקוח:

ספריות לקוח של Cloud: הספריות האלה משתמשות באופן אוטומטי ב-Application Default Credentials ‏ (ADC), כך שלא צריך לספק פרטי כניסה בקוד.
ספריות לקוח של Google API: צריך ליצור מופע של GoogleCredentials ולהעביר אותו ללקוח. דוגמה מופיעה במדריך ללקוח Google API Java.

Application Default Credentials

‫Google Auth Library מספקת הטמעה של Application Default Credentials ‏ (ADC) ל-Java. ‫ADC מספקת דרך לקבל פרטי כניסה להרשאה כדי לבצע קריאות לממשקי Google API.

כדאי להשתמש ב-ADC כשהאפליקציה שלכם דורשת זהות עקבית ורמת הרשאה, ללא קשר למשתמש. מומלץ להשתמש ב-ADC כדי לאשר קריאות ל-Cloud APIs, במיוחד כשמפתחים אפליקציות ב- Google Cloud.

‫ADC תומך גם באיחוד שירותי אימות הזהות של עומסי עבודה, שמאפשר לאפליקציות לגשת למשאבי Google Cloud פלטפורמות חיצוניות כמו Amazon Web Services ‏ (AWS),‏ Microsoft Azure או כל ספק זהויות שתומך ב-OpenID Connect ‏ (OIDC). אנחנו ממליצים על איחוד שירותי אימות הזהות של עומסי עבודה בסביבות שאינןGoogle Cloud , כי הוא מבטל את הצורך להוריד, לנהל ולאחסן באופן מקומי מפתחות פרטיים של חשבונות שירות.

קבלת Application Default Credentials

כדי לקבל Application Default Credentials, משתמשים ב-GoogleCredentials.getApplicationDefault() או ב-GoogleCredentials.getApplicationDefault(HttpTransportFactory). השיטות האלה מחזירות Application Default Credentials כדי לזהות את האפליקציה כולה ולאשר את הגישה שלה.

החיפוש של Application Default Credentials מתבצע בסדר הבא:

קובץ פרטי הכניסה שמשתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS מפנה אליו.
פרטי הכניסה שסופקו על ידי הפקודה gcloud auth application-default login של Google Cloud SDK.
פרטי הכניסה המובנים של Google App Engine.
Google Cloud פרטי כניסה מובנים ב-Shell.
פרטי כניסה מובנים של Google Compute Engine.
- כדי לדלג על הבדיקה הזו, מגדירים את משתנה הסביבה NO_GCE_CHECK=true.
- כדי להתאים אישית את כתובת שרת המטא-נתונים, מגדירים את משתנה הסביבה GCE_METADATA_HOST=<hostname>.

טעינה מפורשת של פרטי כניסה

כדי לקבל פרטי כניסה ממפתח JSON של חשבון שירות, משתמשים ב-GoogleCredentials.fromStream(InputStream) או ב-GoogleCredentials.fromStream(InputStream, HttpTransportFactory), כמו שמוצג בדוגמת הקוד הבאה.

צריך לרענן את פרטי הכניסה לפני שאפשר להשתמש בטוקן הגישה.

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));
credentials.refreshIfExpired();
AccessToken token = credentials.getAccessToken();
// OR
AccessToken token = credentials.refreshAccessToken();

פרטי כניסה של התחזות

משתמשים ב-ImpersonatedCredentials כדי לאפשר לפרטי כניסה (החשבון הראשי) להתחזות לחשבון שירות (היעד). כך לחשבון המשתמש יש גישה למשאבים בתור היעד, בלי צורך במפתח הפרטי של היעד.

כדי להשתמש ב-ImpersonatedCredentials, צריך לעמוד בדרישות הבאות:

בפרויקט של חשבון המשתמש צריך להיות מופעל ה-API של IAMCredentials.
לחשבון המשתמש צריכים להיות הרשאות של תפקיד Service Account Token Creator (ניהול זהויות והרשאות גישה) בחשבון השירות שאליו מתחברים.

בדוגמת הקוד הבאה נוצר ImpersonatedCredentials. פרטי הכניסה של חשבון המשתמש מתקבלים מ-Application Default Credentials‏ (ADC). אחרי כן, משתמשים בImpersonatedCredentials שמתקבלים כדי לגשת ל-Google Cloud Storage בתור חשבון השירות של היעד.

// The principal (ADC) has the Service Account Token Creator role on the target service account.
GoogleCredentials sourceCredentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/iam"));

ImpersonatedCredentials credentials =
    ImpersonatedCredentials.newBuilder()
        .setSourceCredentials(sourceCredentials)
        .setTargetPrincipal(
            "impersonated-account@project.iam.gserviceaccount.com")
        .setScopes(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"))
        .build();

Storage storage =
    StorageOptions.newBuilder().setProjectId("project-id").setCredentials(credentials).build()
        .getService();

for (Bucket b : storage.list().iterateAll()) {
  System.out.println(b);
}

איחוד שירותי אימות הזהות של עומסי עבודה

איחוד שירותי אימות הזהות של עומסי עבודה מאפשר לאפליקציה שלכם לגשת למשאבים מ-Amazon Web Services ‏ (AWS), מ-Microsoft Azure או מכל ספק זהויות שתומך ב-OpenID Connect ‏ (OIDC). Google Cloud

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

גישה למשאבים מ-AWS

כדי לגשת למשאבים של Google Cloud מ-Amazon Web Services‏ (AWS), צריך קודם להגדיר איחוד שירותי אימות הזהות של עומסי עבודה. תהליך ההגדרה מפורט במאמר גישה למשאבים מ-AWS.

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

# Generate an AWS configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --aws \
    --output-file /path/to/generated/config.json

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
‫POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה.
‫AWS_PROVIDER_ID: מזהה הספק ב-AWS.
‫SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שרוצים להתחזות אליו.

בדוגמה הזו, קובץ התצורה נוצר בקובץ הפלט שצוין.

אם אתם משתמשים ב-AWS IMDSv2, אתם צריכים להוסיף את הדגל --enable-imdsv2 לפקודה gcloud iam workload-identity-pools create-cred-config:

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/AWS_PROVIDER_ID \
    --service-account SERVICE_ACCOUNT_EMAIL \
    --aws \
    --output-file /path/to/generated/config.json \
    --enable-imdsv2

עכשיו אפשר להשתמש בספריית האימות כדי לקרוא למשאביGoogle Cloud מ-AWS.

גישה למשאבים מ-Microsoft Azure

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

# Generate an Azure configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AZURE_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --azure \
    --output-file /path/to/generated/config.json

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
‫POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה.
‫AZURE_PROVIDER_ID: מזהה הספק ב-Azure.
‫SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שרוצים להתחזות אליו.

הפקודה הזו יוצרת את קובץ התצורה בקובץ הפלט שצוין.

עכשיו אפשר להשתמש בספריית האימות כדי לקרוא למשאבים של Azure. Google Cloud

איך ניגשים למשאבים מספק זהויות מסוג OIDC

כדי לגשת למשאבי Google Cloud ספק זהויות שתומך ב-OpenID Connect‏ (OIDC), צריך קודם להגדיר איחוד שירותי אימות הזהות של עומסי עבודה, כמו שמתואר במאמר הגדרת איחוד שירותי אימות הזהות של עומסי עבודה מספק זהויות מסוג OIDC.

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

בספקי OIDC, ספריית האימות יכולה לאחזר אסימוני OIDC מקובץ מקומי (פרטי כניסה שהתקבלו מקובץ), משרת מקומי (פרטי כניסה שהתקבלו מכתובת URL) או משילוב של אישור X.509 ומפתח פרטי (פרטי כניסה שהתקבלו מאישור X.509).

פרטי כניסה שהתקבלו מקובץ

במקרה של פרטי כניסה שמקורם בקובץ, תהליך ברקע צריך לרענן באופן רציף את מיקום הקובץ באמצעות אסימון OIDC חדש לפני שיפוג התוקף. אם משך החיים של האסימון הוא שעה אחת, צריך לעדכן את האסימון בקובץ כל שעה. אפשר לאחסן את האסימון ישירות כטקסט פשוט או בפורמט JSON.

כדי ליצור קובץ תצורה של OIDC, מריצים את הפקודה הבאה:

# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-file <var>PATH_TO_OIDC_ID_TOKEN</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
‫POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה.
‫OIDC_PROVIDER_ID: מזהה ספק OIDC.
‫SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שרוצים להתחזות אליו.
‫PATH_TO_OIDC_ID_TOKEN: הנתיב שמשמש לאחזור אסימון OIDC.

הפקודה הזו יוצרת את קובץ התצורה בקובץ הפלט שצוין.

פרטי כניסה שהתקבלו מכתובת URL

במקרה של פרטי כניסה שמקורם בכתובת URL, שרת מקומי צריך לארח נקודת קצה מסוג GET שמספקת אסימון OIDC בפורמט טקסט פשוט או JSON. אם נקודת הקצה דורשת זאת, אפשר לציין כותרות HTTP נוספות לשליחה בבקשת האסימון.

כדי ליצור הגדרת זהות של עומס עבודה ב-OIDC שמבוססת על כתובת URL, מריצים את הפקודה הבאה:

# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-url <var>URL_TO_GET_OIDC_TOKEN</var> \
    --credential-source-headers <var>HEADER_KEY=HEADER_VALUE</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
‫POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה.
‫OIDC_PROVIDER_ID: מזהה ספק OIDC.
‫SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שרוצים להתחזות אליו.
‫URL_TO_GET_OIDC_TOKEN: כתובת ה-URL של נקודת הקצה של השרת המקומי שמפעילים כדי לאחזר את אסימון OIDC.
‫HEADER_KEY ו-HEADER_VALUE: צמדי מפתח/ערך נוספים של כותרות שיועברו עם בקשת ה-GET אל URL_TO_GET_OIDC_TOKEN, לדוגמה Metadata-Flavor=Google.

עכשיו אפשר להשתמש בספריית האימות כדי לקרוא למשאביGoogle Cloud מספק OIDC.

גישה למשאבים באמצעות פרטי כניסה שהתקבלו מאישור X.509

במקרה של פרטי כניסה שמקורם באישור X.509, ספריית האימות משתמשת באישור X.509 ובמפתח פרטי כדי להוכיח את הזהות של האפליקציה. אישורי X.509 כוללים תאריך תפוגה, וצריך לחדש אותם לפני שהתוקף שלהם פג כדי לשמור על הגישה.

מידע נוסף זמין במסמכי התיעוד הרשמיים.

יצירת קובצי תצורה לאיחוד X.509

כדי להגדיר פרטי כניסה שמקורם באישור X.509, יוצרים שני קבצים נפרדים: קובץ תצורה ראשי של פרטי הכניסה וקובץ תצורה של האישור.

קובץ התצורה של פרטי הכניסה הראשיים מכיל את המטא-נתונים הדרושים לאימות. הקובץ הזה מפנה גם לקובץ ההגדרות של האישור.
בקובץ התצורה של האישור מצוינים נתיבי הקבצים של אישור X.509, המפתח הפרטי ושרשרת האמון.

אפשר להשתמש בפקודה gcloud iam workload-identity-pools create-cred-config כדי ליצור את שניהם.

המיקום שבו gcloud יוצר את קובץ ההגדרות של האישור תלוי בשאלה אם משתמשים בדגל --credential-cert-configuration-output-file.

התנהגות ברירת מחדל (מומלץ)

אם לא מציינים את הדגל --credential-cert-configuration-output-file, הפקודה gcloud יוצרת את קובץ ההגדרה של האישור במיקום ברירת מחדל מוכר, שספריית האימות יכולה לגלות באופן אוטומטי. הגישה הזו מתאימה לרוב תרחישי השימוש. שם קובץ התצורה של פרטי הכניסה שמוגדר כברירת מחדל הוא config.json, ושם קובץ התצורה של האישור שמוגדר כברירת מחדל הוא certificate_config.json.

לדוגמה, מריצים את הפקודה הבאה כדי ליצור את קובצי התצורה באמצעות התנהגות ברירת המחדל:

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --output-file /path/to/config.json

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
‫POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה.
‫PROVIDER_ID: מזהה הספק.
‫SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שרוצים להתחזות אליו.
‫PATH_TO_CERTIFICATE: הנתיב שבו נמצא אישור X.509 מסוג leaf.
‫PATH_TO_PRIVATE_KEY: הנתיב שבו נמצא המפתח הפרטי התואם לאישור העלה.
‫PATH_TO_TRUST_CHAIN: הנתיב של קובץ שרשרת האמון של אישור X.509. הקובץ צריך להיות קובץ בפורמט PEM שמכיל את כל אישורי הביניים שנדרשים להשלמת שרשרת האמון בין אישור הקצה לבין מאגר האישורים שהוגדר במאגר איחוד הזהויות של עומסי עבודה. האישור המשני הוא אופציונלי בקובץ הזה.

הפקודה הזו מניבה את התוצאה הבאה:

‫/path/to/config.json: נוצר בנתיב שציינתם. הקובץ הזה יכיל את הערך "use_default_certificate_config": true כדי להנחות את הלקוחות לחפש את הגדרות התצורה של האישור בנתיב ברירת המחדל.
‫certificate_config.json: נוצר בנתיב ברירת המחדל של ההגדרה של Google Cloud CLI, שבדרך כלל הוא ~/.config/gcloud/certificate_config.json ב-Linux וב-macOS, או %APPDATA%\gcloud\certificate_config.json ב-Windows.

התנהגות של מיקום מותאם אישית

אם אתם צריכים לאחסן את קובץ ההגדרות של האישור במיקום שאינו ברירת המחדל, השתמשו בדגל --credential-cert-configuration-output-file.

פקודה לדוגמה (מיקום בהתאמה אישית):

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --credential-cert-configuration-output-file "/custom/path/cert_config.json" \
    --output-file /path/to/config.json

הפקודה הזו מניבה את התוצאה הבאה:

‫/path/to/config.json: נוצר בנתיב שציינתם. הקובץ הזה יכיל שדה "certificate_config_location" שמפנה לנתיב המותאם אישית.
‫cert_config.json: נוצר ב-/custom/path/cert_config.json, כפי שמצוין בדגל.

עכשיו אפשר להשתמש בספריית האימות כדי לקרוא למשאביGoogle Cloud באמצעות פרטי כניסה שמקורם באישור X.509.

שימוש בפרטי כניסה שהתקבלו מקובץ הפעלה עם OIDC ו-SAML

בפרטי כניסה שהתקבלו מקובץ הפעלה, נעשה שימוש בקובץ הפעלה מקומי כדי לאחזר את האסימון של צד שלישי. קובץ ההפעלה צריך לספק ל-stdout אסימון מזהה של OIDC או טענת נכוֹנוּת של SAML תקינים ותקפים בפורמט JSON.

כדי להשתמש בפרטי הכניסה שהתקבלו מקובץ הפעלה, צריך להגדיר את משתנה הסביבה GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES לערך 1.

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

# Generate a configuration file for executable-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account=<var>SERVICE_ACCOUNT_EMAIL</var> \
    --subject-token-type=<var>SUBJECT_TOKEN_TYPE</var> \
    # The absolute path for the program, including arguments.
    # e.g. --executable-command="/path/to/command --foo=bar"
    --executable-command=<var>EXECUTABLE_COMMAND</var> \
    # Optional argument for the executable timeout. Defaults to 30s.
    # --executable-timeout-millis=<var>EXECUTABLE_TIMEOUT</var> \
    # Optional argument for the absolute path to the executable output file.
    # See below on how this argument impacts the library behaviour.
    # --executable-output-file=<var>EXECUTABLE_OUTPUT_FILE</var> \
    --output-file /path/to/generated/config.json

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
‫POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה.
‫PROVIDER_ID: מזהה ספק OIDC או SAML.
‫SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שרוצים להתחזות אליו.
‫SUBJECT_TOKEN_TYPE: סוג אסימון הנושא.
‫EXECUTABLE_COMMAND: הפקודה המלאה שמריצים, כולל ארגומנטים. חייב להיות נתיב מוחלט לתוכנית.

הדגל --executable-timeout-millis הוא אופציונלי. הוא מציין את משך הזמן (באלפיות השנייה) שספריית האימות תמתין עד שקובץ ההפעלה יסיים את הפעולה. אם לא תציינו ערך, ברירת המחדל היא 30 שניות. הערך המקסימלי המותר הוא שתי דקות, והמינימלי הוא חמש שניות.

הדגל האופציונלי --executable-output-file מציין נתיב לשמירת תגובת פרטי הכניסה של צד שלישי שנוצרה על ידי קובץ ההפעלה. הוספה של קובץ למטמון עוזרת לשפר את הביצועים, כי ספריות האימות בודקות קודם אם יש בקובץ הזה פרטי כניסה תקפים שלא פג תוקפם לפני שהן מריצות את קובץ ההפעלה. אם קיימים פרטי כניסה תקינים במטמון, הספריות משתמשות בהם, וכך נמנעות הרצות מיותרות של קובץ ההפעלה.

קובץ ההפעלה צריך לכתוב את תגובת האישורים לקובץ הזה. ספריות האימות קוראות רק מהמיקום הזה. התוכן של הקובץ צריך להיות בפורמט JSON הצפוי.

כדי לאחזר את האסימון של הצד השלישי, הספרייה תריץ את קובץ ההפעלה באמצעות הפקודה שצוינה. הפלט של קובץ ההפעלה חייב להיות בפורמט התגובה שמופיע בדוגמאות הבאות, והוא צריך להפיק את התגובה ל-stdout.

זוהי דוגמה לתשובה של OIDC שניתן להפעיל:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

זוהי דוגמה לתגובת SAML שניתן להפעיל:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

כשמציינים קובץ פלט באמצעות הארגומנט --executable-output-file בתצורת פרטי הכניסה, תגובות מוצלחות של קובץ הפעלה חייבות לכלול שדה expiration_time. כך ספריית האימות יכולה לשמור במטמון ולנהל ביעילות את תוקף פרטי הכניסה שמאוחסנים בקובץ הזה.

דוגמה לתשובת שגיאה של קובץ הפעלה:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

כל השדות האלה הם שדות חובה לתגובת שגיאה. הספרייה משתמשת בשדות code ו-message כחלק מהחריגה שהופעלה.

סיכום השדות של פורמט התגובה: * version: הגרסה של פלט ה-JSON. יש תמיכה רק בגרסה 1. ‫* success: אם הערך הוא true, התגובה חייבת לכלול את האסימון של צד שלישי ואת סוג האסימון. אם צוין קובץ פלט בהגדרת פרטי הכניסה, התשובה צריכה לכלול גם את השדה expiration_time. קובץ ההפעלה צריך לצאת עם קוד יציאה 0. כשהערך הוא false, התגובה חייבת לכלול את השדות של קוד השגיאה וההודעה, ולצאת באמצעות ערך שהוא לא אפס. * ‫token_type: בשדה הזה מציינים את סוג אסימון הנושא של צד שלישי. הערך חייב להיות urn:ietf:params:oauth:token-type:jwt,‏ urn:ietf:params:oauth:token-type:id_token או urn:ietf:params:oauth:token-type:saml2. * ‫id_token: אסימון OIDC של צד שלישי. * ‫saml_response: תגובת SAML של הצד השלישי. ‫* expiration_time: זמן התפוגה של אסימון הנושא של הצד השלישי בשניות (ראשית זמן יוניקס [Unix epoch]). * code: מחרוזת קוד השגיאה. * message: הודעת השגיאה.

כל סוגי התגובות חייבים לכלול את השדות version ו-success. * תגובות מוצלחות חייבות לכלול את token_type ואחד מהערכים id_token או saml_response. השדה expiration_time צריך להופיע גם אם צוין קובץ פלט בתצורת פרטי הכניסה. * תגובות שגיאה חייבות לכלול את השדות code ו-message.

הספרייה מאכלסת את משתני הסביבה האלה כשהיא מריצה את קובץ ההפעלה:

‫GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: שדה הקהל מתוך תצורת פרטי הכניסה. מוצג תמיד.
GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: סוג אסימון הנושא הצפוי. מוצג תמיד.
‫GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: כתובת האימייל של חשבון השירות. מוצג רק כשמשתמשים בהתחזות לחשבון שירות.
‫GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: המיקום של קובץ הפלט בתצורה של פרטי הכניסה. מוצג רק כשהוא מצוין בתצורה של פרטי הכניסה.

קובץ ההפעלה יכול להשתמש במשתני הסביבה כדי להימנע מכתיבה בתוך הקוד של הערכים האלה.

שיקולי אבטחה

מומלץ לפעול לפי שיטות האבטחה הבאות:

למנוע הפעלה של קובץ ההפעלה על ידי תהליכים לא רצויים, כי הוא יוציא פרטי כניסה רגישים לתהליכים האלה ולמשתמשים שלהם דרך stdout.
למנוע מתהליכים לא רצויים לשנות את ההגדרה או את ההפעלה של קובץ ההפעלה.

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

עכשיו אפשר להשתמש בספריית האימות כדי לקרוא למשאביGoogle Cloud מספק OIDC או SAML.

שימוש בספק בהתאמה אישית עם OIDC ו-SAML

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

IdentityPoolCredentials לא שומרים במטמון את האסימון שמוחזר, ולכן צריך להטמיע לוגיקה של שמירה במטמון בספק האסימונים כדי למנוע שליחת בקשות מרובות לאותו אסימון נושא.

import java.io.IOException;

public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {

  @Override
  public String getSubjectToken(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience and subject token type.
    string audience = context.getAudience();
    string tokenType = context.getSubjectTokenType();

    try {
      // Return a valid, unexpired token for the requested audience and token type.
      // Note that IdentityPoolCredentials don't cache the subject token so
      // any caching logic needs to be implemented in the token supplier.
      return retrieveToken(audience, tokenType);
    } catch (Exception e) {
      // If token is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private String retrieveToken(string tokenType, string audience) {
    // Retrieve a subject token of the requested type for the requested audience.
  }
}

CustomTokenSupplier tokenSupplier = new CustomTokenSupplier();
IdentityPoolCredentials identityPoolCredentials =
    IdentityPoolCredentials.newBuilder()
        .setSubjectTokenSupplier(tokenSupplier) // Sets the token supplier.
        .setAudience(...) // Sets the Google Cloud audience.
        .setSubjectTokenType(SubjectTokenTypes.JWT) // Sets the subject token type.
        .build();

איפה הקהל נמצא:

//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
‫WORKLOAD_POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה.
‫PROVIDER_ID: מזהה הספק.

אפשר גם ליצור קובץ הגדרות אישיות של פרטי כניסה באמצעות ה-CLI של gcloud כדי למצוא את הערכים של קהל, כתובת URL להתחזות לחשבון שירות וכל שדה אחר של builder.

שימוש בספק מותאם אישית עם AWS

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

AwsCredentials לא לשמור במטמון את פרטי האבטחה או האזור של AWS שמוחזרים, ולכן צריך להטמיע לוגיקה של שמירה במטמון אצל הספק כדי למנוע בקשות מרובות לאותם משאבים.

class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
  @Override
  AwsSecurityCredentials getAwsSecurityCredentials(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience.
    String audience = context.getAudience();

    try {
      // Return valid, unexpired AWS security credentials for the requested audience.
      // Note that AwsCredentials don't cache the AWS security credentials so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsSecurityCredentials(audience);
    } catch (Exception e) {
      // If credentials are unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  @Override
  String getRegion(ExternalAccountSupplierContext context) throws IOException {
    try {
      // Return a valid AWS region. i.e. "us-east-2".
      // Note that AwsCredentials don't cache the region so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsRegion();
    } catch (Exception e) {
      // If region is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private AwsSecurityCredentials retrieveAwsSecurityCredentials(string audience) {
    // Retrieve Aws security credentials for the requested audience.
  }

  private String retrieveAwsRegion() {
    // Retrieve current AWS region.
  }
}

CustomAwsSupplier awsSupplier = new CustomAwsSupplier();
AwsCredentials credentials = AwsCredentials.newBuilder()
    .setSubjectTokenType(SubjectTokenTypes.AWS4) // Sets the subject token type.
    .setAudience(...) // Sets the Google Cloud audience.
    .setAwsSecurityCredentialsSupplier(supplier) // Sets the supplier.
    .build();

כאשר הקהל הוא: //iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
‫WORKLOAD_POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה.
‫PROVIDER_ID: מזהה הספק.

משך החיים של הטוקן ניתן להגדרה

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

כדי ליצור את ההגדרה עם תוחלת חיים של טוקן שאפשר להגדיר, מריצים את הפקודה הבאה (בדוגמה הזו נעשה שימוש בהגדרת AWS, אבל אפשר להגדיר את תוחלת החיים של הטוקן לכל ספקי איחוד הזהויות של עומסי עבודה):

  # Generate an AWS configuration file with configurable token lifetime.
  gcloud iam workload-identity-pools create-cred-config \
      projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
      --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
      --aws \
      --output-file /path/to/generated/config.json \
      --service-account-token-lifetime-seconds <var>TOKEN_LIFETIME</var>

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
‫POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה.
‫AWS_PROVIDER_ID: מזהה הספק ב-AWS.
‫SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שרוצים להתחזות אליו.
‫TOKEN_LIFETIME: משך החיים שנבחר של אסימון הגישה לחשבון השירות בשניות.

הדגל service-account-token-lifetime-seconds הוא אופציונלי. אם לא מציינים ערך, ברירת המחדל היא שעה. הערך המינימלי המותר הוא 600 (10 דקות) והערך המקסימלי המותר הוא 43,200 (12 שעות). אם אתם צריכים משך חיים ארוך יותר משעה אחת, אתם צריכים להוסיף את חשבון השירות כערך מותר בשירות מדיניות הארגון שמחיל את האילוץ constraints/iam.allowServiceAccountCredentialLifetimeExtension.

הגדרת משך חיים קצר (לדוגמה, 10 דקות) גורמת לספרייה להתחיל את כל תהליך החלפת האסימונים כל 10 דקות. הפעולה הזו קוראת לספק האסימונים של הצד השלישי גם אם תוקף האסימון של הצד השלישי לא פג.

שימוש בפרטי כניסה של משתמשים מורשים בכוח העבודה בחשבון חיצוני

פרטי כניסה של משתמש מורשה בחשבון חיצוני מאפשרים לכם להיכנס באמצעות דפדפן אינטרנט לחשבון של ספק זהויות חיצוני באמצעות CLI של gcloud וליצור הגדרה לשימוש בספריית האימות.

כדי ליצור הגדרת זהות של כוח עבודה של משתמש מורשה בחשבון חיצוני, מריצים את הפקודה הבאה:

gcloud auth application-default login --login-config=LOGIN_CONFIG

כאשר צריך להחליף את המשתנה הבא:

‫LOGIN_CONFIG: קובץ הגדרות הכניסה שנוצר באמצעות Google Cloud console או gcloud iam workforce-pools create-login-config

ייפתח תהליך בדפדפן שדרכו תוכלו להיכנס באמצעות ספק הזהויות מצד שלישי שהגדרתם. לאחר מכן, המערכת שומרת את ההגדרה של המשתמש המורשה בחשבון החיצוני במיקום הידוע של ADC.

ספריית האימות תשתמש באסימון הרענון שסופק מההגדרה כדי ליצור ולרענן אסימון גישה לקריאה לשירותים של Google Cloud .

משך החיים שמוגדר כברירת מחדל לאסימון הרענון הוא שעה אחת. אחרי זה, צריך ליצור הגדרה חדשה באמצעות ה-CLI של gcloud. אפשר לשנות את משך החיים של המאגר על ידי שינוי משך הסשן של מאגר כוח העבודה, ואפשר להגדיר אותו עד 12 שעות.

שימוש בזהויות חיצוניות

אפשר להשתמש בזהויות חיצוניות עם Application Default Credentials. כדי להשתמש בזהויות חיצוניות עם Application Default Credentials, צריך ליצור את קובץ ההגדרות של פרטי הכניסה בפורמט JSON עבור הזהות החיצונית, כמו שמתואר בקטע איחוד זהויות של עומסי עבודה. אחרי שיוצרים את הקובץ, מאחסנים את הנתיב שלו במשתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json

עכשיו הספרייה יכולה לבחור את סוג הלקוח הנכון ולאתחל את פרטי הכניסה מההקשר שקובץ ההגדרות מספק.

GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault();

String projectId = "your-project-id";
String url = "https://storage.googleapis.com/storage/v1/b?project=" + projectId;

HttpCredentialsAdapter credentialsAdapter = new HttpCredentialsAdapter(googleCredentials);
HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credentialsAdapter);
HttpRequest request = requestFactory.buildGetRequest(new GenericUrl(url));

JsonObjectParser parser = new JsonObjectParser(GsonFactory.getDefaultInstance());
request.setParser(parser);

HttpResponse response = request.execute();
System.out.println(response.parseAsString());

אפשר גם לאתחל במפורש לקוחות של חשבונות חיצוניים באמצעות קובץ ההגדרות שנוצר.

ExternalAccountCredentials credentials =
    ExternalAccountCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));

שיקולי אבטחה

הספרייה הזו לא מבצעת אימות של השדות token_url,‏ token_info_url או service_account_impersonation_url בהגדרות של פרטי הכניסה. אנחנו לא ממליצים להשתמש בהגדרת פרטי כניסה שלא נוצרה באמצעות ה-CLI של gcloud, אלא אם אתם מוודאים ששדות כתובות האתרים מפנים לדומיין googleapis.com.

צמצום היקף ההרשאות באמצעות גבולות הגישה לפרטי כניסה

צמצום ההרשאות באמצעות גבולות גישה לפרטי כניסה מאפשר להגביל את ההרשאות שניתנות ב-IAM (הכלי לניהול זהויות והרשאות גישה) לפרטי כניסה עם תוקף קצר ב-Cloud Storage. התהליך כולל יצירה של CredentialAccessBoundary שמגדיר את ההגבלות שחלות על האסימון בהיקף מצומצם. שימוש בהרשאות עם היקף מצומצם מבטיח שלאסימונים שנמצאים בתהליך תמיד יהיו הרשאות מינימליות. העיקרון של הרשאות מינימליות

יצירת `CredentialAccessBoundary`

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

בקטע הקוד הבא אפשר לראות איך מאתחלים CredentialAccessBoundary עם AccessBoundaryRule אחד. הכלל הזה מציין שלאסימון המצומצם תהיה גישת קריאה בלבד לאובייקטים שמתחילים ב-customer-a בקטגוריה bucket-123.

// Create the AccessBoundaryRule.
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
        CredentialAccessBoundary.AccessBoundaryRule.AvailabilityCondition.newBuilder().setExpression(expression).build())
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

דפוס שימוש נפוץ

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

יצירת טוקנים עם הרשאות מצומצמות

יש שתי דרכים ליצור אסימונים עם היקף מצומצם באמצעות CredentialAccessBoundary:

בצד השרת (באמצעות DownscopedCredentials): הלקוח קורא ל-Security Token Service ‏ (STS) בכל פעם שנדרש טוקן עם הרשאות מוגבלות. האפשרות הזו מתאימה לאפליקציות שבהן כללי גבולות הגישה לפרטי הכניסה משתנים לעיתים רחוקות, או לאפליקציות שבהן נעשה שימוש חוזר הרבה פעמים בפרטי כניסה מצומצמים יחידים. שיקול חשוב הוא שכל שינוי בכלל מחייב לבצע קריאה חדשה ל-STS. הגישה הזו זמינה בספריית google-auth-library-oauth2-http ולא נדרשים פריטים נוספים בקשרי תלות. כך קל יותר לבצע אינטגרציה. האפשרות הזו מתאימה אם תרחיש השימוש שלכם לא דורש את היתרונות הספציפיים של הגישה בצד הלקוח.
מצד הלקוח (באמצעות ClientSideCredentialAccessBoundaryFactory): הלקוח מאחזר חומר קריפטוגרפי פעם אחת ואז יוצר באופן מקומי כמה אסימונים עם הרשאות מוגבלות. כך מצמצמים את מספר הפעמים שבהן מתבצעת קריאה ל-STS, והתהליך יעיל יותר כשכללי Credential Access Boundary משתנים לעיתים קרובות, כי הלקוח לא צריך ליצור קשר עם ה-STS בכל פעם שכלל משתנה. השיטה הזו יעילה יותר גם לאפליקציות שצריכות ליצור הרבה אסימונים ייחודיים עם היקף הרשאות מצומצם. הגישה הזו זמינה במודול google-auth-library-cab-token-generator. עם זאת, למודול הזה יש קבוצה משלו של יחסי תלות. התלות הזו יכולה להוסיף מורכבות לפרויקט. כדאי להשתמש בגישה הזו אם חשוב לכם לצמצם את מספר הקריאות ל-STS וליצור הרבה טוקנים ייחודיים. תצטרכו גם לנהל את התלות הנוספת.

CAB בצד השרת

אפשר להשתמש במחלקה DownscopedCredentials כדי ליצור אסימון גישה עם הרשאות מצומצמות מפרטי כניסה של מקור ומ-CredentialAccessBoundary.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the DownscopedCredentials class.
DownscopedCredentials downscopedCredentials =
    DownscopedCredentials.newBuilder()
        .setSourceCredential(sourceCredentials)
        .setCredentialAccessBoundary(CredentialAccessBoundary.newBuilder().addRule(rule).build())
        .build();

// Retrieve the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = downscopedCredentials.refreshAccessToken();

CAB בצד הלקוח

ב-CAB מצד הלקוח, נעשה שימוש ב-ClientSideCredentialAccessBoundaryFactory עם פרטי כניסה של מקור. אחרי שמפעילים את המפעל, אפשר לקרוא לשיטה generateToken() שוב ושוב עם אובייקטים שונים של CredentialAccessBoundary כדי ליצור כמה אסימונים בהיקף מצומצם.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the ClientSideCredentialAccessBoundaryFactory.
ClientSideCredentialAccessBoundaryFactory factory =
    ClientSideCredentialAccessBoundaryFactory.newBuilder()
        .setSourceCredential(sourceCredentials)
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

// Generate the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = factory.generateToken(credentialAccessBoundary);

שימוש באסימוני גישה עם היקף מצומצם

אפשר להגדיר ברוקר של טוקנים בשרת ברשת פרטית. עומסי עבודה שונים (צרכני אסימונים) באותה רשת שולחים בקשות מאומתות לברוקר הזה כדי לקבל אסימונים עם היקף מצומצם. האסימונים האלה מאפשרים להם לגשת לקטגוריות ספציפיות ב-Storage או לשנות אותן. Google Cloud

הברוקר יוצר מופעים של פרטי כניסה עם הרשאות מצומצמות שיכולים ליצור אסימוני גישה עם הרשאות מצומצמות לטווח קצר. לאחר מכן, הוא מעביר את האסימונים האלה לצרכן האסימונים.

צרכן האסימון יכול להשתמש באסימוני הגישה האלה עם היקף מצומצם באמצעות OAuth2Credentials או OAuth2CredentialsWithRefresh. אחר כך תוכלו להשתמש בהרשאה הזו כדי לאתחל מופע של לקוח אחסון כדי לגשת למשאבי אחסון של Google Cloudעם גישה מוגבלת.

// You can pass an `OAuth2RefreshHandler` to `OAuth2CredentialsWithRefresh` that will allow the
// library to seamlessly handle downscoped token refreshes on expiration.
OAuth2CredentialsWithRefresh.OAuth2RefreshHandler handler =
        new OAuth2CredentialsWithRefresh.OAuth2RefreshHandler() {
    @Override
    public AccessToken refreshAccessToken() {
      // Retrieve the token from your Token Broker.
      return accessToken;
    }
};

// The downscoped token is retrieved from the token broker.
AccessToken downscopedToken = handler.refreshAccessToken();

// Build the OAuth2CredentialsWithRefresh from the downscoped token and pass a refresh handler
// to handle token expiration. Passing the original downscoped token or the expiry here is optional,
// because the refresh_handler will generate the downscoped token on demand.
OAuth2CredentialsWithRefresh credentials =
    OAuth2CredentialsWithRefresh.newBuilder()
        .setAccessToken(downscopedToken)
        .setRefreshHandler(handler)
        .build();

// Use the credentials with the Cloud Storage SDK.
StorageOptions options = StorageOptions.newBuilder().setCredentials(credentials).build();
Storage storage = options.getService();

// Call Cloud Storage APIs.
// Because we passed the downscoped credential, we will have limited read-only access to objects
// starting with "customer-a" in bucket "bucket-123".
storage.get(...)

אפשר להשתמש בגבולות גישה לפרטי כניסה רק ב-Cloud Storage, ולא בשירותים האחרים שלGoogle Cloud .

שימוש בפרטי כניסה עם `google-http-client`

אפשר להשתמש בפרטי הכניסה שסופקו על ידי com.google.auth:google-auth-library-oauth2-http עם לקוחות מבוססי-HTTP של Google. לקוחות מבוססי HTTP של Google מספקים HttpCredentialsAdapter שאפשר להשתמש בו כHttpRequestInitializer, הארגומנט האחרון עבור כלי הבנייה שלהם.

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.services.bigquery.Bigquery;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);

Bigquery bq = new Bigquery.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
    .setApplicationName(APPLICATION_NAME)
    .build();

אימות טוקנים של JWT (תכונת בטא)

כדי לאמת טוקן JWT, משתמשים במחלקה TokenVerifier.

אימות חתימה

כדי לאמת חתימה, משתמשים ב-TokenVerifier שמוגדר כברירת מחדל:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder().build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

התאמה אישית של `TokenVerifier`

כדי להתאים אישית TokenVerifier, יוצרים מופע שלו באמצעות ה-builder שלו:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder()
  .setAudience("audience-to-verify")
  .setIssuer("issuer-to-verify")
  .build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

אפשרויות נוספות מפורטות במאמרי העזרה בנושא TokenVerifier.Builder.

`google-auth-library-credentials`

פריט המידע הזה שנוצר בתהליך פיתוח (Artifact) מכיל מחלקות בסיסיות וממשקים של פרטי הכניסה ל-Google:

‫Credentials: זוהי מחלקת הבסיס לזהות מורשית. הטמעות של המחלקה הזו יכולות לאשר את האפליקציה שלכם.
‫RequestMetadataCallback: זה הממשק של הקריאה החוזרת שמקבלת את התוצאה של Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback) האסינכרוני.
‫ServiceAccountSigner: זהו הממשק של חותם חשבון שירות. הטמעות של המחלקה הזו יכולות לחתום על מערכי בייטים באמצעות פרטי הכניסה שמשויכים לחשבון שירות של Google.

`google-auth-library-appengine`

הארטיפקט הזה תלוי ב-App Engine SDK ‏ (appengine-api-1.0-sdk). אפשר להשתמש בו רק באפליקציות שפועלות בסביבות App Engine שמשתמשות ב-urlfetch. המחלקה AppEngineCredentials מאפשרת לכם להעניק הרשאה לאפליקציית App Engine שלכם בהינתן מופע של AppIdentityService.

שימוש:

import com.google.appengine.api.appidentity.AppIdentityService;
import com.google.appengine.api.appidentity.AppIdentityServiceFactory;
import com.google.auth.Credentials;
import com.google.auth.appengine.AppEngineCredentials;

AppIdentityService appIdentityService = AppIdentityServiceFactory.getAppIdentityService();

Credentials credentials =
    AppEngineCredentials.newBuilder()
        .setScopes(...)
        .setAppIdentityService(appIdentityService)
        .build();

google-auth-library-cab-token-generator

המודול הזה מספק את המחלקה ClientSideCredentialAccessBoundaryFactory, שמאפשרת ליצור בצד הלקוח אסימונים עם היקף מצומצם ל-Cloud Storage באמצעות גבולות גישה לפרטי כניסה. הגישה הזו שימושית במיוחד לאפליקציות שנדרשים בהן שינויים תכופים בכללי גבולות הגישה לפרטי הכניסה או ליצירה של הרבה אסימונים ייחודיים עם היקף מצומצם, כי היא מצמצמת את מספר הקריאות לשירות אסימוני האבטחה (STS). דוגמאות לשימוש מופיעות בקטע CAB מצד הלקוח. למודול הזה יש קבוצה משלו של יחסי תלות. כדאי לבדוק אם היתרונות של צמצום היקף ההרשאות בצד הלקוח עולים על המורכבות הנוספת בתרחיש השימוש הספציפי שלכם.

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

סקירה כללית

אימות ההגדרות האישיות של פרטי הכניסה

ייבוא של ספריית האימות

ספריות Java SDK-bom

מפרט החומרים (BoM) של ספריית האימות של Google

Maven

Gradle

Scala

רישום ביומן של ספריית האימות

העברה מ-GoogleCredential אל GoogleCredentials

Application Default Credentials

קבלת Application Default Credentials

טעינה מפורשת של פרטי כניסה

פרטי כניסה של התחזות

איחוד שירותי אימות הזהות של עומסי עבודה

גישה למשאבים מ-AWS

גישה למשאבים מ-Microsoft Azure

איך ניגשים למשאבים מספק זהויות מסוג OIDC

פרטי כניסה שהתקבלו מקובץ

פרטי כניסה שהתקבלו מכתובת URL

גישה למשאבים באמצעות פרטי כניסה שהתקבלו מאישור X.509

יצירת קובצי תצורה לאיחוד X.509

התנהגות ברירת מחדל (מומלץ)

התנהגות של מיקום מותאם אישית

שימוש בפרטי כניסה שהתקבלו מקובץ הפעלה עם OIDC ו-SAML

שיקולי אבטחה

שימוש בספק בהתאמה אישית עם OIDC ו-SAML

שימוש בספק מותאם אישית עם AWS

משך החיים של הטוקן ניתן להגדרה

שימוש בפרטי כניסה של משתמשים מורשים בכוח העבודה בחשבון חיצוני

שימוש בזהויות חיצוניות

שיקולי אבטחה

צמצום היקף ההרשאות באמצעות גבולות הגישה לפרטי כניסה

יצירת CredentialAccessBoundary

דפוס שימוש נפוץ

יצירת טוקנים עם הרשאות מצומצמות

CAB בצד השרת

CAB בצד הלקוח

שימוש באסימוני גישה עם היקף מצומצם

שימוש בפרטי כניסה עם google-http-client

אימות טוקנים של JWT (תכונת בטא)

אימות חתימה

התאמה אישית של TokenVerifier

google-auth-library-credentials

google-auth-library-appengine

google-auth-library-cab-token-generator

תחילת העבודה עם ספריית האימות של Google

העברה מ-`GoogleCredential` אל `GoogleCredentials`

יצירת `CredentialAccessBoundary`

שימוש בפרטי כניסה עם `google-http-client`

התאמה אישית של `TokenVerifier`

`google-auth-library-credentials`

`google-auth-library-appengine`