ניהול בקרת הגישה

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

סקירה כללית על בקרת גישה לנתונים

בקרת גישה לנתונים היא תכונה מרכזית ב-Document AI Warehouse. היא קובעת למי תהיה גישה למשאב מסוים ב-Document AI Warehouse, ומה תהיה רמת הגישה שלו.

ממשקי ה-API של Document AI Warehouse מבוססים על Google Cloud. פרוטוקול HTTPS משמש כדי להבטיח העברת נתונים מאובטחת באינטרנט. האימות וההרשאה נאכפים בממשקי ה-API של Document AI Warehouse כדי להגן על השירות ועל נתוני המשתמשים על סמך זהויות Google.

ממשקי Document AI Warehouse API משתמשים ב-OAuth2 לאימות באמצעות חשבון משתמש. כל השיטות של API דורשות את היקף ההרשאות של OAuth‏ https://www.googleapis.com/auth/cloud-platform.

מחסן Document AI אוכף בקרת גישה לנתוני לקוחות על סמך Cloud IAM. ב-Document AI Warehouse מוגדרות קבוצות של תפקידים והרשאות שמשויכות אליהם, כדי שתוכלו להגביל את הגישה של משתמשים שונים לנתונים שמאוחסנים בשירות שלנו. למידע נוסף, אפשר לעיין בקטע תפקידים והרשאות ב-IAM.

שימוש בחשבון שירות כדי לאכוף בקרת גישה בסיסית

צריך חשבון שירות עם ההרשאות הנדרשות כדי לגשת ל-Document AI Warehouse API. אם מבצעים את השלב 'הקצאת הרשאות דרך המסוף' במדריך ההפעלה המהירה, מוקצה אוטומטית חשבון שירות עם התפקיד 'אדמין של Document AI Warehouse'. Google Cloud

מצב בקרת גישה

ב-Document AI Warehouse יש שלושה מצבים של בקרת גישה:

  • גישה אוניברסלית: אין בקרת גישה ברמת המסמך
  • בקרת גישה ברמת המסמך באמצעות שירות זהויות משלכם
  • בקרת גישה ברמת המסמך באמצעות Cloud Identity

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

גישה אוניברסלית

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

במצב הזה, אחרי שמסיימים את תהליך הקצאת ההרשאות שמפורט במדריך התחלת העבודה המהירה, לכם ולכל המשתמשים שלכם תהיה גישה לכל המסמכים בפרויקט Google Cloudשנבחר בשירות Document AI Warehouse, באמצעות חשבון השירות ועם ההרשאות שמשויכות לחשבון השירות.

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

בקרת גישה ברמת המסמך

משתמשי Document AI Warehouse יכולים:

  • שימוש בשירות זהויות משלכם
    • גם משתמש הקצה וגם קבוצות החברות של משתמשי הקצה נדרשים במטא-נתונים של הבקשה. אם לחברה שלכם יש דרך משלה לאימות המשתמש ולזיהוי הקבוצות שהמשתמש שייך אליהן, אתם יכולים להשתמש באפשרות הזו.
  • שימוש ב-Cloud Identity
    • במטא-נתונים של הבקשה נדרש רק משתמש הקצה, כי Document AI Warehouse אוסף את קבוצות החברים מ-Cloud Identity בשביל הלקוחות. ההבדל בין זה לבין שימוש בשירות זהויות מותאם אישית הוא שאתם מנהלים את החברות של המשתמשים בקבוצות באמצעות Cloud Identity ולא באמצעות מערכת פנימית.

יש כמה מגבלות לשימוש במצב הגישה ברמת המסמך:

  • רק חברים ותפקידים בACL נתמכים. התנאים של IAM מוזנחים.
  • אין תמיכה בתפקידים בהתאמה אישית ברשימת בקרת הגישה.
  • ‫Document AI Warehouse לא מאמת את פרטי הכניסה של משתמשי הקצה. ‫Document AI Warehouse מאמת רק את פרטי הכניסה של חשבון השירות כדי לוודא שהקריאות מגיעות מהלקוחות. צריך לאמת את פרטי הכניסה של משתמש הקצה בצד של הלקוח.
  • כדי לאכוף את בקרת הגישה, הלקוחות צריכים לספק את משתמש הקצה (ואת כל הקבוצות שמשתמש הקצה חבר בהן, אם הם לא משתמשים באפשרות Cloud Identity) במטא-נתונים של הבקשה.
  • מספר קבוצות החברות של משתמש הקצה צריך להיות קטן מ-100.

בקרת גישה ברמת המסמך באמצעות שירות הזהויות של הלקוח

אפשר לבחור במצב הזה אם רוצים:

  • להעניק למשתמשי קצה (קבוצות) הרשאות שונות לגישה לכל אחד מהמסמכים.
  • שימוש בשירות ניהול זהויות משלכם.

המצב הזה מאפשר להשתמש ב-IAM וברשימות של בקרת גישה (ACL) יחד כדי לנהל את ההרשאות. אפשר להגדיר לכל מסמך במאגר Document AI רשימת ACL ספציפית ברמת המסמך. האימות וההרשאה מתבצעים באופן הבא:

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

מערכת Document AI Warehouse מעניקה גישה למסמך המבוקש רק אם מתקיימים שני התנאים שמופיעים ברשימה הקודמת.

הפרטים של UserInfo (כולל מזהה משתמש הקצה ומזהי קבוצות החברות של המשתמש) של RequestMetadata שסופקו בקריאה ל-API משמשים כדי לאמת אם משתמש הקצה מורשה לבצע את הפעולה המתאימה על משאב המסמך המבוקש. לדוגמה, ה-UserInfo שמופיע ב-API‏ GetDocument משמש לאימות של הרשאת משתמש הקצה לצפייה במסמך. אם למשתמש הקצה או לאחת מקבוצות החברים יש הרשאה לצפות במסמך, אז למשתמש הקצה יש הרשאה לצפות במסמך.

דוגמה ל-RequestMetadata בפורמט JSON:

request_metadata: {
    user_info: {
        id: user:fake_user_id
        group_ids: [
            group:fake_group_id_1,
            group:fake_group_id_2,
            group:fake_group_id_3,
        ]
    }
}

בנוסף להוראות במדריך תחילת העבודה, כדי להשתמש במצב בקרת הגישה הזה צריך לבצע כמה שלבים נוספים לפני שמתחילים לשלוח ממשקי API אל Document AI Warehouse:

  1. אחזור של חברות בקבוצות של משתמש קצה נתון משירות הספריות (לדוגמה, Azure Active Directory או Okta).
  2. כדי להגדיר מדיניות פרויקט שמוגדרת כברירת מחדל, פועלים לפי ההוראות בקטע הגדרת בקרת גישה. אפשר גם להגדיר רשימת ACL ברמת המסמך למסמכים ספציפיים אחרי היצירה.

אחרי שמבצעים את השלבים הקודמים, אפשר להשתמש בחשבון השירות כדי לבצע קריאות API אל Document AI Warehouse עם פרטים של משתמש הקצה וחברות בקבוצה בקטע RequestMetadata של גוף הבקשה.

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

כפתרון מוכן לשימוש, מסוף Document AI Warehouse הוא פרוקסי שיכול לאחסן את המפתח של חשבון השירות, לאמת את משתמשי הקצה באמצעות הזהויות שלהם ב-Google ולהעביר את הבקשות אל Document AI Warehouse.

בקרת גישה ברמת המסמך באמצעות Cloud Identity

אפשרות נוספת היא להשתמש ב-Cloud Identity כדי לפשט את התהליך, במקום להשתמש בשירות הזהויות שלכם.

כדי לנהל משתמשים וקבוצות באופן מרכזי,לקוחות יכולים להגדיר את Cloud Identity מאפס או לאחד זהויות בין Google לבין ספקי זהויות אחרים, כמו Active Directory ו-Azure Active Directory. Google Cloud

הקטע UserInfo של RequestMetadata שמופיע בקריאה ל-API משמש לאימות שלמשתמש הקצה יש הרשאה לבצע את הפעולה המתאימה על משאב המסמך המבוקש. כשמשתמשים ב-Cloud Identity, צריך לציין רק את מזהה משתמש הקצה ב-RequestMetadata, ומאגר Document AI אוסף את פרטי קבוצת ההרשאה משירות זהות Cloud Identity. אם למשתמש הקצה או לאחת מהקבוצות שהוא חבר בה יש הרשאה לגשת למסמך, אז למשתמש הקצה יש הרשאה לגשת למסמך.

דוגמה ל-RequestMetadata בפורמט JSON:

request_metadata: {
    user_info: {
        id: user:fake_user_id
    }
}

בנוסף להוראות במדריך התחלה מהירה, כדי להשתמש במצב בקרת הגישה הזה צריך לבצע כמה שלבים נוספים לפני שמתחילים לשלוח בקשות אל Document AI Warehouse:

  1. שילוב עם Cloud Identity עבור משתמשי הקצה והקבוצות.
  2. כדי להגדיר מדיניות פרויקט שמוגדרת כברירת מחדל, פועלים לפי ההוראות בקטע הגדרת בקרת גישה. אפשר גם להגדיר רשימת ACL ברמת המסמך למסמכים ספציפיים אחרי היצירה.

אחרי שמבצעים את השלבים הקודמים, אפשר להשתמש בחשבון השירות כדי לבצע קריאות API אל Document AI Warehouse עם פרטי משתמשי קצה בקטע RequestMetadata של גוף הבקשה.

הגדרת בקרת הגישה

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

לפני שמתחילים, חשוב לוודא שסיימתם את השלבים במדריך למתחילים.

SetAcl ו-FetchAcl

כשיוצרים פרויקט חדש, לא מוגדרת רשימת ACL של הפרויקט. בעלי הפרויקט יכולים לשלוח קריאה ל-Document AI Warehouse SetAcl API כדי להגדיר מדיניות פרויקט כברירת מחדל באמצעות תפקידים מוגדרים מראש לפרויקט. לשם כך, צריך להגדיר את השדה projectOwner לערך true באמצעות חשבון השירות. לחברים במדיניות הפרויקט יש גישה לכל המסמכים בפרויקט, בהתאם לתפקידים שהוקצו להם. אפשר להעניק למשתמשים או לקבוצות עם הרשאת אדמין גישה למדיניות הפרויקט שמוגדרת כברירת מחדל.

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

כדי לבצע קריאות ל-Document Schema API באמצעות חשבון השירות, אפשר לעיין במאמר projects.locations.documentSchemas.

שיטת ה-API של המסמך התפקידים הנדרשים
CreateDocument roles/contentwarehouse.documentCreator
UpdateDocument roles/contentwarehouse.documentEditor
DeleteDocument
SetACL		 roles/contentwarehouse.documentAdmin
GetDocument
FetchACL
SearchDocuments		 roles/contentwarehouse.documentViewer

CreateDocument

אם לא הוענקה גישה למשתמש הקצה או לקבוצה, צריך להעניק להם גישת יוצר:

  • [אופציונלי] אחזור קבוצות חברים עבור האדמין של משתמש הקצה משירות הזהויות של הלקוח. לקוחות שמשתמשים ב-Cloud Identity יכולים לדלג על השלב הזה.
  • מעניקים למשתמש קצה א' (או לקבוצה שמשתמש קצה א' חבר בה) את התפקיד roles/contentwarehouse.documentCreator ברמת הפרויקט על ידי ביצוע הקריאה אל SetAcl באמצעות חשבון השירות עם אדמין משתמש קצה [וקבוצות חברים] במטא-נתונים של הבקשה. למשתמש האדמין הסופי יש גישת documentAdmin ברמת הפרויקט.

כדי ליצור מסמך:

  • אופציונלי: אחזור קבוצות חברות עבור משתמש קצה א' משירות הזהויות. אם אתם משתמשים ב-Cloud Identity, אתם יכולים לדלג על השלב הזה.
  • מבצעים את הקריאה אל CreateDocument עם משתמש הקצה א' [וקבוצות החברים] במטא-נתונים של הבקשה כדי ליצור מסמך באמצעות חשבון השירות. אחרי שהמסמך נוצר, משתמש הקצה א' יכול לראות ולערוך את המסמך כברירת מחדל. לקוחות יכולים גם לציין מדיניות ברירת מחדל כדי להעניק למשתמשים או לקבוצות גישה במהלך היצירה. לדוגמה, הענקת גישת documentViewer לקבוצה X, גישת documentEditor לקבוצה Y וגישת documentAdmin לקבוצה Z.

GetDocument ו-FetchAcl

אחרי שהמסמך נוצר, משתמש הקצה א' או החברים בקבוצה X, בקבוצה Y או בקבוצה Z יכולים להתקשר למספר GetDocument כדי לראות את המסמך, או להתקשר למספר FetchAcl כדי לראות את רשימת בקרת הגישה של המסמך. אלה השלבים:

  1. אופציונלי: אחזור קבוצות חברות עבור משתמש קצה א' משירות הזהויות. אם אתם משתמשים ב-Cloud Identity, אתם יכולים לדלג על השלב הזה.
  2. מבצעים את הקריאה אל GetDocument או אל FetchAcl באמצעות חשבון השירות עם משתמש הקצה א' (וקבוצות החברים) במטא-נתונים של הבקשה.

השיחה ממשתמש הקצה ב' תידחה אם ב' לא חבר בקבוצה X, בקבוצה Y או בקבוצה Z.

UpdateDocument,‏ DeleteDocument ו-SetAcl

אחרי יצירת המסמך, רק משתמש הקצה א' או חברים בקבוצה Y או בקבוצה Z יכולים להתקשר אל UpdateDocument כדי לעדכן את המסמך. רק משתמש הקצה א' או חברים בקבוצה Z יכולים להתקשר אל DeleteDocument כדי למחוק את המסמך או אל SetAcl כדי לשתף את המסמך עם משתמשי קצה או קבוצות אחרים. אלה השלבים:

  1. אופציונלי: אחזור קבוצות חברות עבור משתמש קצה א' משירות הזהויות. אם אתם משתמשים ב-Cloud Identity, אתם יכולים לדלג על השלב הזה.
  2. מתקשרים אל UpdateDocument, אל DeleteDocument או אל SetAcl באמצעות חשבון השירות עם משתמש הקצה א' [וקבוצות החברים] במטא-נתונים של הבקשה.

השיחה מחברים בקבוצה X תידחה כי יש להם רק גישת documentViewer למסמך.

SearchDocuments

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

כדי לשלוח קריאה ל-API של SearchDocument, הלקוחות צריכים לבצע את השלבים הבאים.

  1. אופציונלי: אחזור קבוצות חברות עבור משתמש קצה א' משירות הזהויות. אם אתם משתמשים ב-Cloud Identity, אתם יכולים לדלג על השלב הזה.
  2. מבצעים את הקריאה אל SearchDocument באמצעות חשבון השירות עם משתמש הקצה א' (וקבוצות החברים) במטא-נתונים של הבקשה.
שיטת ה-API של Document Link התפקידים הנדרשים
CreateDocumentLink מקור: roles/contentwarehouse.documentEditor
יעד: roles/contentwarehouse.documentViewer
ListLinkedTargets
ListLinkedSources		 roles/contentwarehouse.documentViewer
DeleteDocumentLink מקור: roles/contentwarehouse.documentEditor

משתמשי הקצה יכולים לקשר בין המסמכים doc1 ו-doc2 אם יש להם הרשאת contentwarehouse.documents.update ל-doc1 והרשאת contentwarehouse.documents.get ל-doc2.

ListLinkedTargets ו-ListLinkedSources

משתמשי קצה יכולים לראות את רשימת המסמכים שמיועדים או שממקורם עם הרשאת contentwarehouse.documents.get.

משתמשי קצה יכולים למחוק את הקישורים אם יש להם הרשאת contentwarehouse.documents.update במסמכי המקור.