הגדרת אימות ל-Artifact Registry עבור npm

כדי להשתמש באפליקציית צד שלישי להתחברות למאגר, צריך לבצע אימות ב-Artifact Registry.

לא צריך להגדיר אימות עבור Cloud Build או סביבות זמן ריצה כמו Google Kubernetes Engine ו-Cloud Run, אבל כדאי לוודא שההרשאות הנדרשות מוגדרות. Google Cloud

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

1. התקינו את ה-CLI של Google Cloud. אחר כך, אתחלו את ה-CLI של Google Cloud באמצעות הפקודה הבאה:

   gcloud init

   אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

   הערה: אם התקנתם את ה-CLI של gcloud, השתמשו בפקודה gcloud components update כדי לבדוק אם מותקנת הגרסה העדכנית.
2. (אופציונלי) הגדרת ברירות מחדל לפקודות של ה-CLI של gcloud.
3. אם אתם מתחברים למאגרי מידע מ-Windows, צריך להתקין את PowerShell.
4. יוצרים חשבון שירות שיפעל בשם האפליקציה.
5. אם אתם חדשים ב-npm, מומלץ לקרוא את הסקירה הכללית כדי לקבל מידע על חבילות עם היקף ועל קובץ ההגדרות של הגדרות האימות.

סקירה כללית

‫Artifact Registry תומך בשיטות האימות הבאות.

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

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

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

משתמשים באפשרות הזו כשאפליקציה לא תומכת ב-Application Default Credentials, אבל כן תומכת באימות באמצעות שם משתמש וסיסמה.

אימות באמצעות כלי עזר לאימות

‫google-artifactregistry-auth היא ספריית לקוח שמקבלת פרטי כניסה למאגרי Artifact Registry.

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

1. Application Default Credentials‏ (ADC), אסטרטגיה שמחפשת פרטי כניסה בסדר הבא:

   1. פרטי הכניסה מוגדרים במשתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS.

   2. פרטי הכניסה שחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine,‏ Google Kubernetes Engine,‏ Cloud Run,‏ App Engine או בפונקציות של Cloud Run מספק.

2. פרטי כניסה שסופקו על ידי Google Cloud CLI, כולל פרטי כניסה של משתמשים מהפקודה gcloud auth application-default login.

המשתנה GOOGLE_APPLICATION_CREDENTIALS הופך את החשבון לאימות למפורש, וכך קל יותר לפתור בעיות. אם לא משתמשים במשתנה, צריך לוודא שלחשבונות ש-ADC עשוי להשתמש בהם יש את ההרשאות הנדרשות. לדוגמה, לחשבון השירות שמוגדר כברירת מחדל למכונות וירטואליות ב-Compute Engine, לצמתים ב-Google Kubernetes Engine ולעדכונים ב-Cloud Run יש גישת קריאה בלבד למאגרים. אם אתם מתכוונים להעלות נתונים מהסביבות האלה באמצעות חשבון השירות שמוגדר כברירת מחדל, אתם צריכים לשנות את ההרשאות.

כדי ליצור חשבון שירות ולהגדיר את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS:

1. יוצרים חשבון שירות שיפעל בשם האפליקציה, או בוחרים חשבון שירות קיים שבו רוצים להשתמש לאוטומציה של CI/CD.

2. מקצים לחשבון השירות את התפקיד הספציפי ב-Artifact Registry כדי לתת גישה למאגר.

3. מקצים את המיקום של קובץ המפתח של חשבון השירות למשתנה GOOGLE_APPLICATION_CREDENTIALS כדי שעוזר האישורים של Artifact Registry יוכל לקבל את המפתח כשמתחברים למאגרי מידע.

   export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
   

   ‫KEY-FILE הוא הנתיב אל קובץ המפתח של חשבון השירות.

כדי להגדיר אימות:

1. מריצים את הפקודה הבאה כדי להדפיס את הגדרות המאגר:

   gcloud artifacts print-settings npm [--project=PROJECT] \
       --repository=REPOSITORY \
       --location=LOCATION \
       --scope=@SCOPE-NAME \
   

   כאשר:

   • ‫PROJECT הוא מזהה הפרויקט. אם לא מציינים את הדגל הזה, המערכת משתמשת בפרויקט הנוכחי או בפרויקט ברירת המחדל.
   • ‫REPOSITORY הוא המזהה של המאגר. אם הגדרתם מאגר ברירת מחדל של Artifact Registry, המערכת תשתמש בו אם לא תציינו את הדגל הזה בפקודה.
   • ‫LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר.

   • ‫SCOPE-NAME הוא שם ההיקף של npm שאותו רוצים לשייך למאגר.

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

     חבילות ללא היקף משויכות למאגר ברירת המחדל של npm, בדרך כלל מאגר npm הציבורי. אם לא מציינים היקף, ההגדרות שמוחזרות מגדירות את מאגר Artifact Registry כמאגר ברירת המחדל. הדבר עלול לגרום לבעיות אם בפרויקטים של Node.js צריך להתקין חבילות גם ממאגר npm הציבורי וגם ממאגר Artifact Registry.

2. מוסיפים את הגדרות התצורה שמוחזרות לקובץ התצורה .npmrc בפרויקטים של Node.js. הקובץ הזה נמצא בדרך כלל באותה תיקייה כמו package.json.

   חשוב לוודא שאתם כוללים את ההגדרות האלה בפרויקטים של Node.js לחבילות שאתם מפרסמים, וגם בפרויקטים שיתקינו תלות ממאגר npm שלכם.

3. אם יש לכם מאגרי Node.js אחרים להתחבר אליהם, חוזרים על השלבים הקודמים כדי לקבל את ההגדרות ומוסיפים אותן לקובצי .npmrc המתאימים.

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

כל מאגר חבילות Node.js ב-Artifact Registry משויך לנקודת קצה של מאגר https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY

אם לא ציינתם היקף באמצעות הפקודה print-settings, אתם יכולים להריץ את הפקודה הבאה כדי לשייך היקף למאגר Artifact Registry.

npm config set @SCOPE_NAME:registry https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY/

קבלת טוקן גישה

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

כדי לקבל טוקן, אפשר להשתמש באחת מהאפשרויות הבאות:

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

  1. מוודאים שפרטי הכניסה להתחברות למאגר npm הציבורי נמצאים בקובץ התצורה של npm של המשתמש, ~/.npmrc.

  2. מריצים את הפקודה הבאה בספריית הפרויקט של Node.js.

     npx google-artifactregistry-auth
     

     אם מאגר Artifact Registry מוגדר כמאגר הגלובלי והחבילות לא מוגדרות בהיקף, צריך להשתמש בפקודה הבאה כדי שהפקודה תוכל להוריד את כלי העזר לאישורים ממאגר npm הציבורי במקום ממאגר Artifact Registry.

     npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
     

• מוסיפים סקריפט לקובץ package.json בפרויקט.

  "scripts": {
   "artifactregistry-login": "npx google-artifactregistry-auth"
  }
  

  מריצים את הסקריפט בספריית הפרויקט של Node.js.

  npm run artifactregistry-login
  

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

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

• ‫--repo-config הוא קובץ .npmrc עם הגדרות המאגר. אם לא מציינים את הדגל הזה, מיקום ברירת המחדל הוא הספרייה הנוכחית.
• ‫--credential-config הוא הנתיב לקובץ .npmrc שבו רוצים לכתוב את אסימון הגישה. ברירת המחדל היא קובץ .npmrc של המשתמש.

הגדרת אימות סיסמה

משתמשים בגישה הזו כשהאפליקציה שלכם ב-Node.js דורשת אימות באמצעות שם משתמש וסיסמה שצוינו.

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

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

כדי ליצור חשבון שירות ולהגדיר אימות:

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

   כדי להגדיר אימות באמצעות Artifact Registry, תצטרכו את המיקום של קובץ המפתח של חשבון השירות. בחשבונות קיימים, אפשר לראות את המפתחות וליצור מפתחות חדשים בדף 'חשבונות שירות'.

   מעבר לדף 'חשבונות שירות'

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

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

2. מקצים לחשבון השירות את התפקיד הספציפי ב-Artifact Registry כדי לתת גישה למאגר.

3. כדי להפעיל את חשבון השירות בסשן הנוכחי של ה-CLI של gcloud, מריצים את הפקודה:

   gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
   

   כאשר:

   • ‫ACCOUNT הוא המשתמש או חשבון השירות.
   • ‫KEY-FILE הוא הנתיב לקובץ מפתח JSON של חשבון השירות.

4. מריצים את הפקודה הבאה כדי להדפיס את הגדרות המאגר:

   gcloud artifacts print-settings npm [--project=PROJECT] \
   [--repository=REPOSITORY] [--location=LOCATION] --scope=@SCOPE-NAME --json-key=KEY-FILE
   

   כאשר:

   • ‫PROJECT הוא מזהה הפרויקט. אם לא מציינים את הדגל הזה, המערכת משתמשת בפרויקט הנוכחי או בפרויקט ברירת המחדל.
   • ‫REPOSITORY הוא המזהה של המאגר. אם הגדרתם מאגר ברירת מחדל של Artifact Registry, המערכת תשתמש בו אם לא תציינו את הדגל הזה בפקודה.
   • ‫LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר.

   • ‫SCOPE-NAME הוא שם ההיקף של npm שאותו רוצים לשייך למאגר.

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

     חבילות ללא היקף משויכות למאגר ברירת המחדל של npm, בדרך כלל מאגר npm הציבורי. אם לא מציינים היקף, ההגדרות שמוחזרות מגדירות את מאגר Artifact Registry כמאגר ברירת המחדל. הדבר עלול לגרום לבעיות אם בפרויקטים של Node.js צריך להתקין חבילות גם ממאגר npm הציבורי וגם ממאגר Artifact Registry.

   • ‫KEY-FILE הוא הנתיב לקובץ מפתח JSON של חשבון השירות.

   הערה: הגדרות התצורה שמוחזרות כוללות כתובת אימייל של placeholder. כדי לפרסם חבילות npm, צריך להזין כתובת אימייל בהגדרות של npm. כתובת האימייל של ה-placeholder לא משמשת את Artifact Registry לאימות.

5. מוסיפים את הגדרות התצורה שמוחזרות לקובץ התצורה .npmrc בפרויקטים של Node.js. הקובץ הזה נמצא בדרך כלל באותה תיקייה כמו package.json. חשוב לוודא שאתם כוללים את ההגדרות האלה בפרויקטים של Node.js לחבילות שאתם מפרסמים, וגם בפרויקטים שיתקינו תלות ממאגר ה-npm שלכם.

6. אם יש לכם מאגרי Node.js אחרים להתחבר אליהם, חוזרים על השלבים הקודמים כדי לקבל את ההגדרות ולהוסיף אותן לקובץ .npmrc.

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

• הגדרת גישה למאגרים
• מידע נוסף על ניהול מאגרי מידע
• מידע על ניהול חבילות