כניסת משתמשים באמצעות SAML

במאמר הזה מוסבר איך משתמשים ב-Identity Platform כדי להכניס משתמשים באמצעות ספק Security Assertion Markup Language ‏ (SAML) 2.0.

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

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

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. מפעילים את Identity Platform ומוסיפים את ה-SDK של הלקוח לאפליקציה. מידע נוסף והוראות זמינים במאמר כניסה של משתמש באמצעות אימייל באמצעות Identity Platform.

הגדרת הספק

  1. במסוף Google Cloud , נכנסים לדף Identity Platform > ספקי זהויות.
    כניסה לדף 'ספקי זהויות'

  2. לוחצים על הוספת ספק ובוחרים באפשרות SAML מהרשימה.

  3. מזינים את הפרטים הבאים:

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

    2. מזהה הישות של הספק.

    3. כתובת ה-URL של SAML SSO של הספק.

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

      -----BEGIN CERTIFICATE-----
MIICajCCAdOgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBSMQswCQYDVQQGEwJ1czEL
...
LEzc1JwEGQQVDYQCwsQMSBDAF0QAB0w9GikhqkgBNADABIgABIwAgOdACCjaCIIM
-----END CERTIFICATE-----

  4. בקטע ספק שירותים, מזינים את מזהה הישות של האפליקציה. בדרך כלל זה כתובת ה-URL של האפליקציה. בספק הזהויות של SAML, זה נקרא הקהל.

  5. בחלונית הצדדית Project settings (הגדרות הפרויקט), לוחצים על Add Domain (הוספת דומיין) ומוסיפים את הדומיין של האפליקציה. לדוגמה, אם כתובת ה-URL של הכניסה לאפליקציה היא https://example.com/login, מוסיפים example.com.

  6. כדי להשלים את ההגדרה, מבצעים אחת מהפעולות הבאות:

    • מעתיקים את כתובת ה-URL של התקשרות החזרה להרשאה שמופיעה כברירת מחדל בשדה Authorization callback (URL) (התקשרות חזרה להרשאה (כתובת URL)) ומוסיפים אותה להגדרות של אפליקציית SAML.

      שימוש בכתובת ה-URL של התקשרות חזרה לאימות שמוגדרת כברירת מחדל מפחית את המורכבות של אימות תגובת SAML.

    • מוסיפים את כתובת ה-URL המותאמת אישית של הקריאה החוזרת לאישור להגדרות של אפליקציית SAML – לדוגמה, https://PROJECT-ID.firebaseapp.com/__/auth/handler.

  7. בקטע הגדרת האפליקציה, לוחצים על פרטי ההגדרה. מעתיקים את קטע הקוד לקוד של האפליקציה כדי להפעיל את ה-SDK של לקוח Identity Platform.

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

רכיבים שנדרשים על ידי הספק

ב-Identity Platform מצפים שהרכיבים <saml:Subject> ו-<saml:NameID> יופיעו בתגובות מהספק. אם לא מגדירים ערכים לרכיבים האלה כשמגדירים את הספק, טענת ה-SAML נכשלת.

בקשות לחתימה

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

כדי לחתום על בקשות, קודם צריך להפעיל בקשות חתומות עבור ספק הזהויות על ידי קריאה ל-inboundSamlConfigs.patch() והגדרת idp_config.sign_request ל-true:

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫project-id: המזהה של Google Cloud הפרויקט
  • ‫provider-id: מזהה ספק SAML

ה-method של ה-HTTP וכתובת ה-URL: 

PATCH https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest

תוכן בקשת JSON: 

{
  "idp_config": {
    "sign_request": true
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

 

כדי להפעיל בקשות חתומות, צריך להשתמש ב-API ל-REST. אי אפשר להשתמש במסוףGoogle Cloud או ב-Google Cloud CLI.

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

החלפת אישורים של ספקי שירות

כשמשתמשים בבקשות SAML חתומות, Identity Platform משתמש באישור של ספק שירותים (SP). כדי למנוע שיבושים באימות, חשוב לעקוב אחרי תאריך התפוגה של אישורי ה-SP ולחדש אותם לפני שהוא מגיע.

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

    curl -s -X GET "https://identitytoolkit.googleapis.com/v2/projects/PROJECT_ID/inboundSamlConfigs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    -H "Content-Type: application/json" | \
    jq -r '.inboundSamlConfigs[].spConfig.spCertificates[]?.expiresAt'

    מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud.

    בודקים את הערך של expiresAt בקטע spConfig.spCertificates.

  2. אם חותמת הזמן של התפוגה (expiresAt) היא תוך 30 יום או תוך פרק הזמן שנדרש על ידי הארגון שלכם, צריך לפנות אל Cloud Customer Care ואל מנהל ה-IdP כדי לתכנן את העדכון במהלך השבתה מתוזמנת.

  3. כדי לבצע רוטציה של האישור ולקבל את האישור הציבורי החדש, צריך לפנות ל-Cloud Customer Care.

  4. כדי לעדכן את הגדרת האישור ב-IdP, משתפים את אישור ה-SP החדש עם האדמין של ה-IdP.

  5. בודקים אם הכניסה היחידה (SSO) פועלת עם ההגדרה המעודכנת.

כניסה של משתמשים לחשבון

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

  1. יוצרים מכונת SAMLAuthProvider עם מזהה הספק שהגדרתם בקטע הקודם. מזהה הספק חייב להתחיל ב-saml.

    גרסה 9 לאינטרנט

    import { SAMLAuthProvider } from "firebase/auth";

const provider = new SAMLAuthProvider("saml.myProvider");

    גרסה 8 לאינטרנט

    const provider = new firebase.auth.SAMLAuthProvider('saml.myProvider');

  2. מתחילים בתהליך הכניסה. אפשר לבחור להשתמש בתיבת דו-שיח או בהפניה אוטומטית.

    גרסה 9 לאינטרנט

    import { getAuth, signInWithPopup, SAMLAuthProvider } from "firebase/auth";

const auth = getAuth();
signInWithPopup(auth, provider)
  .then((result) => {
    // User is signed in.
    // Provider data available from the result.user.getIdToken()
    // or from result.user.providerData
  }).catch((error) => {
    // Handle Errors here.
    const errorCode = error.code;
    const errorMessage = error.message;
    // The email of the user's account used.
    const email = error.customData.email;
    // The AuthCredential type that was used.
    const credential = SAMLAuthProvider.credentialFromError(error);
    // Handle / display error.
    // ...
  });

    גרסה 8 לאינטרנט

    firebase.auth().signInWithPopup(provider)
  .then((result) => {
    // User is signed in.
    // Identity provider data available in result.additionalUserInfo.profile,
    // or from the user's ID token obtained from result.user.getIdToken()
    // as an object in the firebase.sign_in_attributes custom claim
    // This is also available from result.user.getIdTokenResult()
    // idTokenResult.claims.firebase.sign_in_attributes.
  })
  .catch((error) => {
    // Handle / display error.
    // ...
  });

    הפניה לכתובת URL אחרת

    כדי להפנות לדף כניסה, קוראים ל-signInWithRedirect():

    גרסה 9 לאינטרנט

    import { getAuth, signInWithRedirect } from "firebase/auth";

const auth = getAuth();
signInWithRedirect(auth, provider);

    גרסה 8 לאינטרנט

    firebase.auth().signInWithRedirect(provider);

    לאחר מכן, מתקשרים אל getRedirectResult() כדי לקבל את התוצאות כשהמשתמש חוזר לאפליקציה:

    גרסה 9 לאינטרנט

    import { getAuth, getRedirectResult, SAMLAuthProvider } from "firebase/auth";

const auth = getAuth();
getRedirectResult(auth)
  .then((result) => {
    // User is signed in.
    // Provider data available from the result.user.getIdToken()
    // or from result.user.providerData
  })
  .catch((error) => {
    // Handle Errors here.
    const errorCode = error.code;
    const errorMessage = error.message;
    // The email of the user's account used.
    const email = error.customData.email;
    // The AuthCredential type that was used.
    const credential = SAMLAuthProvider.credentialFromError(error);
    // Handle / display error.
    // ...
  });

    גרסה 8 לאינטרנט

    firebase.auth().getRedirectResult()
  .then((result) => {
    // User is signed in.
    // Provider data available in result.additionalUserInfo.profile,
    // or from the user's ID token obtained from result.user.getIdToken()
    // as an object in the firebase.sign_in_attributes custom claim
    // This is also available from result.user.getIdTokenResult()
    // idTokenResult.claims.firebase.sign_in_attributes.
  }).catch((error) => {
    // Handle / display error.
    // ...
  });

  3. מאחזרים את מאפייני המשתמש שמשויכים לספק SAML מאסימון הזהות באמצעות הטענה firebase.sign_in_attributes. חשוב לאמת את טוקן של מזהה באמצעות SDK לאדמינים כששולחים אותו לשרת.

    טוקן המזהה כולל את כתובת האימייל של המשתמש רק אם היא מופיעה במאפיין NameID של טענת הנכוֹנוּת (assertion) של SAML מספק הזהויות:

    <Subject>
  <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">test@email.com</NameID>
</Subject>

    השדה הזה מאוכלס בטוקן של מזהה שהונפק על ידי Firebase ובאובייקט UserInfo.

נתמכות רק זרימות SAML שיוזם ספק השירות מתוך ה-SDK של הלקוח.

אם משתמש כבר נכנס לאפליקציה שלכם בשיטה אחרת (למשל באמצעות כתובת אימייל וסיסמה), אתם יכולים לקשר את החשבון הקיים שלו לספק SAML באמצעות linkWithPopup() או linkWithRedirect().

בקטע הקוד הבא אפשר לראות איך לקשר את חשבון Google של משתמש לספק SAML:

גרסה 9 לאינטרנט

import { getAuth, linkWithPopup, GoogleAuthProvider } from "firebase/auth";
const provider = new GoogleAuthProvider();

const auth = getAuth();
linkWithPopup(auth.currentUser, provider).then((result) => {
  // Accounts successfully linked.
  const credential = GoogleAuthProvider.credentialFromResult(result);
  const user = result.user;
  // ...
}).catch((error) => {
  // Handle Errors here.
  // ...
});

גרסה 8 לאינטרנט

auth.currentUser.linkWithPopup(provider).then((result) => {
  // Accounts successfully linked.
  var credential = result.credential;
  var user = result.user;
  // ...
}).catch((error) => {
  // Handle Errors here.
  // ...
});

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