אירוח דף כניסה באמצעות Cloud Run

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

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

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

מגבלות בדף הכניסה

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

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

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

הגדרת כתובת ה-URI המורשית להפניה אוטומטית לספקי Identity Platform

אם אתם משתמשים בספקים של Identity Platform שדורשים הפניה אוטומטית לכניסה (הפניה אוטומטית לדף הכניסה של ספק הזהויות החיצוני). אתם צריכים להוסיף את כתובת ה-URL של דף הכניסה המתארח ככתובת URL מורשית להפניה אוטומטית בהגדרות של הספק.

לדוגמה, אם הספק הוא Google, צריך לבצע את הפעולות הבאות:

  1. בוחרים את האפליקציה שמאובטחת באמצעות IAP ומעתיקים את כתובת ה-URL להתחברות.

  2. נכנסים לדף Credentials במסוף Google Cloud .

    כניסה לדף Credentials

  3. מוסיפים את LOGIN_URL/__/auth/handler כאחד ממזהי ה-URI המורשים להפניה אוטומטית של לקוח OAuth 2.0 של האפליקציה. בוחרים את אותו מזהה לקוח ב-OAuth שבו השתמשתם כשהגדרתם את ספק Google.

בספקי SAML ו-OIDC אחרים, צריך להוסיף את LOGIN_URL/__/auth/handler בתור כתובת ה-URI המורשית להפניה או כתובת ה-URL של ה-ACS.

בדיקת דף הכניסה

דף הכניסה הראשוני שנוצר על ידי IAP פועל באופן מלא. כדי לבדוק את זה:

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

  2. בוחרים דייר (tenant) וספק כדי להיכנס לחשבון. אם לא מופיעים דיירים או ספקים, ודאו שהגדרתם אותם באמצעות Identity Platform.

  3. נכנסים באמצעות פרטי הכניסה.

המערכת אמורה להפנות אתכם למשאב המוגן.

התאמה אישית של דף הכניסה

אפשר להתאים אישית את דף הכניסה באמצעות קובץ תצורה בפורמט JSON. למשל:

  • הוספת כותרת ולוגו לדף הכניסה.

  • מציינים את הדיירים והספקים הזמינים.

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

  • הוספת קישורים למדיניות הפרטיות ולתנאים ולהגבלות של האפליקציה.

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

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

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

  1. נכנסים לדף Identity Platform Providers במסוףGoogle Cloud .

    כניסה לדף Identity Platform Providers

  2. לוחצים על הוספת ספק.

  3. בוחרים באפשרות Google מרשימת הספקים.

  4. מגדירים את מזהה הלקוח באינטרנט ואת סוד הלקוח באינטרנט:

    1. נכנסים לדף Credentials במסוף Google Cloud .

      כניסה לדף Credentials

    2. משתמשים בלקוח OAuth 2.0 קיים או יוצרים לקוח חדש. מגדירים את Client ID ו-Client secret ל-מזהה לקוח אינטרנט ול-סוד לקוח אינטרנט. מוסיפים את LOGIN_URL/__/auth/handler כאחד מכתובות ה-URI המורשות להפניה אוטומטית של לקוח OAuth 2.0. הערך LOGIN_URL הוא כתובת ה-URL לכניסה שנוצרה על ידי IAP אחרי בחירת האפשרות אני רוצה ליצור דף כניסה. אפשר למצוא אותו בדף IAP במסוף Google Cloud , על ידי בחירת המשאב שמאובטח באמצעות IAP.

  5. לוחצים על שמירה בשני הדפים.

כניסה לחלונית הניהול

הגדרת ה-JSON של דף הכניסה שמתארח ב-Cloud Run בחלונית LOGIN_URL/admin. כדי לגשת לחלונית: שימו לב שצריך את התפקיד אדמין של Storage‏ (roles/storage.admin).

  1. נכנסים לדף IAP במסוף Google Cloud .

    כניסה לדף IAP

  2. בוחרים את המשאב מהרשימה.

  3. מפעילים את כתובת ה-URL שמופיעה בקטע התאמה אישית של הדף בחלונית המידע. הוא אמור להיראות בערך כך: https://servicename-xyz-uc.a.run.app/admin.

  4. נכנסים לאותו חשבון Google שבו השתמשתם כדי להגדיר את IAP. מופיע כלי לעריכת טקסט שמכיל את קובץ התצורה בפורמט JSON.

שינוי ההגדרות האישיות

סכימת ההגדרות של דף הכניסה מבוססת על FirebaseUI, וכוללת הרבה מהמאפיינים שלו. במקום להשתמש ב-LOGIN_URL שנוצר על ידי IAP כ-authDomain שמוגדר כברירת מחדל, אפשר להשתמש ב-PROJECT_ID.firebaseapp.com.

אם רוצים להשתמש ב-PROJECT_ID.firebaseapp.com בתור authDomain, צריך לשנות את signInFlow ל-popup כדי למנוע בעיות בגישה לאחסון של צד שלישי בדפדפנים נפוצים (אפשר לעיין בשיטות מומלצות לשימוש ב-signInWithRedirect בדפדפנים שחוסמים גישה לאחסון של צד שלישי). בנוסף, צריך לפעול לפי ההוראות במאמר הגדרת URI מורשה להפניה אוטומטית לספקי Identity Platform כדי להוסיף את PROJECT_ID.firebaseapp.com/__/auth/handler כאחד מכתובות ה-URI המורשות להפניה אוטומטית או כתובות ה-ACS של ספק Identity Platform שהמשתמשים ייכנסו איתו.

הקוד הבא מציג דוגמה להגדרה עם שלושה דיירים:

{
  "AIzaSyC5DtmRUR...": {
    "authDomain": "awesomeco.firebaseapp.com",
    "displayMode": "optionFirst",
    "selectTenantUiTitle": "Awesome Company Portal",
    "selectTenantUiLogo": "https://awesome.com/abcd/logo.png",
    "styleUrl": "https://awesome.com/abcd/overrides/stylesheet.css",
    "tosUrl": "https://awesome.com/abcd/tos.html",
    "privacyPolicyUrl": "https://awesome.com/abcd/privacypolicy.html",
    "tenants": {
      "tenant-a-id": {
        "fullLabel": "Company A Portal",
        "displayName": "Company A",
        "iconUrl": "https://companya.com/img/icon.png",
        "logoUrl": "https://companya.com/img/logo.png",
        "buttonColor": "#007bff",
        "signInFlow": "popup",
        "signInOptions": [
          {
            "provider": "password",
            "requireDisplayName": false,
            "disableSignUp": {
              "status": true,
              "adminEmail": "admin@example.com",
              "helpLink": "https://www.example.com/trouble_signing_in"
            }
          },
          "facebook.com",
          "google.com",
          "microsoft.com",
          {
            "provider": "saml.okta-cicp-app",
            "providerName": "Corp Account",
            "fullLabel": "Employee Corporate Login",
            "buttonColor": "#ff0000",
            "iconUrl": "https://companya.com/abcd/icon-1.png"
          },
          {
            "provider": "oidc.okta-oidc",
            "providerName": "Contractor Account",
            "fullLabel": "Contractor Account Portal",
            "buttonColor": "#00ff00",
            "iconUrl": "https://companya.com/abcd/icon-2.png"
          }
        ],
        "tosUrl": "https://companya.com/abcd/tos.html",
        "privacyPolicyUrl": "https://companya.com/abcd/privacypolicy.html"
      },
      "tenant-b-id": {
        "fullLabel": "Company B Portal",
        "displayName": "Company B",
        "iconUrl": "https://companyb.com/img/icon.png",
        "logoUrl": "https://companyb.com/img/logo.png",
        "buttonColor": "#007bff",
        "immediateFederatedRedirect": true,
        "signInFlow": "popup",
        "signInOptions": [
          {
            "provider": "saml.okta-bla-app",
            "providerName": "Corp Account",
            "buttonColor": "#0000ff",
            "iconUrl": "https://companyb.com/abcd/icon.png"
          }
        ],
        "tosUrl": "https://companyb.com/abcd/tos.html",
        "privacyPolicyUrl": "https://companyb.com/abcd/privacypolicy.html"
      },
      "tenant-c-id": {
        "fullLabel": "Company C Portal",
        "displayName": "Company C",
        "iconUrl": "https://companyc.com/img/icon.png",
        "logoUrl": "https://companyc.com/img/logo.png",
        "buttonColor": "#007bff",
        "immediateFederatedRedirect": true,
        "signInFlow": "popup",
        "signInOptions": [
          {
            "provider": "password",
            "requireDisplayName": false
          },
          {
            "provider": "google.com",
            "scopes": ["scope1", "scope2", "https://example.com/scope3"],
            "loginHintKey": "login_hint",
            "customParameters": {
              "prompt": "consent",
            },
          }
        ],
        "tosUrl": "https://companyc.com/abcd/tos.html",
        "privacyPolicyUrl": "https://companyc.com/abcd/privacypolicy.html",
        "adminRestrictedOperation": {
          "status": true,
          "adminEmail": "admin@example.com",
          "helpLink": "https://www.example.com/trouble_signing_in"
        }
      },
    }
  }
}

רשימה מלאה של המאפיינים הזמינים מופיעה במאמרי העזרה.

שינוי ברירת המחדל של CSS

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

בדוגמה הבאה אפשר לראות איך לשנות את הגדרות ברירת המחדל של ה-CSS:

/** Change header title style. */
.heading-center {
  color: #7181a5;
  font-family: Arial, Helvetica, sans-serif;
  font-size: 20px;
  font-weight: bold;
}

/** Use round edged borders for container. */
.main-container {
  border-radius: 5px;
}

/** Change page background color. */
body {
  background-color: #e6eaf0;
}

פריסה מחדש של שירות Cloud Run

במקרים מסוימים, יכול להיות שתרצו לפרוס מחדש את שירות Cloud Run שמארח את דף הכניסה. תרחישים לדוגמה:

  • הוספה, שינוי או הסרה של ספקי זהויות

  • שינוי הגדרות של דיירים

  • הגדרה של משתני סביבה

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

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

אפשר לקבל את הגרסה הנוכחית של מאגר התגים שנפרס באמצעות נקודת הקצה /versionz. לדוגמה:

curl 'https://servicename-xyz-uc.a.run.app/versionz'

כדי לפרוס מחדש את שירות Cloud Run:

  1. נכנסים לדף Cloud Run במסוף Google Cloud .

    כניסה לדף Cloud Run

  2. בוחרים את השירות שמארח את דף הכניסה.

  3. לוחצים על Edit & Deploy New Revision.

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

  5. לוחצים על Deploy.

אפשרויות מתקדמות

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

בנוסף לשימוש במסוף /admin, אפשר לעדכן את הגדרות ה-JSON באופן פרוגרמטי.

כדי לקבל את ההגדרה הנוכחית, משתמשים בנקודת הקצה /get_admin_config. לדוגמה:

curl -H 'Authorization: Bearer [TOKEN]'
  'https://servicename-xyz-uc.a.run.app/get_admin_config'

כדי לעדכן את ההגדרות, משתמשים ב-/set_admin_config. לדוגמה:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' -H "Content-type: application/json"
  -d '[UPDATED-CONFIG]' 'https://servicename-xyz-uc.a.run.app/set_admin_config'

שתי הקריאות ל-REST דורשות את ההיקף https://www.googleapis.com/auth/devstorage.read_write, וצריך לצרף אסימון OAuth תקין לכותרת Authorization.

הגדרה של משתני סביבה

אתם יכולים להגדיר משתני סביבה בשירות Cloud Run כדי להתאים אישית את ההגדרות המתקדמות. בטבלה הבאה מפורטים המשתנים הזמינים:

משתנה תיאור
DEBUG_CONSOLE ערך בוליאני (0 או 1) שמציין אם לתעד ביומן את כל השגיאות והפרטים של הבקשות לאחזור מהרשת. מידע רגיש לא יתועד ביומן. מושבתת (0) כברירת מחדל.
UI_CONFIG מחרוזת שמכילה את הגדרת ה-JSON של דף הכניסה. כשמשתמשים במשתנה הזה במקום בלוח /admin, לא צריך לקרוא ולכתוב ב-Cloud Storage כשניגשים להגדרות. המערכת מתעלמת מהגדרות לא תקינות. כדי לצמצם את שגיאות התחביר, אפשר להשתמש בחלונית /admin כדי לאמת את קובץ ה-JSON לפני שמגדירים את המשתנה הזה.
GCS_BUCKET_NAME מחרוזת שמחליפה את קטגוריית ברירת המחדל של Cloud Storage שמשמשת לאחסון הגדרות ה-JSON. שם הקובץ הוא config.json, והמיקום שמוגדר כברירת מחדל הוא gcip-iap-bucket-[CLOUD-RUN-SERVICE-NAME]-[PROJECT-NUMBER].
ALLOW_ADMIN ערך בוליאני (0 או 1) שמציין אם לאפשר גישה לחלונית ההגדרות של /admin. מופעל (1) כברירת מחדל.

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

התאמה אישית של הדומיין

כברירת מחדל, המשתמשים יראו את כתובת ה-URL של שירות Cloud Run כשהם ייכנסו לחשבון. כדי לציין דומיין מותאם אישית:

  1. כדי להגדיר דומיין מותאם אישית לשירות Cloud Run, פועלים לפי השלבים שמפורטים במאמר מיפוי דומיינים מותאמים אישית.

  2. מגדירים את IAP כך שישתמש בכתובת ה-URL החדשה לאימות:

    1. נכנסים לדף IAP במסוף Google Cloud .

      כניסה לדף IAP

    2. בוחרים את המשאב שמוגן על ידי IAP.

    3. בחלונית הצד, לוחצים על סמל העריכה לצד השדה כתובת URL להתחברות.

    4. בוחרים באפשרות Use an existing hosted sign-in page ובוחרים את הדומיין מהתפריט הנפתח.

    5. לוחצים על Save.

שימוש בדף כניסה אחד לכמה משאבי IAP

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

כדי להשתמש שוב בדף כניסה:

  1. כדי לפרוס את דף האימות למשאב הראשון שמוגן באמצעות IAP, פועלים לפי השלבים שבמאמר הזה.

  2. מפעילים את IAP במשאב השני. כשמופיעה בקשה לציין דף כניסה, בוחרים באפשרות I'll provide my own ומזינים את כתובת ה-URL של שירות Cloud Run בשדה URL.

  3. פורסים מחדש את שירות Cloud Run.

פתרון בעיות

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

כשמשתמשים בדף כניסה שמתארח, מקבלים את השגיאה הבאה:

Service unavailable

במצב כזה, לא תוכלו לגשת לדף הכניסה.

כדי לפתור את השגיאה:

  1. מוודאים שקטגוריית ברירת המחדל של Cloud Storage היא בפורמט gcip-iap-bucket-CLOUD_RUN_SERVICE_NAME-PROJECT-NUMBER.

  2. מוודאים שקטגוריית ברירת המחדל של Cloud Storage קיימת ומכילה קובץ בשם config.json.

קובצי Cookie של צד שלישי וחלוקת האחסון למחיצות בדפדפנים

בדפדפנים שבהם קובצי Cookie של צד שלישי מושבתים או שמוגדרת בהם חלוקת האחסון למחיצות, יכול להיות שדף הכניסה או הדף admin/ לא יפעלו כמו שצריך. כדי לפתור את הבעיה:

  1. פורסים מחדש את דף הכניסה כדי להשתמש בגרסה העדכנית 1.0.1.

  2. אם מתאימים אישית את דף הכניסה, צריך לוודא ש-authDomain מוגדר בתור LOGIN_URL שנוצר על ידי IAP. לחלופין, אם המדיניות signInFlow מוגדרת לערך popup, אפשר להגדיר את המדיניות authDomain לערך PROJECT_ID.firebaseapp.com.

    בקטע הקוד הבא אפשר לראות את ההגדרה של authDomain לדף כניסה בהתאמה אישית:

    {
      "AIzaSyC5DtmRUR...": {
        "authDomain": "LOGIN_URL",
        ...
      }
    }
    

    קטע הקוד הבא מתאר את authDomain של דף כניסה ב-popup:

    {
      "AIzaSyC5DtmRUR...": {
        "authDomain": "PROJECT_ID.firebaseapp.com",
        "tenants": {
          "tenant-a-id": {
            ...
            "signInFlow": "popup"
            ...
          }
        }
        ...
      }
    }
    

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