סקירה כללית
Google Auth Library היא ספריית לקוח לאימות בקוד פתוח ל-Java. במאמר הזה מוסבר איך להשתמש בספרייה הזו כדי לאמת את אפליקציות Java שלכם, כדי שתוכלו לגשת לשירותי Cloud de Confiance by S3NS .
במדריך הזה נסביר איך:
- מוסיפים לפרויקט את יחסי התלות הנדרשים של ספריית Google Auth באמצעות Maven, Gradle או Simple Build Tool (SBT).
- אימות באמצעות שיטות שונות, תוך התמקדות ב-Application Default Credentials (ADC).
- להגדיר תרחישי אימות מתקדמים, כולל איחוד שירותי אימות הזהות של עומסי עבודה, איחוד שירותי אימות הזהות של כוח עבודה והתחזות לחשבון שירות.
- ליצור ולהשתמש באסימונים מצומצמים כדי להגביל את ההרשאות.
- לשלב את פרטי הכניסה עם ספריות הלקוח של Google HTTP.
המסמכים האלה מיועדים למפתחי Java. לפרטים מלאים על ה-API, קראו את מאמרי העזרה של Google Auth Library API.
ספריית Google Auth ל-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 APIs או לספריות לקוח לצורך אימות ב-Cloud de Confiance by S3NS , אתם עלולים לסכן את האבטחה של המערכות והנתונים שלכם.
מידע נוסף זמין במאמר פרטי כניסה ממקור חיצוני.
ייבוא של ספריית Google Auth
כדי לייבא את Google Auth Library, משתמשים ב-com.google.cloud:libraries-bom או ב-Google Auth Library מפרט חומרים (BoM) עם Maven או Gradle.
Java SDK libraries-bom
כדי לאמת ספריית לקוח ב-Java SDK (לדוגמה, google-cloud-datastore) באמצעות Google Auth Library, משתמשים ב-libraries-bom, שימשוך את הגרסאות של Google Auth Library שתואמות לספריית הלקוח הזו.
לדוגמה, כדי לייבא את ספריית Google Auth באמצעות 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 ישירות באמצעות Google Auth Library מפרט חומרים (BoM).
מפרט החומרים (BoM) של ספריית האימות של Google
אתם יכולים להשתמש ב-Google Auth Library מפרט חומרים (BoM) כדי לוודא שהמודולים של Google Auth Library והתלויות הטרנזיטיביות הרלוונטיות תואמים.
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. לדוגמה, כדי לכלול את המודול 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) לא תומך ב-Maven Bills of Materials (BOMs). לכן, כשמשתמשים ב-Scala, אי אפשר לייבא את google-auth-library-bom כדי לטפל באופן אוטומטי בגרסאות תואמות של המודולים של ספריית Google Auth וביחסי התלות הטרנזיטיביים שלהם.
במקום זאת, צריך להוסיף כל מודול משנה נדרש ישירות לקובץ 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"
רישום ביומן של ספריית האימות של Google
ב-Google Auth Library ל-Java מומלץ להשתמש ביומן ניפוי באגים של ספריית הלקוח. רישום ביומן של יומן ניפוי באגים יגבב טוקנים רגישים (למשל access_token, refresh_token וכו') והערכים יוסתרו. הרישום ביומן באמצעות java.util.logging מושבת בספריית Google Auth כדי למנוע דליפה של טוקנים רגישים.
הפונקציונליות של רישום ביומן של ניפוי באגים בצד הלקוח היא אופציונלית ודורשת הגדרה.
יומן ניפוי באגים יכול לתעד את הפרטים הבאים, בהתאם לרמת הרישום ביומן:
- פרטי הבקשה: כותרות, כתובת URL, שיטה (רמת INFO)
- פרטי התגובה: כותרות, סטטוס, הודעה (רמת INFO)
- מטען ייעודי (payload) של תגובה (רמת DEBUG)
מעבר מ-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ולהעביר אותו ללקוח. לדוגמה, עיינו במדריך ללקוח Java של Google API.
Application Default Credentials
ספריית Google Auth ל-Java מספקת הטמעה של Application Default Credentials (ADC). באמצעות ADC אפשר לקבל פרטי כניסה לצורך הרשאה לשליחת קריאות ל-Google APIs.
כדאי להשתמש ב-ADC כשהאפליקציה שלכם דורשת רמת הרשאה וזהות עקבית, ללא תלות במשתמש. מומלץ להשתמש ב-ADC כדי לאשר קריאות ל-Cloud APIs, במיוחד כשמפתחים אפליקציות ב- Cloud de Confiance.
בנוסף, ADC תומך באיחוד שירותי אימות הזהות של עומסי עבודה, שמאפשר לאפליקציות לגשת למשאבים של Cloud de Confiance מפלטפורמות חיצוניות כמו Amazon Web Services (AWS), Microsoft Azure או כל ספק זהויות שתומך ב-OpenID Connect (OIDC). אנחנו ממליצים על איחוד שירותי אימות הזהות של עומסי עבודה בסביבות שהן לאCloud de Confiance , כי כך לא צריך להוריד, לנהל ולאחסן באופן מקומי מפתחות פרטיים של חשבונות שירות.
קבלת Application Default Credentials
כדי לקבל את Application Default Credentials, משתמשים ב-GoogleCredentials.getApplicationDefault() או ב-GoogleCredentials.getApplicationDefault(HttpTransportFactory). השיטות האלה מחזירות את Application Default Credentials כדי לזהות את האפליקציה כולה ולאשר אותה.
כדי למצוא את פרטי הכניסה של ברירת המחדל של האפליקציה, המערכת מחפשת במקומות הבאים לפי הסדר הזה:
- קובץ פרטי הכניסה שמשתנה הסביבה
GOOGLE_APPLICATION_CREDENTIALSמפנה אליו. - פרטי כניסה שסופקו על ידי הפקודה
gcloud auth application-default loginשל Google Cloud SDK. - פרטי כניסה מובנים של Google App Engine.
- Cloud de Confiance פרטי כניסה מובנים של 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.s3ns.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);
}
אסימונים שקשורים לאישורים לזהויות של נציגים
כשהאפליקציה פועלת עם זהות של סוכן (לדוגמה, שירות או משימה ב-Cloud Run שנפרסו באמצעות --identity-type=agent-identity), כברירת מחדל, ComputeEngineCredentials מבקש משרת המטא-נתונים טוקני גישה וטוקנים של מזהה שקשורים לאישור. אסימון מקושר קשור לאישור X.509 של עומס העבודה, וצריך להוכיח את הבעלות על המפתח הפרטי התואם באמצעות Mutual TLS (mTLS). המפתח הפרטי הזה זמין רק לעומס העבודה, ולכן אי אפשר להשתמש באסימון שדלף ממקום אחר.
טוקן מקושר מתקבל רק כשהבקשה שנושאת אותו נשלחת דרך mTLS עם אותו אישור.
ספריות הלקוח של Cloud ל-Java מגדירות את mTLS וטוענות מחדש באופן אוטומטי את אישורי עומסי העבודה שעברו רוטציה, כשזהות הסוכן מופעלת. אם אתם קוראים ל-Google APIs באמצעות צד הלקוח ב-HTTP, אתם צריכים להגדיר mTLS עם אישור עומס העבודה ולטעון אותו מחדש כשסביבת זמן הריצה מחליפה את האישור בדיסק. אחרי הרוטציה, טוקני הרענון החדשים מקושרים לאישור החדש. אם טוקן רענון חדש נשלח דרך חיבור mTLS שנוצר באמצעות האישור הקודם, ה-API דוחה את הבקשה עם 401 UNAUTHENTICATED.
הספרייה מבקשת אסימון מקושר רק אם כל התנאים הבאים מתקיימים:
- נמצא אישור של עומס עבודה, באמצעות הקובץ שצוין במשתנה הסביבה
GOOGLE_API_CERTIFICATE_CONFIGאו במיקום ברירת המחדל (/var/run/secrets/workload-spiffe-credentials/). - מזהה ה-SPIFFE של האישור שייך למתחם אמון של זהות הסוכן.
- לא השבתתם את קישור האסימונים ואת mTLS (ראו השבתת קישור האסימונים).
בכל הסביבות האחרות, ComputeEngineCredentials פועל כמו קודם ומחזיר אסימונים לא מאוגדים.
השבתת קישור טוקנים
אם אתם צריכים להשבית את קישור האסימון (ראו מגבלות ידועות), הגדירו את משתנה הסביבה הבא:
GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false
| משתנה הסביבה | אפקט |
|---|---|
GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN |
צריך להגדיר את הערך false כדי לבקש אסימונים לא מאוגדים. |
GOOGLE_API_USE_CLIENT_CERTIFICATE |
אם מגדירים את הערך false, פרוטוקול mTLS מושבת לגמרי, וגם קישור האסימונים מושבת. עדיף להשתמש ב-GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false אם אתם צריכים רק אסימונים לא מקושרים. |
הערכים לא תלויי-רישיות והמערכת מתעלמת מרווחים לבנים מסביב. רק הערך false משבית תכונה. כל ערך אחר משאיר את ברירת המחדל.
משתני סביבה חלים על כל התהליך, ולכן השבתת קישור האסימונים משפיעה על כל ספרייה באפליקציה שמשתמשת ב-Application Default Credentials, ולא רק על הספרייה שצריכה את זה. אם אתם צריכים טוקנים של מזהים לא מאוגדים רק לחלק מהיעדים, השתמשו באפשרות לכל יעד שמתוארת בקטע בקשת טוקנים של מזהים לא מאוגדים ליעדים ספציפיים.
בקשת טוקנים של מזהים לא מאוגדים ליעדים ספציפיים
טוקן של מזהה מקושר כולל את טביעת האצבע לאישור של עומס העבודה בטענת הנכוֹנוּת (claim) שלו, cnf (x5t#S256). שירותים שמקבלים את הטענה הזו יכולים לאמת אותה מול אישור הלקוח שמוצג במהלך לחיצת יד של mTLS, או להתעלם מהטענה אם הם לא אוכפים קישור אישורים.
Cloud Run אוכף באופן אוטומטי את קישור האישור כשהטענה cnf קיימת בטוקן של מזהה. אם אתם שולחים קריאה לשירות Cloud Run עם טוקן מזהה מקושר, אתם צריכים לשלוח את הקריאה לכתובת ה-URL של *.mtls.run.app באמצעות mTLS. בקשות לכתובת URL רגילה של *.run.app או לדומיין בהתאמה אישית בלי mTLS נדחות עם השגיאה 401 Unauthorized.
אם אתם שולחים קריאה לשירות שאוכף קישור אישורים דרך נקודת קצה (endpoint) שהיא לא mTLS (כמו כתובת URL רגילה של *.run.app), או אם אתם לא צריכים קישור אישורים לנקודת קצה (endpoint) של יעד, אתם יכולים להעביר את IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN כדי לבקש טוקן של מזהה לא מקושר ליעד הזה בלבד:
GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
IdTokenCredentials idTokenCredentials =
IdTokenCredentials.newBuilder()
.setIdTokenProvider((IdTokenProvider) credentials)
.setTargetAudience("https://my-service-12345.us-central1.run.app")
.setOptions(Arrays.asList(IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN))
.build();
טוקני גישה וטוקנים של מזהים ליעדים אחרים עדיין מקושרים. האפשרות הזו נתמכת רק על ידי ComputeEngineCredentials. הטמעות אחרות של IdTokenProvider לא מבקשות טוקנים של מזהה מקושרים ומתעלמות מהאפשרות הזו, כך שאותו קוד פועל גם מחוץ לסביבות של זהות הסוכן.
מגבלות ידועות
- הערכה לפיתוח סוכנים (ADK) ל-Java לא משתמשת ב-mTLS כשהיא קוראת ל-Google APIs, כמו Gemini ב-Vertex AI. עם אסימונים מקושרים (ברירת המחדל), הקריאות האלה נכשלות עם השגיאה
com.google.genai.errors.ClientException: 401 . Request had invalid authentication credentials. כדי לעקוף את הבעיה, מגדירים אתGOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=falseלסוכנים שמשתמשים ב-ADK ל-Java. מידע נוסף זמין במאמר אימות נציגים ב-Cloud Run.
איחוד שירותי אימות הזהות של עומסי עבודה
איחוד שירותי אימות הזהות של עומסי עבודה מאפשר לאפליקציה לגשת למשאבי Cloud de Confianceמ-Amazon Web Services (AWS), מ-Microsoft Azure או מכל ספק זהויות שתומך ב-OpenID Connect (OIDC).
באופן מסורתי, אפליקציות שפועלות מחוץ ל- Cloud de Confiance משתמשות במפתחות של חשבונות שירות כדי לגשת למשאבים של Cloud de Confiance . באמצעות איחוד שירותי אימות הזהות, עומס העבודה יכול להתחזות לחשבון שירות. כך עומס העבודה החיצוני יכול לגשת ישירות למשאבי Cloud de Confiance , בלי נטל התחזוקה והאבטחה שקשורים למפתחות של חשבונות שירות.
איך ניגשים למשאבים מ-AWS
כדי לגשת למשאבי Cloud de Confiance מ-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: מספר הפרויקט ב- Cloud de Confiance . -
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 Auth Library ל-Java כדי להפעיל משאבים שלCloud de Confiance by S3NS מ-AWS.
איך ניגשים למשאבים מ-Microsoft Azure
כדי לגשת למשאבי Cloud de Confiance מ-Microsoft Azure, קודם צריך להגדיר איחוד שירותי אימות הזהות של עומסי עבודה. תהליך ההגדרה מפורט במאמר גישה למשאבים מ-Azure.
כחלק מהתהליך הזה, תיצרו קובץ תצורה של פרטי כניסה. הקובץ הזה מכיל מטא-נתונים לא רגישים שמנחים את הספרייה איך לאחזר אסימוני נושא חיצוניים ולהמיר אותם באסימוני גישה לחשבון השירות. אפשר ליצור את הקובץ באמצעות Google Cloud CLI:
# 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: מספר הפרויקט ב- Cloud de Confiance . -
POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה. -
AZURE_PROVIDER_ID: מזהה הספק ב-Azure. -
SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שרוצים להתחזות אליו.
הפקודה הזו יוצרת את קובץ התצורה בקובץ הפלט שצוין.
עכשיו אתם יכולים להשתמש ב-Google Auth Library עבור Java כדי לקרוא למשאבי Cloud de Confianceמ-Azure.
איך ניגשים למשאבים מספק זהויות מסוג OIDC
כדי לגשת למשאבי Cloud de Confiance מספק זהויות שתומך ב-OpenID Connect (OIDC), קודם צריך להגדיר את איחוד שירותי אימות הזהות של עומסי עבודה, כמו שמוסבר במאמר הגדרת איחוד שירותי אימות הזהות של עומסי עבודה מספק זהויות מסוג OIDC.
כחלק מהתהליך, תצטרכו ליצור קובץ תצורה של פרטי כניסה באמצעות Google Cloud CLI. הקובץ הזה מכיל מטא-נתונים לא רגישים שמנחים את הספרייה איך לאחזר אסימוני נושא חיצוניים ולהמיר אותם בטוקני גישה לחשבון שירות.
בספקי OIDC, ספריית Google Auth ל-Java יכולה לאחזר אסימוני OIDC מכל אחד מהמקורות הבאים:
- קובץ מקומי (פרטי כניסה שהתקבלו מקובץ)
- שרת מקומי (פרטי כניסה שהתקבלו מכתובת URL)
- אישור X.509 ומפתח פרטי (פרטי כניסה שמקורם באישור X.509)
- קובץ JSON מקומי שמכיל גם אסימון נושא וגם אסימון שחקן להקצאת שחקן (עם קישור אופציונלי לאישור לקוח 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: מספר הפרויקט ב- Cloud de Confiance . -
POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה. -
OIDC_PROVIDER_ID: מזהה ספק ה-OIDC. -
SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שרוצים להתחזות אליו. PATH_TO_OIDC_ID_TOKEN: הנתיב שמשמש לאחזור אסימון ה-OIDC.
הפקודה הזו יוצרת את קובץ התצורה בקובץ הפלט שצוין.
פרטי כניסה שהתקבלו מכתובת URL
בפרטי כניסה שהתקבלו מכתובת URL, שרת מקומי צריך לארח נקודת קצה (endpoint) מסוג GET שמספקת אסימון OIDC בפורמט טקסט פשוט או JSON. אם נקודת הקצה דורשת זאת, אתם יכולים לציין כותרות HTTP נוספות שיישלחו בבקשת האסימון.
כדי ליצור הגדרת Workload Identity ב-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: מספר הפרויקט ב- Cloud de Confiance . -
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 Auth Library עבור Java כדי לקרוא למשאביCloud de Confiance מספק 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 יוצר את קובץ תצורת האישור במיקום ברירת מחדל מוכר, שספריית Google Auth יכולה לגלות באופן אוטומטי. הגישה הזו מתאימה לרוב תרחישי השימוש. קובץ ברירת המחדל של הגדרת פרטי הכניסה נקרא 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: מספר הפרויקט ב- Cloud de Confiance . -
POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה. -
PROVIDER_ID: מזהה הספק. -
SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שרוצים להתחזות אליו. -
PATH_TO_CERTIFICATE: הנתיב שבו נמצא אישור העלה הירוק מסוג X.509. -
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 Auth Library עבור Java כדי לקרוא למשאביCloud de Confiance by S3NS באמצעות פרטי כניסה שמקורם באישור X.509.
גישה למשאבים באמצעות הקצאת הרשאות לגורם פעיל
בעומסי עבודה שמשתמשים באיחוד שירותי אימות הזהות של עומסי עבודה ב-OIDC עם הקצאת הרשאות לגורם (כפי שמוגדר ב-RFC 8693: OAuth 2.0 Token Exchange), ספריית Google Auth ל-Java מחליפה גם אסימון נושא של צד שלישי וגם אסימון גורם של צד שלישי מקובץ JSON מקומי. אסימון הנושא מייצג את הזהות של חשבון המשתמש בבקשה, ואסימון השחקן מייצג את עומס העבודה או השירות שפועלים בשם הנושא.
אפשר להשתמש בהקצאת הרשאות בשני מצבים:
- הקצאת משתמש רגילה (ללא קישור אישור): ספריית Google Auth מחליפה את אסימון הנושא ואת אסימון המשתמש באמצעות TLS רגיל עם Security Token Service (
sts.googleapis.com), ואם מוגדר, מתחזה לחשבון שירות באמצעותiamcredentials.googleapis.com. - אסימונים שמקושרים לאישור עם הקצאת הרשאות לגורם (mTLS): ספריית Google Auth מציגה אישור לקוח מסוג X.509 באמצעות Mutual TLS (mTLS) במהלך החלפת האסימונים עם
sts.mtls.googleapis.com(ואם מוגדרת התחזות לחשבון שירות, עםiamcredentials.mtls.googleapis.com). Cloud de Confiance מאמת שחתימת האישור מסוג SHA-256 בטענת האישור (cnf.x5t#S256) של האסימון תואמת לאישור הלקוח מסוג leaf שמוצג בלחיצת היד של mTLS, ומנפיק אסימון גישה לטווח קצר שמקושר באופן קריפטוגרפי לאישור הזה.
לפני שמתחילים
לפני שמגדירים את Google Auth Library ל-Java, צריך לוודא שיש לכם:
- ספק ומאגר זהויות של עומסי עבודה ב-OIDC שמוגדרים להקצאת הרשאות למשתמשים (עם שם המשאב המלא של ספק המשתמשים המורשה בהגדרות
--actor-providersשל ספק הנושאים), ואם משתמשים באסימונים שקשורים לאישורים, אפשר גם להגדיר אכיפה של מדיניות בקרת גישה מבוססת-הקשר. תהליך ברקע מקומי שמרענן באופן קבוע קובץ JSON שמכיל גם את אסימון הנושא וגם את אסימון השחקן לפני שתוקפם פג:
{ "subject_token": "<var>SUBJECT_JWT_TOKEN</var>", "actor_token": "<var>ACTOR_JWT_TOKEN</var>" }חשוב לוודא שהאסימונים עומדים בדרישות הבאות:
אסימון נושא (הצהרת
may_act): אסימון הנושא חייב לכלול הצהרתmay_actשמאשרת את הצהרתsub(ואופציונליתiss) של השחקן:"may_act": { "sub": "<var>ACTOR_SUBJECT</var>", "iss": "<var>ACTOR_ISSUER</var>" } ```אסימון שחקן (הצהרות
aud,subו-iss): ההצהרהaudשל אסימון השחקן צריכה להיות מוגדרת לשם המשאב המלא של ספק השחקן (//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>ACTOR_PROVIDER_ID</var>), וההצהרהsub(ו-iss) שלו צריכה להתאים לערכים שהוצהרו בהצהרהmay_actשל אסימון הנושא.טענת אישור (
cnf) (רק לאסימונים שקשורים לאישור): המטען הייעודי (payload) של JWT באסימון הקשור חייב לכלול טענתcnfשמכילה את טביעת האצבע לאישור SHA-256 בקידוד base64url (x5t#S256) של אישור הקצה X.509 בקידוד DER של עומס העבודה. אם האסימון של הנושא קשור לאישור, גם האסימון של השחקן חייב להיות קשור לאישור, ואישור הלקוח שמוצג בלחיצת היד של mTLS חייב להתאים לטביעת האצבע לאישורcnf.x5t#S256של האסימון של השחקן:"cnf": { "x5t#S256": "<var>BASE64URL_SHA256_CERT_FINGERPRINT</var>" } ```
(רק לאסימונים שקשורים לאישור) קובץ אישור קצה מסוג X.509 בקידוד PEM וקובץ מפתח פרטי תואם מסוג PKCS#8 לא מוצפן בדיסק.
יצירת קובצי תצורה להאצלת הרשאות לגורם מבצע
אפשר ליצור את קובצי התצורה באמצעות הפקודה gcloud iam workload-identity-pools create-cred-config.
האצלת סמכויות רגילה (ללא קישור בין הרישיון למכשיר)
כדי ליצור קובץ תצורה של פרטי כניסה (config.json) להקצאת הרשאות רגילה של גורם מבצע ללא קישור אישור, מריצים את הפקודה הבאה:
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_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--output-file /path/to/config.json
אסימונים שקשורים לאישורים עם האצלת הרשאות לגורם (mTLS)
כדי להגדיר טוקנים שמקושרים לאישורים עם האצלת הרשאות לשחקן, ה-CLI של gcloud יוצר שני קבצים נפרדים כשמציינים את הדגלים --credential-cert-path ו---credential-cert-private-key-path:
- קובץ תצורה ראשי של פרטי כניסה (
config.json): מכיל את המטא-נתונים של מאגר הזהויות של עומסי העבודה, נקודות הקצה של.mtls.googleapis.com, הנתיב לקובץ האסימון בפורמט JSON ושמות השדות של אסימוני הנושא והשחקן, והפניה לקובץ התצורה של האישור. - קובץ תצורה של אישור (
certificate_config.json): מציין את הנתיבים של אישור הקצה X.509 והמפתח הפרטי של עומס העבודה.
אם משמיטים את הדגל --credential-cert-configuration-output-file (מומלץ), הכלי gcloud יוצר את certificate_config.json בנתיב ברירת המחדל של הגדרת ה-CLI של Google Cloud (~/.config/gcloud/certificate_config.json ב-Linux וב-macOS, או %APPDATA%\gcloud\certificate_config.json ב-Windows) ומגדיר את "use_default_certificate_config": true ב-config.json:
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_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
--credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
--output-file /path/to/config.json
אם אתם צריכים לאחסן את קובץ התצורה של האישור במיקום ברירת המחדל, ציינו את הדגל --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>OIDC_PROVIDER_ID</var> \
--service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
--credential-source-file "<var>PATH_TO_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
--credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
--credential-cert-configuration-output-file "/custom/path/certificate_config.json" \
--output-file /path/to/config.json
מחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_NUMBER: מספר הפרויקט ב- Cloud de Confiance . -
POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה. -
OIDC_PROVIDER_ID: מזהה הספק של מאגר הזהויות של עומסי העבודה ב-OIDC, שמאמת את אסימון הנושא. -
SERVICE_ACCOUNT_EMAIL: אופציונלי. כתובת האימייל של חשבון השירות שרוצים להתחזות אליו. אם אתם משתמשים בגישה ישירה למשאבים, השמיטו את--service-account. -
PATH_TO_TOKENS_JSON: הנתיב לקובץ ה-JSON המקומי שמכיל גם את אסימון הנושא וגם את אסימון השחקן. -
SUBJECT_TOKEN_FIELD_NAME: מפתח ה-JSON ב-PATH_TO_TOKENS_JSONשמכיל את אסימון הנושא (לדוגמה,subject_token). -
ACTOR_TOKEN_FIELD_NAME: מפתח ה-JSON ב-PATH_TO_TOKENS_JSONשמכיל את אסימון השחקן (לדוגמה,actor_token). המפתח הזה חייב להיות שונה מ-SUBJECT_TOKEN_FIELD_NAME. -
PATH_TO_CERTIFICATE(אסימונים שמקושרים לאישור בלבד): הנתיב לאישור X.509 בקידוד PEM. -
PATH_TO_PRIVATE_KEY(אסימונים שקשורים לאישור בלבד): הנתיב למפתח הפרטי התואם בקידוד PEM.
הגדרת משתני סביבה וקריאה לממשקי API של Cloud de Confiance
מגדירים את
GOOGLE_APPLICATION_CREDENTIALSכך שיצביע על קובץ התצורה של פרטי הכניסה:export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.jsonכשמשתמשים באסימונים שמקושרים לאישורים, צריך להגדיר גם את
GOOGLE_API_USE_CLIENT_CERTIFICATE=trueכדי להפעיל העברת mTLS של אישורי לקוח בספריות הלקוח ב-Cloud:export GOOGLE_API_USE_CLIENT_CERTIFICATE=trueאם שמרתם את
certificate_config.jsonבמיקום מותאם אישית, צריך להגדיר אתGOOGLE_API_CERTIFICATE_CONFIG:export GOOGLE_API_CERTIFICATE_CONFIG=/custom/path/certificate_config.jsonמפעילים ספריית לקוח של Cloud de Confiance באמצעות Application Default Credentials. ספריית הלקוח משתמשת באופן אוטומטי ב-
IdentityPoolCredentialsכדי להחליף את אסימוני הנושא והשחקן (ומציגה את אישור הלקוח של עומס העבודה באמצעות mTLS כשמוגדר קישור אישורים):import com.google.cloud.pubsub.v1.TopicAdminClient; import com.google.pubsub.v1.ProjectName; import com.google.pubsub.v1.Topic; public class ActorDelegationExample { public static void main(String[] args) throws Exception { String projectId = "your-project-id"; // TopicAdminClient automatically detects GOOGLE_APPLICATION_CREDENTIALS // and uses mTLS when GOOGLE_API_USE_CLIENT_CERTIFICATE=true is set. try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) { for (Topic topic : topicAdminClient.listTopics(ProjectName.of(projectId)).iterateAll()) { System.out.println(topic.getName()); } } } }
רוטציה של טוקנים ואישורים
כשהתהליך ברקע מחליף אסימונים בדיסק (ובאסימונים שקשורים לאישור, את אישור הקצה X.509 ואת המפתח הפרטי של עומס העבודה), חשוב לזכור את ההתנהגויות והדרישות הבאות:
- עדכונים אטומיים: ספריית האימות של Google קוראת גם את אסימון הנושא וגם את אסימון השחקן מקובץ אסימון ה-JSON בקריאה אחת לכל רענון. מעדכנים את קובץ האסימון בפורמט JSON באופן אטומי (לדוגמה, על ידי כתיבה לקובץ זמני ושינוי השם שלו) כדי שאסימון הנושא ואסימון השחקן יישארו מסונכרנים. כשמשתמשים באסימונים שקשורים לאישור, צריך לעדכן את האישור, את המפתח הפרטי ואת קובץ האסימון בפורמט JSON באופן אטומי, כדי שטביעת האצבע של
cnf.x5t#S256בקובץ האסימון תישאר מסונכרנת עם אישור X.509 בדיסק. - הצמדת אישורים לכל מחזור (אסימונים שמקושרים לאישורים): כש-
IdentityPoolCredentialsמרענן אסימון גישה דרך mTLS, הוא יוצר תמונת מצב של מאגר המפתחות X.509 בתחילת מחזור הרענון ומשתמש באותו אישור לקוח גם בבקשת Security Token ServiceexchangeTokenוגם בבקשת ההתחזות של Service Account Credentials APIgenerateAccessToken(אם הוגדרה). - טעינה מחדש אוטומטית של
401 Unauthorized(אסימונים שקשורים לאישור): אם האישור עובר רוטציה ובקשת mTLS מחזירה את הערך401 Unauthorized, ספריית Google Auth טוענת מחדש באופן אוטומטי את אישור ה-X.509 ואת המפתח הפרטי מהדיסק, ומנסה שוב לרענן את האסימון פעם אחת.
פתרון בעיות בהענקת הרשאות למשתמשים
בטבלה הבאה מפורטות שגיאות נפוצות ופתרונות להאצלת הרשאות לגורם:
| שגיאה או חריגה | מטרה | רזולוציה |
|---|---|---|
IllegalArgumentException: Actor tokens are only supported for JSON-formatted credential sources. |
המאפיין credential_source.format.type חסר או מוגדר כ-text, אבל צוין המאפיין actor_token_field_name. |
מגדירים את credential_source.format.type כ-"json" ומציינים גם את subject_token_field_name וגם את actor_token_field_name. |
IllegalArgumentException: The actor_token_field_name must not be empty. |
הערך actor_token_field_name ב-credential_source.format הוא מחרוזת ריקה (""). |
צריך להזין שם שדה JSON לא ריק בשביל actor_token_field_name, או להסיר את השדה אם לא נעשה שימוש בהקצאת הרשאות למשתמש. |
IllegalArgumentException: The actor_token_field_name must differ from the subject_token_field_name. |
הערכים של actor_token_field_name ו-subject_token_field_name מוגדרים לאותו מפתח JSON. |
צריך להשתמש בשמות שונים לשדות ה-JSON של אסימון הנושא ואסימון השחקן בקובץ האסימונים וב-config.json. |
IllegalArgumentException: An actorTokenType must be specified when an actorTokenSupplier is configured. (או להיפך) |
רק אחד מהשדות actor_token_type או actor_token_field_name קיים ב-config.json. |
צריך לציין גם את "actor_token_type": "urn:ietf:params:oauth:token-type:jwt" וגם את credential_source.format.actor_token_field_name. |
IOException: Invalid token field name. No token was found for field: FIELD_NAME |
קובץ ה-JSON ב-credential_source.file לא מכיל את המפתח subject_token_field_name או actor_token_field_name שהוגדר, או שהערך שלו הוא null. |
מוודאים שתהליך רענון האסימון כותב את שני המפתחות בקובץ ה-JSON. |
IOException: Invalid token field value. Empty token was found for field: FIELD_NAME |
המפתח subject_token_field_name או actor_token_field_name שהוגדר בקובץ האסימון בפורמט JSON הוא מחרוזת ריקה או מחרוזת שמכילה רק רווחים. |
מוודאים שתהליך רענון האסימון מאכלס את שני השדות במחרוזות JWT לא ריקות. |
IOException: Token field value for FIELD_NAME must be a String... |
הערך ב-subject_token_field_name או ב-actor_token_field_name בקובץ האסימון בפורמט JSON הוא אובייקט, מערך, מספר או ערך בוליאני בפורמט JSON, במקום מחרוזת. |
מוודאים ששני שדות האסימון מכילים מחרוזות JWT שעברו סריאליזציה ("eyJ..."). |
RuntimeException: Failed to initialize mTLS transport for file credential source due to certificate configuration error. |
ערכת ה-SDK לא הצליחה לטעון או לנתח את certificate_config.json, את אישור ה-X.509 ב-cert_path או את המפתח הפרטי ב-key_path. |
צריך לוודא ש-certificate_config.json קיים בנתיב ברירת המחדל (או GOOGLE_API_CERTIFICATE_CONFIG), ושהערכים של cert_path ו-key_path מפנים לקובצי PEM תקינים וקריאים. |
400 Bad Request / invalid_request מ-sts.mtls.googleapis.com |
טביעת האצבע של cnf.x5t#S256 בטוקן לא תואמת לאישור הלקוח שהוצג במהלך לחיצת היד של mTLS. |
מוודאים שהערך של x5t#S256 הוא גיבוב SHA-256 בקידוד base64url של אישור הקצה בקידוד DER ב-certificate_config.json. |
401 Unauthorized או 403 Forbidden כשקוראים לממשקי API של Cloud de Confiance אחרי שהחלפת האסימונים בוצעה בהצלחה |
ספריית הלקוח במורד הזרם לא יצרה mTLS או השתמשה באישור שונה מזה שמקושר לטוקן הגישה. | צריך לוודא שהמשתנה export GOOGLE_API_USE_CLIENT_CERTIFICATE=true מוגדר, ושהמשתנה GOOGLE_API_CERTIFICATE_CONFIG (אם משתמשים בנתיב תצורה של אישור בהתאמה אישית) מפנה לאותו קובץ certificate_config.json שאליו מפנה המשתנה config.json. |
שימוש בפרטי כניסה שהתקבלו מקובץ הפעלה עם OIDC ו-SAML
בפרטי כניסה שהתקבלו מקובץ הפעלה, קובץ הפעלה מקומי משמש לאחזור האסימון של הצד השלישי. קובץ ההפעלה צריך לספק ל-stdout אסימון מזהה של OIDC או טענת נכוֹנוּת של SAML תקינים ותקפים בפורמט JSON.
כדי להשתמש בפרטי הכניסה שהתקבלו מקובץ הפעלה, צריך להגדיר את משתנה הסביבה GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES לערך 1.
כדי ליצור הגדרת Workload Identity שהתקבלה מקובץ הפעלה, מריצים את הפקודה הבאה:
# 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: מספר הפרויקט ב- Cloud de Confiance . -
POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה. -
PROVIDER_ID: מזהה הספק של OIDC או SAML. -
SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שרוצים להתחזות אליו. -
SUBJECT_TOKEN_TYPE: סוג אסימון הנושא. -
EXECUTABLE_COMMAND: הפקודה המלאה שצריך להריץ, כולל ארגומנטים. הנתיב חייב להיות נתיב מוחלט לתוכנית.
הדגל --executable-timeout-millis הוא אופציונלי. הוא מציין את משך הזמן (באלפיות השנייה) שבו ספריית Google Auth תמתין עד שקובץ ההפעלה יסיים. אם לא מציינים ערך, ברירת המחדל היא 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. כך ספריית האימות של Google יכולה לשמור ביעילות במטמון את פרטי הכניסה ששמורים בקובץ, ולנהל את התוקף שלהם.
הנה דוגמה לתגובת שגיאה של קובץ הפעלה:
{
"version": 1,
"success": false,
"code": "401",
"message": "Caller not authorized."
}
כל השדות האלה נדרשים לתגובת שגיאה. הספרייה משתמשת בשדות הקוד וההודעה כחלק מחריגה שנזרקה.
סיכום השדות של פורמט התגובה:
* 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 Auth Library עבור Java כדי לקרוא למשאביCloud de Confiance by S3NS מספק OIDC או SAML.
שימוש בספק בהתאמה אישית עם OIDC ו-SAML
אפשר להשתמש בהטמעה מותאמת אישית של IdentityPoolSubjectTokenSupplier בזמן שיוצרים את IdentityPoolCredentials כדי לספק אסימון נושא שאפשר להחליף באסימון גישה של Cloud de Confiance . הספק צריך להחזיר אסימון נושא תקין ובתוקף כשהוא נקרא על ידי פרטי הכניסה של Cloud de Confiance.
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 Cloud de Confiance 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: מספר הפרויקט ב- Cloud de Confiance . -
WORKLOAD_POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה. -
PROVIDER_ID: מזהה הספק.
אפשר גם למצוא את הערכים של הקהל, כתובת ה-URL להתחזות לחשבון שירות וכל שדה אחר של ה-builder, על ידי יצירת קובץ תצורה של פרטי כניסה באמצעות ה-CLI של gcloud.
שימוש בספק בהתאמה אישית ב-AWS
אפשר לספק הטמעה מותאמת אישית של AwsSecurityCredentialsSupplier כשמפעילים את AwsCredentials. אם מספקים את הספק, המכונה של AwsCredentials תפנה לספק כדי לאחזר את פרטי הכניסה המאובטחים ל-AWS ולהחליף אותם באסימון גישה שלCloud de Confiance . הספק צריך להחזיר פרטי כניסה מאובטחים תקינים ותקפים של AWS כשמתבצעת קריאה על ידי פרטי הכניסה של Cloud de Confiance .
הפונקציות של 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 Cloud de Confiance 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: מספר הפרויקט ב- Cloud de Confiance . -
WORKLOAD_POOL_ID: המזהה של מאגר הזהויות של עומסי העבודה. -
PROVIDER_ID: מזהה הספק.
אפשר גם למצוא את הערכים של הקהל, כתובת ה-URL להתחזות לחשבון שירות וכל שדה אחר של ה-builder, על ידי יצירת קובץ תצורה של פרטי כניסה באמצעות ה-CLI של gcloud.
משך חיים של טוקן שניתן להגדרה
כשיוצרים הגדרת פרטי כניסה עם איחוד שירותי אימות הזהות של עומסי עבודה באמצעות התחזות לחשבון שירות, אפשר לספק ארגומנט אופציונלי כדי להגדיר את משך החיים של טוקן הגישה של חשבון השירות.
כדי ליצור את התצורה עם משך חיים של אסימון שניתן להגדרה, מריצים את הפקודה הבאה (בדוגמה הזו משתמשים בתצורה של 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: מספר הפרויקט ב- Cloud de Confiance . -
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, וליצור הגדרה לשימוש בספריית Google Auth.
כדי ליצור הגדרה של זהות כוח עבודה למשתמש מורשה בחשבון חיצוני, מריצים את הפקודה הבאה:
gcloud auth application-default login --login-config=LOGIN_CONFIG
צריך להחליף את המשתנה הבא:
-
LOGIN_CONFIG: קובץ תצורת ההתחברות שנוצר באמצעות מסוף Cloud de Confiance או gcloud iam workforce-pools create-login-config
כך נפתח תהליך בדפדפן שמאפשר להיכנס באמצעות ספק הזהויות שהוגדר מצד שלישי. לאחר מכן, הוא מאחסן את הגדרת המשתמש המורשה של החשבון החיצוני במיקום הידוע של ADC.
לאחר מכן, ספריית Google Auth ל-Java תשתמש בטוקן הרענון שסופק מההגדרות כדי ליצור ולרענן טוקן גישה לקריאה לשירותיCloud de Confiance .
משך החיים של טוקן הרענון הוא שעה אחת כברירת מחדל. אחרי זה, צריך ליצור הגדרה חדשה מה-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, אלא אם מוודאים ששדות כתובת ה-URL מפנים לדומיין 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();
דפוס שימוש נפוץ
דפוס השימוש הנפוץ כולל ברוקר של אסימונים עם גישה מוגברת. הברוקר הזה יוצר פרטי כניסה עם הרשאות מצומצמות מפרטי כניסה של מקור עם גישה ברמה גבוהה יותר. לאחר מכן, הוא מעביר את טוקני הגישה לטווח קצר עם ההיקף המצומצם לצרכן טוקנים דרך ערוץ מאומת ומאובטח, כדי לאפשר גישה מוגבלת למשאבי Cloud de ConfianceStorage.
יצירת אסימונים עם הרשאות מצומצמות
יש שתי דרכים ליצור אסימונים עם היקף מצומצם באמצעות CredentialAccessBoundary:
בצד השרת (באמצעות
DownscopedCredentials): הלקוח קורא ל-Security Token Service (STS) בכל פעם שנדרש אסימון עם היקף מצומצם. השיטה הזו מתאימה לאפליקציות שבהן הכללים של גבולות הגישה לפרטי הכניסה משתנים לעיתים רחוקות, או כשמשתמשים שוב ושוב באותם פרטי כניסה מצומצמים. נקודה חשובה שצריך לקחת בחשבון היא שכל שינוי בכלל מחייב קריאה חדשה ל-STS. הגישה הזו זמינה בספרייהgoogle-auth-library-oauth2-httpולא נדרשים יחסי תלות נוספים. כך קל יותר לשלב את הנתונים. היא מתאימה לתרחישי שימוש שלא דורשים את היתרונות הספציפיים של הגישה בצד הלקוח.בצד הלקוח (באמצעות
ClientSideCredentialAccessBoundaryFactory): הלקוח מאחזר חומר קריפטוגרפי פעם אחת, ואז יוצר כמה אסימונים עם היקף מצומצם באופן מקומי. כך מצמצמים את הקריאות ל-STS, וזה יעיל יותר כשכללי גבולות הגישה לפרטי הכניסה משתנים לעיתים קרובות, כי הלקוח לא צריך לפנות ל-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 עם פרטי כניסה של מקור. אחרי שמפעילים את ה-factory, אפשר לקרוא ל-method 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);
שימוש בטוקני גישה עם היקף מצומצם
אתם יכולים להגדיר מתווך טוקנים בשרת ברשת פרטית. עומסי עבודה שונים (צרכני אסימונים) באותה רשת שולחים בקשות מאומתות לברוקר הזה כדי לקבל אסימונים עם היקף מצומצם. הטוקנים האלה מאפשרים להם לגשת לקטגוריות ספציפיות ב- Cloud de Confiance Storage או לשנות אותן.
הברוקר יוצר מופעים של פרטי כניסה עם הרשאות מצומצמות, שיכולים ליצור טוקני גישה עם הרשאות מצומצמות לטווח קצר. לאחר מכן, הוא מעביר את האסימונים האלה לצרכן האסימונים.
צרכן האסימון יכול להשתמש בטוקני הגישה המצומצמים האלה באמצעות OAuth2Credentials או OAuth2CredentialsWithRefresh. אחר כך תוכלו להשתמש בפרטי הכניסה האלה כדי להפעיל מכונה של לקוח אחסון, כדי לגשת למשאבי Cloud de ConfianceStorage עם גישה מוגבלת.
// 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, ולא בשירותים האחרים שלCloud de Confiance .
שימוש בפרטי כניסה עם google-http-client
אפשר להשתמש בפרטי הכניסה שסופקו על ידי com.google.auth:google-auth-library-oauth2-http עם לקוחות מבוססי-HTTP של Google. לקוחות מבוססי-HTTP של Google מספקים HttpCredentialsAdapter שאפשר להשתמש בו בתור HttpRequestInitializer, הארגומנט האחרון של ה-builders שלהם.
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
הארטיפקט הזה מכיל מחלקות בסיסיות וממשקים לפרטי הכניסה של Google:
-
Credentials: זוהי המחלקה הבסיסית של זהות מורשית. הטמעות של המחלקה הזו יכולות לאשר את האפליקציה שלכם. -
RequestMetadataCallback: זהו הממשק של פונקציית ה-callback שמקבלת את התוצאה של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 בצד הלקוח. למודול הזה יש קבוצה משלו של יחסי תלות. כדאי לבדוק אם היתרונות של צמצום ההיקף בצד הלקוח עולים על המורכבות הנוספת בתרחיש לדוגמה הספציפי שלכם.