כניסת משתמשים באמצעות 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 של התקשרות חזרה (callback) להרשאה שמוגדרת כברירת מחדל מפחית את המורכבות של אימות תגובת 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 כדי שיוכל לאמת את החתימה של הבקשות.

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

כשמכניסים משתמש, ה-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. חשוב לאמת את טוקן ה-ID באמצעות 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.
  // ...
});

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