יצירת מחבר זהות

כברירת מחדל, Google Cloud Search מזהה רק זהויות Google שמאוחסנות ב- Google Cloud Directory (משתמשים וקבוצות). משתמשים במחברי זהויות כדי לסנכרן את זהויות הארגון עם הזהויות של Google שמשמשות את Google Cloud Search.

Google מספקת את האפשרויות הבאות לפיתוח מחברי זהויות:

• ה-SDK של מחבר הזהויות. האפשרות הזו מיועדת למפתחים שמתכנתים בשפת התכנות Java. ה-SDK של Identity Connector הוא wrapper סביב ה-API ל-REST וכך תוכלו ליצור מחברים במהירות. כדי ליצור מחבר הזהויות שמשתמש ב-SDK, יוצרים מחבר זהויות באמצעות Identity Connector SDK.

• API ל-REST וספריות API ברמה נמוכה. האפשרויות האלה מיועדות למפתחים לא מתכנתים ב-Java או שבסיס הקוד שלהם מתאים יותר API ל-REST או ספרייה. כדי ליצור מחבר זהויות באמצעות API ל-REST: כדי Directory API: חשבונות משתמשים של על מיפוי משתמשים מסמכי העזרה של Cloud Identity עבור על מיפוי של קבוצות.

יצירת מחבר זהויות באמצעות ה-SDK של מחבר זהויות

מחבר זהויות אופייני מבצע את המשימות הבאות:

1. מגדירים את המחבר.
2. אחזור כל המשתמשים ממערכת הזהויות של הארגון ושליחתם אל Google לסנכרון עם הזהויות של Google.
3. אחזור כל הקבוצות ממערכת הזהויות של הארגון ושליחתן אל Google לסנכרון עם הזהויות של Google.

הגדרת יחסי תלות

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

<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-identity-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>

 compile group: 'com.google.enterprise.cloudsearch',
         name: 'google-cloudsearch-identity-connector-sdk',
         version: 'v1-0.0.3'

הגדרה של תצורת המחבר

לכל מחבר יש קובץ תצורה שמכיל פרמטרים המשמשים את של המאגר, כמו המזהה של המאגר. הפרמטרים מוגדרים כך צמדי key-value, כמו api.sourceId=1234567890abcdef.

ב-Google Cloud Search SDK יש כמה הגדרות ש-Google מספקת הפרמטרים שבהם משתמשים כל המחברים. עליך להצהיר על הפרטים הבאים הפרמטרים ש-Google מספקת בקובץ התצורה:

• עבור מחבר תוכן, צריך להצהיר על api.sourceId וגם api.serviceAccountPrivateKeyFile כי הפרמטרים האלה מזהים את המיקום של המאגר והמפתח הפרטי שנדרשים כדי לגשת למאגר.

• עבור מחבר זהויות, עליך להצהיר על api.identitySourceId בתור מזהה את המיקום של מקור הזהות החיצוני. אם אתם משתמשים שמסתנכרנים, צריך גם להצהיר על api.customerId כמזהה הייחודי של חשבון Google Workspace של הארגון.

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

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

מעבירים את קובץ התצורה למחבר

מגדירים את מאפיין המערכת config כדי להעביר את קובץ התצורה אל למחבר. אפשר להגדיר את המאפיין באמצעות הארגומנט -D כשמתחילים של המחבר. לדוגמה, הפקודה הבאה מפעילה את המחבר עם קובץ התצורה MyConfig.properties:

java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector

אם הארגומנט הזה חסר, ערכת ה-SDK תנסה לגשת להגדרות ברירת מחדל בשם connector-config.properties.

יצירת מחבר זהויות של סנכרון מלא באמצעות מחלקה של תבניות

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

החלק הזה במסמכים מתייחס לקטעי קוד קטע לדוגמה אחד (IdentityConnecorSample.java). הדוגמה הזו קוראת את הטקסט 'משתמש וקבוצה' זהויות משני קובצי CSV ומסנכרנת אותן עם הזהויות של Google.

הטמעת נקודת הכניסה של המחבר

נקודת הכניסה למחבר היא אמצעי תשלום אחד (main()). המשימה העיקרית של השיטה הזו היא ליצור מופע של Application את הכיתה ולהפעיל start() כדי להריץ את המחבר.

לפני השיחה application.start() להשתמש IdentityApplication.Builder של הכיתה כדי ליצור תבנית FullSyncIdentityConnector. FullSyncIdentityConnector מקבל Repository את האובייקט שהשיטות שלו תטמיעו. בקטע הקוד הבא אפשר לראות איך להטמיע את השיטה main():

/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * sync connector. In the full sync case, the repository is responsible
 * for providing a snapshot of the complete identity mappings and
 * group rosters. This is then reconciled against the current set
 * of mappings and groups in Cloud Directory.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new CsvRepository();
  IdentityConnector connector = new FullSyncIdentityConnector(repository);
  IdentityApplication application = new IdentityApplication.Builder(connector, args).build();
  application.start();
}

מאחורי הקלעים, ה-SDK קורא ל- initConfig() אחרי הפעלת ה-method main() של המחבר Application.build. השיטה initConfig() מבצעת את המשימות הבאות:

1. קורא ל- Configuation.isInitialized() כדי לוודא Configuration לא אותחל.
2. הפעלת אובייקט Configuration עם מפתח/ערך ש-Google סיפקה זוגות של מילים. כל צמד מפתח/ערך מאוחסן ConfigValue בתוך האובייקט Configuration.

הטמעת הממשק של Repository

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

• init() . כדי לבצע הגדרה ואתחול של מאגר זהויות, מבטלים את השינוי ה-method 'init() '.

• listUsers() . כדי לסנכרן את כל המשתמשים במאגר הזהויות עם משתמשי Google, משנים את ההגדרה השיטה listUsers().

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

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

אחזור פרמטרים מותאמים אישית של הגדרות אישיות

כחלק מהטיפול בתצורת המחבר שלך, תצטרך לקבל של הפרמטרים המותאמים אישית Configuration לאובייקט. משימה זו מתבצעת בדרך כלל Repository של הכיתה init() .

בכיתה Configuration יש כמה שיטות לקבלת סוגי נתונים שונים ממערך הגדרות אישיות. כל שיטה מחזירה ConfigValue לאובייקט. אחר כך תשתמשו באובייקט ConfigValue get() שמאחזר את הערך בפועל. קטע הקוד הבא מראה איך לאחזר את userMappingCsvPath ערך groupMappingCsvPath מאובייקט Configuration:

/**
 * Initializes the repository once the SDK is initialized.
 *
 * @param context Injected context, contains convenienve methods
 *                for building users & groups
 * @throws IOException if unable to initialize.
 */
@Override
public void init(RepositoryContext context) throws IOException {
  log.info("Initializing repository");
  this.context = context;
  userMappingCsvPath = Configuration.getString(
      "sample.usersFile", "users.csv").get().trim();
  groupMappingCsvPath = Configuration.getString(
      "sample.groupsFile", "groups.csv").get().trim();
}

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

ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

הצגת המיפוי לכל המשתמשים

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

1. קבלת מיפוי שכולל את הזהות של Google ואת מקורות הזיהוי החיצוניים המשויכים אליה זהות.
2. אורזים את הצמדה באיטרטור שהוחזר באמצעות השיטה listUsers().

אחזור של מיפוי משתמשים

קטע הקוד הבא מראה איך מאחזרים את מיפויי הזהויות מאוחסנות בקובץ CSV:

/**
 * Retrieves all user identity mappings for the identity source. For the
 * full sync connector, the repository must provide a complete snapshot
 * of the mappings. This is reconciled against the current mappings
 * in Cloud Directory. All identity mappings returned here are
 * set in Cloud Directory. Any previously mapped users that are omitted
 * are unmapped.
 *
 * The connector does not create new users. All users are assumed to
 * exist in Cloud Directory.
 *
 * @param checkpoint Saved state if paging over large result sets. Not used
 *                   for this sample.
 * @return Iterator of user identity mappings
 * @throws IOException if unable to read user identity mappings
 */
@Override
public CheckpointCloseableIterable<IdentityUser> listUsers(byte[] checkpoint)
    throws IOException {
  List<IdentityUser> users = new ArrayList<>();
  try (Reader in = new FileReader(userMappingCsvPath)) {
    // Read user mappings from CSV file
    CSVParser parser = CSVFormat.RFC4180
        .withIgnoreSurroundingSpaces()
        .withIgnoreEmptyLines()
        .withCommentMarker('#')
        .parse(in);
    for (CSVRecord record : parser.getRecords()) {
      // Each record is in form: "primary_email", "external_id"
      String primaryEmailAddress = record.get(0);
      String externalId = record.get(1);
      if (primaryEmailAddress.isEmpty() || externalId.isEmpty()) {
        // Skip any malformed mappings
        continue;
      }
      log.info(() -> String.format("Adding user %s/%s",
          primaryEmailAddress, externalId));

      // Add the identity mapping
      IdentityUser user = context.buildIdentityUser(
          primaryEmailAddress, externalId);
      users.add(user);
    }
  }
  // ...
}

יצירת חבילה של מיפוי משתמשים באיטרטור

listUsers() מחזירה את הערך Iterator, בייחוד CheckpointCloseableIterable, מתוך IdentityUser אובייקטים. אפשר להשתמש CheckpointClosableIterableImpl.Builder כדי ליצור ולהחזיר איטרטור. קטע הקוד הבא מראה איך כדי לארוז כל מיפוי לרשימה, יוצרים את האיטרטור list:

CheckpointCloseableIterable<IdentityUser> iterator =
  new CheckpointCloseableIterableImpl.Builder<IdentityUser>(users)
      .setHasMore(false)
      .setCheckpoint((byte[])null)
      .build();

קבוצה

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

1. מקבלים את הקבוצה ואת החברים בה.
2. לארוז כל קבוצה וחברים באיטרטור שהוחזר על ידי אמצעי תשלום אחד (listGroups()).

קבלת זהות הקבוצה

קטע הקוד הבא מראה איך לאחזר את הקבוצות והחברים מאוחסנות בקובץ CSV:

/**
 * Retrieves all group rosters for the identity source. For the
 * full sync connector, the repository must provide a complete snapshot
 * of the rosters. This is reconciled against the current rosters
 * in Cloud Directory. All groups and members  returned here are
 * set in Cloud Directory. Any previously created groups or members
 * that are omitted are removed.
 *
 * @param checkpoint Saved state if paging over large result sets. Not used
 *                   for this sample.
 * @return Iterator of group rosters
 * @throws IOException if unable to read groups
 */    @Override
public CheckpointCloseableIterable<IdentityGroup> listGroups(byte[] checkpoint)
    throws IOException {
  List<IdentityGroup> groups = new ArrayList<>();
  try (Reader in = new FileReader(groupMappingCsvPath)) {
    // Read group rosters from CSV
    CSVParser parser = CSVFormat.RFC4180
        .withIgnoreSurroundingSpaces()
        .withIgnoreEmptyLines()
        .withCommentMarker('#')
        .parse(in);
    for (CSVRecord record : parser.getRecords()) {
      // Each record is in form: "group_id", "member"[, ..., "memberN"]
      String groupName = record.get(0);
      log.info(() -> String.format("Adding group %s", groupName));
      // Parse the remaining columns as group memberships
      Supplier<Set<Membership>> members = new MembershipsSupplier(record);
      IdentityGroup group = context.buildIdentityGroup(groupName, members);
      groups.add(group);
    }
  }
  // ...

}

לארוז את הקבוצה ואת החברים באיטרטור

listGroups() מחזירה את הערך Iterator, בייחוד CheckpointCloseableIterable, מתוך IdentityGroup אובייקטים. אפשר להשתמש CheckpointClosableIterableImpl.Builder כדי ליצור ולהחזיר איטרטור. קטע הקוד הבא מראה איך לארוז כל קבוצה וחברים לרשימה וליצור ממנה את האיטרטור list:

CheckpointCloseableIterable<IdentityGroup> iterator =
   new CheckpointCloseableIterableImpl.Builder<IdentityGroup>(groups)
      .setHasMore(false)
      .setCheckpoint((byte[])null)
      .build();

השלבים הבאים

אפשר לנסות את הפתרונות הבאים:

• (אופציונלי) הטמעה של Close() לשחרור משאבים לפני הכיבוי.
• (אופציונלי) יצירת מחבר תוכן באמצעות ה-SDK של מחבר התוכן.