google auth library java
v1.30.0
مكتبة عميل المصادقة مفتوحة المصدر لـ Java.
يتكون هذا المشروع من 3 قطع أثرية:
جدول المحتويات:
بداية سريعة
جوجل-auth-library-oauth2-http
جوجل-مصادقة-مكتبة-بيانات الاعتماد
google-auth-library-appengine
حالة سي آي
المساهمة
رخصة
إذا كنت تستخدم Maven، فأضف هذا إلى ملف pom.xml الخاص بك (لاحظ أنه يمكنك استبدال google-auth-library-oauth2-http بأي من google-auth-library-credentials و google-auth-library-appengine ، اعتمادًا على احتياجات التطبيق الخاص بك):
< dependency >
< groupId >com.google.authgroupId >
< artifactId >google-auth-library-oauth2-httpartifactId >
< version >1.19.0version >
dependency >إذا كنت تستخدم Gradle، أضف هذا إلى تبعياتك
implementation ' com.google.auth:google-auth-library-oauth2-http:1.19.0 'إذا كنت تستخدم SBT، أضف هذا إلى تبعياتك
libraryDependencies + = " com.google.auth " % " google-auth-library-oauth2-http " % " 1.19.0 " توفر هذه المكتبة تطبيقًا لبيانات اعتماد التطبيق الافتراضية لـ Java. توفر بيانات اعتماد التطبيق الافتراضية طريقة بسيطة للحصول على بيانات اعتماد الترخيص لاستخدامها في الاتصال بواجهات برمجة تطبيقات Google.
وهي مناسبة بشكل أفضل للحالات التي تحتاج فيها المكالمة إلى نفس مستوى الهوية والترخيص للتطبيق بشكل مستقل عن المستخدم. هذا هو الأسلوب الموصى به للسماح باستدعاءات Cloud APIs، خاصة عند إنشاء تطبيق يستخدم Google Cloud Platform.
تدعم بيانات اعتماد التطبيق الافتراضية أيضًا اتحاد هوية عبء العمل للوصول إلى موارد Google Cloud من الأنظمة الأساسية غير التابعة لـ Google Cloud، بما في ذلك Amazon Web Services (AWS) أو Microsoft Azure أو أي موفر هوية يدعم OpenID Connect (OIDC). يوصى باتحاد هوية عبء العمل للبيئات غير التابعة لـ Google Cloud لأنه يتجنب الحاجة إلى تنزيل المفاتيح الخاصة لحساب الخدمة وإدارتها وتخزينها محليًا، راجع: اتحاد هوية عبء العمل.
للحصول على بيانات الاعتماد الافتراضية للتطبيق، استخدم GoogleCredentials.getApplicationDefault() أو GoogleCredentials.getApplicationDefault(HttpTransportFactory) . تقوم هذه الطرق بإرجاع بيانات اعتماد التطبيق الافتراضية التي يتم استخدامها لتحديد التطبيق بأكمله وتخويله. يتم البحث فيما يلي (بالترتيب) للعثور على بيانات اعتماد التطبيق الافتراضية:
GOOGLE_APPLICATION_CREDENTIALSgcloud auth application-default loginNO_GCE_CHECK=trueGCE_METADATA_HOST= للحصول على بيانات الاعتماد من مفتاح 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 بتمكين واجهة برمجة التطبيقات "IAMCredentials". بالإضافة إلى ذلك، يجب أن يمنح حساب الخدمة الهدف المدير الأساسي دور IAM "منشئ الرمز المميز لحساب الخدمة".
String credPath = "/path/to/svc_account.json" ;
ServiceAccountCredentials sourceCredentials = ServiceAccountCredentials
. fromStream ( new FileInputStream ( credPath ));
sourceCredentials = ( ServiceAccountCredentials ) sourceCredentials
. createScoped ( Arrays . asList ( "https://www.googleapis.com/auth/iam" ));
ImpersonatedCredentials targetCredentials = ImpersonatedCredentials . create ( sourceCredentials ,
"[email protected]" , null ,
Arrays . asList ( "https://www.googleapis.com/auth/devstorage.read_only" ), 300 );
Storage storage_service = StorageOptions . newBuilder (). setProjectId ( "project-id" )
. setCredentials ( targetCredentials ). build (). getService ();
for ( Bucket b : storage_service . list (). iterateAll ())
System . out . println ( b ); باستخدام اتحاد هوية عبء العمل، يمكن لتطبيقك الوصول إلى موارد Google Cloud من Amazon Web Services (AWS) أو Microsoft Azure أو أي موفر هوية يدعم OpenID Connect (OIDC).
تقليديًا، تستخدم التطبيقات التي تعمل خارج Google Cloud مفاتيح حساب الخدمة للوصول إلى موارد Google Cloud. باستخدام اتحاد الهوية، يمكن أن ينتحل عبء العمل الخاص بك صفة حساب الخدمة. يتيح ذلك لأحمال العمل الخارجية الوصول إلى موارد Google Cloud مباشرة، مما يؤدي إلى التخلص من أعباء الصيانة والأمان المرتبطة بمفاتيح حساب الخدمة.
من أجل الوصول إلى موارد Google Cloud من Amazon Web Services (AWS)، يلزم توفر المتطلبات التالية:
اتبع الإرشادات التفصيلية حول كيفية تكوين اتحاد هوية عبء العمل من AWS.
بعد تكوين موفر AWS لانتحال شخصية حساب خدمة، يجب إنشاء ملف تكوين بيانات الاعتماد. على عكس ملفات اعتماد حساب الخدمة، يحتوي ملف تكوين بيانات الاعتماد الذي تم إنشاؤه على بيانات تعريف غير حساسة لإرشاد المكتبة حول كيفية استرداد الرموز المميزة للموضوع الخارجي واستبدالها برموز الوصول إلى حساب الخدمة. يمكن إنشاء ملف التكوين باستخدام gcloud CLI.
لإنشاء تكوين هوية حمل عمل AWS، قم بتشغيل الأمر التالي:
# Generate an AWS configuration file.
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حيث يلزم استبدال المتغيرات التالية:
$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.
للوصول إلى موارد Google Cloud من Microsoft Azure، يلزم توفر المتطلبات التالية:
اتبع الإرشادات التفصيلية حول كيفية تكوين اتحاد هوية حمل العمل من Microsoft Azure.
بعد تكوين موفر Azure لانتحال شخصية حساب خدمة، يجب إنشاء ملف تكوين بيانات الاعتماد. على عكس ملفات اعتماد حساب الخدمة، يحتوي ملف تكوين بيانات الاعتماد الذي تم إنشاؤه على بيانات تعريف غير حساسة لإرشاد المكتبة حول كيفية استرداد الرموز المميزة للموضوع الخارجي واستبدالها برموز الوصول إلى حساب الخدمة. يمكن إنشاء ملف التكوين باستخدام gcloud CLI.
لإنشاء تكوين هوية حمل عمل Azure، قم بتشغيل الأمر التالي:
# Generate an Azure configuration file.
gcloud iam workload-identity-pools create-cred-config
projects/ $PROJECT_NUMBER /locations/global/workloadIdentityPools/ $POOL_ID /providers/ $AZURE_PROVIDER_ID
--service-account $SERVICE_ACCOUNT_EMAIL
--azure
--output-file /path/to/generated/config.jsonحيث يلزم استبدال المتغيرات التالية:
$PROJECT_NUMBER : رقم مشروع Google Cloud.$POOL_ID : معرف تجمع هوية عبء العمل.$AZURE_PROVIDER_ID : معرف موفر Azure.$SERVICE_ACCOUNT_EMAIL : البريد الإلكتروني لحساب الخدمة المراد انتحاله.يؤدي هذا إلى إنشاء ملف التكوين في ملف الإخراج المحدد.
يمكنك الآن استخدام مكتبة المصادقة للاتصال بموارد Google Cloud من Azure.
من أجل الوصول إلى موارد Google Cloud من موفر هوية يدعم OpenID Connect (OIDC)، يلزم توفر المتطلبات التالية:
اتبع الإرشادات التفصيلية حول كيفية تكوين اتحاد هوية عبء العمل من موفر هوية OIDC.
بعد تكوين موفر OIDC لانتحال صفة حساب خدمة، يجب إنشاء ملف تكوين بيانات الاعتماد. على عكس ملفات اعتماد حساب الخدمة، يحتوي ملف تكوين بيانات الاعتماد الذي تم إنشاؤه على بيانات تعريف غير حساسة لإرشاد المكتبة حول كيفية استرداد الرموز المميزة للموضوع الخارجي واستبدالها برموز الوصول إلى حساب الخدمة. يمكن إنشاء ملف التكوين باستخدام gcloud CLI.
بالنسبة لموفري OIDC، يمكن لمكتبة Auth استرداد رموز OIDC المميزة إما من موقع ملف محلي (بيانات اعتماد مصدر الملف) أو من خادم محلي (بيانات اعتماد مصدر عنوان URL).
بيانات الاعتماد من مصادر الملفات بالنسبة إلى بيانات الاعتماد من مصادر الملفات، يجب أن تقوم عملية الخلفية بتحديث موقع الملف بشكل مستمر باستخدام رمز OIDC مميز جديد قبل انتهاء الصلاحية. بالنسبة للرموز المميزة التي تبلغ مدة صلاحيتها ساعة واحدة، يجب تحديث الرمز المميز في الملف كل ساعة. يمكن تخزين الرمز المميز مباشرة كنص عادي أو بتنسيق JSON.
لإنشاء تكوين OIDC من مصدر ملف، قم بتشغيل الأمر التالي:
# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workload-identity-pools create-cred-config
projects/ $PROJECT_NUMBER /locations/global/workloadIdentityPools/ $POOL_ID /providers/ $OIDC_PROVIDER_ID
--service-account $SERVICE_ACCOUNT_EMAIL
--credential-source-file $PATH_TO_OIDC_ID_TOKEN
# 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. يمكن أيضًا تحديد رؤوس الطلب الإضافية المطلوبة.
لإنشاء تكوين هوية حمل عمل OIDC من مصدر URL، قم بتشغيل الأمر التالي:
# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config
projects/ $PROJECT_NUMBER /locations/global/workloadIdentityPools/ $POOL_ID /providers/ $OIDC_PROVIDER_ID
--service-account $SERVICE_ACCOUNT_EMAIL
--credential-source-url $URL_TO_GET_OIDC_TOKEN
--credential-source-headers $HEADER_KEY = $HEADER_VALUE
# 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.
بيانات الاعتماد من مصادر قابلة للتنفيذ بالنسبة إلى بيانات الاعتماد من مصادر قابلة للتنفيذ، يتم استخدام ملف قابل للتنفيذ محلي لاسترداد الرمز المميز للطرف الثالث. يجب أن يتعامل الملف القابل للتنفيذ مع توفير رمز معرف OIDC صالح وغير منتهي الصلاحية أو تأكيد SAML بتنسيق JSON إلى stdout.
لاستخدام بيانات الاعتماد القابلة للتنفيذ، يجب تعيين متغير البيئة GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES على 1 .
لإنشاء تكوين هوية حمل عمل قابل للتنفيذ، قم بتشغيل الأمر التالي:
# Generate a configuration file for executable-sourced credentials.
gcloud iam workload-identity-pools create-cred-config
projects/ $PROJECT_NUMBER /locations/global/workloadIdentityPools/ $POOL_ID /providers/ $PROVIDER_ID
--service-account= $SERVICE_ACCOUNT_EMAIL
--subject-token-type= $SUBJECT_TOKEN_TYPE
# The absolute path for the program, including arguments.
# e.g. --executable-command="/path/to/command --foo=bar"
--executable-command= $EXECUTABLE_COMMAND
# Optional argument for the executable timeout. Defaults to 30s.
# --executable-timeout-millis=$EXECUTABLE_TIMEOUT
# Optional argument for the absolute path to the executable output file.
# See below on how this argument impacts the library behaviour.
# --executable-output-file=$EXECUTABLE_OUTPUT_FILE
--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 ثانية عندما لا يتم توفيره. الحد الأقصى للقيمة المسموح بها هو 2 دقيقة. الحد الأدنى هو 5 ثواني.
تعتبر علامة --executable-output-file اختيارية. إذا تم توفيره، فيجب أن يشير مسار الملف إلى استجابة بيانات اعتماد 3PI التي تم إنشاؤها بواسطة الملف القابل للتنفيذ. وهذا مفيد للتخزين المؤقت لبيانات الاعتماد. من خلال تحديد هذا المسار، ستقوم مكتبات المصادقة أولاً بالتحقق من وجوده قبل تشغيل الملف القابل للتنفيذ. من خلال التخزين المؤقت لاستجابة JSON القابلة للتنفيذ لهذا الملف، فإنه يعمل على تحسين الأداء لأنه يتجنب الحاجة إلى تشغيل الملف القابل للتنفيذ حتى تنتهي صلاحية بيانات الاعتماد المخزنة مؤقتًا في ملف الإخراج. يجب أن يتعامل الملف القابل للتنفيذ مع الكتابة في هذا الملف - ستحاول مكتبات المصادقة القراءة من هذا الموقع فقط. يجب أن يتطابق تنسيق محتويات الملف مع تنسيق 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
}نموذج للاستجابة للخطأ القابل للتنفيذ:
{
"version" : 1 ,
"success" : false ,
"code" : " 401 " ,
"message" : " Caller not authorized. "
}هذه كلها حقول مطلوبة للاستجابة للخطأ. سيتم استخدام حقول التعليمات البرمجية والرسائل بواسطة المكتبة كجزء من الاستثناء المطروح.
للحصول على استجابات ناجحة، يكون الحقل expiration_time مطلوبًا فقط عند تحديد ملف الإخراج في تكوين بيانات الاعتماد.
ملخص حقول تنسيق الاستجابة:
version : إصدار إخراج JSON. حاليًا يتم دعم الإصدار 1 فقط.success : عندما يكون صحيحا، يجب أن تحتوي الاستجابة على الرمز المميز ونوع الرمز المميز لجهة خارجية. يجب أن تحتوي الاستجابة أيضًا على حقل expiration_time إذا تم تحديد ملف إخراج في تكوين بيانات الاعتماد. يجب أيضًا إنهاء الملف القابل للتنفيذ برمز الخروج 0. وعندما يكون خطأ، يجب أن تحتوي الاستجابة على رمز الخطأ وحقول الرسائل والخروج بقيمة غير صفرية.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).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 : موقع ملف الإخراج من تكوين بيانات الاعتماد. موجود فقط عند تحديده في تكوين بيانات الاعتماد.يمكن استخدام متغيرات البيئة هذه بواسطة الملف القابل للتنفيذ لتجنب تشفير هذه القيم بشكل صارم.
يوصى بشدة بالممارسات الأمنية التالية:
نظرًا لتعقيد استخدام بيانات الاعتماد من مصادر قابلة للتنفيذ، فمن المستحسن استخدام الآليات المدعومة الحالية (من مصادر الملفات/مصادر عناوين URL) لتوفير بيانات اعتماد الجهات الخارجية ما لم تكن تلبي متطلباتك المحددة.
يمكنك الآن استخدام مكتبة المصادقة للاتصال بموارد Google Cloud من موفر OIDC أو SAML.
يمكن استخدام التنفيذ المخصص لـ IdentityPoolSubjectTokenSupplier أثناء إنشاء IdentityPoolCredentials لتوفير رمز مميز للموضوع يمكن استبداله برمز وصول GCP. يجب على المورد إرجاع رمز موضوع صالح وغير منتهي الصلاحية عند استدعائه بواسطة بيانات اعتماد Google Cloud Platform.
لا تقوم IdentityPoolCredentials بتخزين الرمز المميز الذي تم إرجاعه مؤقتًا، لذا يجب تنفيذ منطق التخزين المؤقت في مورد الرمز المميز لمنع الطلبات المتعددة لنفس الرمز المميز للموضوع.
import java . io . IOException ;
public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {
@ Override
public String getSubjectToken ( ExternalAccountSupplierContext context ) throws IOException {
// Any call to the supplier will pass 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 do not 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 GCP audience.
. setSubjectTokenType ( SubjectTokenTypes . JWT ) // Sets the subject token type.
. build (); مكان تواجد الجمهور: //iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID
حيث يلزم استبدال المتغيرات التالية:
$PROJECT_NUMBER : رقم مشروع Google Cloud.$WORKLOAD_POOL_ID : معرف تجمع هوية عبء العمل.$PROVIDER_ID : معرف المزود.يمكن أيضًا العثور على قيم الجمهور وعنوان URL لانتحال هوية حساب الخدمة وأي حقل إنشاء آخر عن طريق إنشاء ملف تكوين بيانات الاعتماد باستخدام gcloud CLI.
يمكن توفير تطبيق مخصص لـ AwsSecurityCredentialsSupplier عند تهيئة AwsCredentials. إذا تم توفيره، فسيرجع مثيل AwsCredentials إلى المورد لاسترداد بيانات اعتماد أمان AWS لاستبدالها برمز وصول GCP. يجب على المورد إرجاع بيانات اعتماد أمان AWS صالحة وغير منتهية الصلاحية عند استدعائها بواسطة بيانات اعتماد Google Cloud Platform.
لا تقوم AwsCredentials بتخزين بيانات اعتماد أمان AWS أو المنطقة التي تم إرجاعها مؤقتًا، لذلك يجب تنفيذ منطق التخزين المؤقت في المورد لمنع الطلبات المتعددة لنفس الموارد.
class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
@ Override
AwsSecurityCredentials getAwsSecurityCredentials ( ExternalAccountSupplierContext context ) throws IOException {
// Any call to the supplier will pass 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 do not 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 do not 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 GCP audience.
. setAwsSecurityCredentialsSupplier ( supplier ) // Sets the supplier.
. build (); مكان تواجد الجمهور: //iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID
حيث يلزم استبدال المتغيرات التالية:
$PROJECT_NUMBER : رقم مشروع Google Cloud.$WORKLOAD_POOL_ID : معرف تجمع هوية عبء العمل.$PROVIDER_ID : معرف المزود.يمكن أيضًا العثور على قيم الجمهور وعنوان URL لانتحال هوية حساب الخدمة وأي حقل إنشاء آخر عن طريق إنشاء ملف تكوين بيانات الاعتماد باستخدام gcloud CLI.
عند إنشاء تكوين بيانات اعتماد مع اتحاد هوية عبء العمل باستخدام انتحال هوية حساب الخدمة، يمكنك توفير وسيطة اختيارية لتكوين عمر رمز الوصول إلى حساب الخدمة.
لإنشاء التكوين باستخدام عمر الرمز المميز القابل للتكوين، قم بتشغيل الأمر التالي (يستخدم هذا المثال تكوين AWS، ولكن يمكن تكوين عمر الرمز المميز لجميع موفري اتحاد هوية حمل العمل):
# Generate an AWS configuration file with configurable token lifetime.
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
--service-account-token-lifetime-seconds $TOKEN_LIFETIMEحيث يلزم استبدال المتغيرات التالية:
$PROJECT_NUMBER : رقم مشروع Google Cloud.$POOL_ID : معرف تجمع هوية عبء العمل.$AWS_PROVIDER_ID : معرف موفر AWS.$SERVICE_ACCOUNT_EMAIL : البريد الإلكتروني لحساب الخدمة المراد انتحاله.$TOKEN_LIFETIME : المدة العمرية المطلوبة لرمز الوصول إلى حساب الخدمة بالثواني. تعتبر علامة service-account-token-lifetime-seconds اختيارية. إذا لم يتم توفيره، فهذا الإعداد الافتراضي هو ساعة واحدة. الحد الأدنى المسموح به هو 600 (10 دقائق) والحد الأقصى المسموح به هو 43200 (12 ساعة). إذا كان عمر الخدمة أكبر من ساعة واحدة مطلوبًا، فيجب إضافة حساب الخدمة كقيمة مسموح بها في سياسة المؤسسة التي تفرض قيد constraints/iam.allowServiceAccountCredentialLifetimeExtension .
لاحظ أن تكوين عمر قصير (على سبيل المثال 10 دقائق) سيؤدي إلى قيام المكتبة ببدء تدفق تبادل الرمز المميز بالكامل كل 10 دقائق، مما سيؤدي إلى الاتصال بموفر الرمز المميز للطرف الثالث حتى إذا لم تنته صلاحية الرمز المميز للطرف الثالث.
يتيح لك اتحاد هوية القوى العاملة استخدام موفر هوية خارجي (IdP) لمصادقة وتخويل القوى العاملة - مجموعة من المستخدمين، مثل الموظفين والشركاء والمقاولين - باستخدام IAM، حتى يتمكن المستخدمون من الوصول إلى خدمات Google Cloud. يعمل اتحاد هوية القوى العاملة على توسيع إمكانات هوية Google Cloud لدعم تسجيل الدخول الفردي غير المتزامن والمستند إلى السمات.
من خلال اتحاد هوية القوى العاملة، يمكن للقوى العاملة لديك الوصول إلى موارد Google Cloud باستخدام موفر هوية خارجي (IdP) يدعم OpenID Connect (OIDC) أو SAML 2.0 مثل Azure Active Directory (Azure AD)، أو خدمات اتحاد Active Directory (AD FS)، أو Okta وآخرون.
من أجل الوصول إلى موارد Google Cloud من موفر هوية يدعم OpenID Connect (OIDC)، يلزم توفر المتطلبات التالية:
اتبع الإرشادات التفصيلية حول كيفية تكوين اتحاد هوية القوى العاملة.
بعد تكوين موفر OIDC أو SAML 2.0، يجب إنشاء ملف تكوين بيانات الاعتماد. يحتوي ملف تكوين بيانات الاعتماد الذي تم إنشاؤه على بيانات تعريف غير حساسة لإرشاد المكتبة حول كيفية استرداد الرموز المميزة للموضوع الخارجي واستبدالها برموز وصول GCP. يمكن إنشاء ملف التكوين باستخدام gcloud CLI.
يمكن لمكتبة المصادقة استرداد الرموز المميزة للموضوع الخارجي من موقع ملف محلي (بيانات اعتماد مصدر ملف)، أو من خادم محلي (بيانات اعتماد مصدر عنوان URL) أو عن طريق استدعاء ملف قابل للتنفيذ (بيانات اعتماد مصدر قابل للتنفيذ).
بيانات الاعتماد من مصادر الملفات بالنسبة لبيانات الاعتماد من مصادر الملفات، يجب أن تقوم عملية الخلفية بتحديث موقع الملف بشكل مستمر باستخدام رمز مميز جديد للموضوع قبل انتهاء الصلاحية. بالنسبة للرموز المميزة التي تبلغ مدة صلاحيتها ساعة واحدة، يجب تحديث الرمز المميز في الملف كل ساعة. يمكن تخزين الرمز المميز مباشرة كنص عادي أو بتنسيق JSON.
لإنشاء تكوين OIDC من مصدر ملف، قم بتشغيل الأمر التالي:
# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workforce-pools create-cred-config
locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID
--subject-token-type=urn:ietf:params:oauth:token-type:id_token
--credential-source-file= $PATH_TO_OIDC_ID_TOKEN
--workforce-pool-user-project= $WORKFORCE_POOL_USER_PROJECT
# 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حيث يلزم استبدال المتغيرات التالية:
$WORKFORCE_POOL_ID : معرف تجمع القوى العاملة.$PROVIDER_ID : معرف المزود.$PATH_TO_OIDC_ID_TOKEN : مسار الملف المستخدم لاسترداد رمز OIDC.$WORKFORCE_POOL_USER_PROJECT : رقم المشروع المرتبط بمشروع مستخدم تجمعات القوى العاملة.لإنشاء تكوين SAML من مصدر ملف، قم بتشغيل الأمر التالي:
# Generate a SAML configuration file for file-sourced credentials.
gcloud iam workforce-pools create-cred-config
locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID
--credential-source-file= $PATH_TO_SAML_ASSERTION
--subject-token-type=urn:ietf:params:oauth:token-type:saml2
--workforce-pool-user-project= $WORKFORCE_POOL_USER_PROJECT
--output-file=/path/to/generated/config.json حيث يلزم استبدال المتغيرات التالية:
$WORKFORCE_POOL_ID : معرف تجمع القوى العاملة.$PROVIDER_ID : معرف المزود.$PATH_TO_SAML_ASSERTION : مسار الملف المستخدم لاسترداد تأكيد SAML المشفر بواسطة base64.$WORKFORCE_POOL_USER_PROJECT : رقم المشروع المرتبط بمشروع مستخدم تجمعات القوى العاملة.تقوم هذه الأوامر بإنشاء ملف التكوين في ملف الإخراج المحدد.
بيانات الاعتماد من مصدر URL بالنسبة لبيانات الاعتماد من مصدر URL، يحتاج الخادم المحلي إلى استضافة نقطة نهاية GET لإرجاع رمز OIDC المميز. يمكن أن تكون الاستجابة بنص عادي أو JSON. يمكن أيضًا تحديد رؤوس الطلب الإضافية المطلوبة.
لإنشاء تكوين هوية القوى العاملة لـ OIDC من مصدر URL، قم بتشغيل الأمر التالي:
# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workforce-pools create-cred-config
locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID
--subject-token-type=urn:ietf:params:oauth:token-type:id_token
--credential-source-url= $URL_TO_RETURN_OIDC_ID_TOKEN
--credential-source-headers $HEADER_KEY = $HEADER_VALUE
--workforce-pool-user-project= $WORKFORCE_POOL_USER_PROJECT
--output-file=/path/to/generated/config.jsonحيث يلزم استبدال المتغيرات التالية:
$WORKFORCE_POOL_ID : معرف تجمع القوى العاملة.$PROVIDER_ID : معرف المزود.$URL_TO_RETURN_OIDC_ID_TOKEN : عنوان URL لنقطة نهاية الخادم المحلي.$HEADER_KEY و $HEADER_VALUE : أزواج مفتاح/قيمة الرأس الإضافية لتمرير طلب GET إلى $URL_TO_GET_OIDC_TOKEN ، على سبيل المثال Metadata-Flavor=Google .$WORKFORCE_POOL_USER_PROJECT : رقم المشروع المرتبط بمشروع مستخدم تجمعات القوى العاملة.لإنشاء تكوين SAML من مصدر URL، قم بتشغيل الأمر التالي:
# Generate a SAML configuration file for file-sourced credentials.
gcloud iam workforce-pools create-cred-config
locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID
--subject-token-type=urn:ietf:params:oauth:token-type:saml2
--credential-source-url= $URL_TO_GET_SAML_ASSERTION
--credential-source-headers 
