שימוש ב-API בארכיטקטורת REST

במסמך הזה מוסבר איך לבצע פעולות נפוצות שקשורות למשתמשים, כמו כניסה של משתמשים ועבודה עם אסימונים, באמצעות Identity Platform API בארכיטקטורת REST.

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

כדי להשתמש ב-API בארכיטקטורת REST, צריך מפתח API של Identity Platform. כדי לקבל מפתח:

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

  2. לוחצים על פרטי הגדרת האפליקציה.

  3. מעתיקים את השדה apiKey.

חשוב: כל הקריאות ל-API מחייבות שימוש ב-HTTPS.

קריאה ל-API

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

אפשר להחליף טוקן אימות בהתאמה אישית בטוקן מזהה ובטוקן לרענון על ידי שליחת בקשת HTTP‏ POST לנקודת הקצה signInWithCustomToken.

Method: POST

‫Content-Type: application/json

נקודת קצה (endpoint) 
https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=[API_KEY]
 מטען ייעודי (payload) של גוף הבקשה
שם המאפיין סוג תיאור
token מחרוזת אסימון בהתאמה אישית של Identity Platform שממנו אפשר ליצור זוג של אסימון מזהה ואסימון רענון.
returnSecureToken בוליאני האם להחזיר מזהה ואסימון רענון. הערך צריך להיות תמיד true.
tenantId מחרוזת מזהה הדייר שאליו המשתמש נכנס. הפרמטר הזה משמש רק במקרים של ריבוי דיירים.
הערך שלו חייב להיות זהה לערך של tenant_id בטוקן.
טענות לאסימון בהתאמה אישית
מאפיין (property) שם תיאור
alg אלגוריתם הערך צריך להיות RS256.
iss מנפיק כתובת האימייל בחשבון השירות של הפרויקט.
sub נושא כתובת האימייל בחשבון השירות של הפרויקט.
aud קהל https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit
IAT השעה שבה הונפק הזמן הנוכחי, בשניות מאז ראשית זמן יוניקס (Unix epoch).
exp שעת התפוגה הזמן שבו יפוג תוקף האסימון, בשניות מאז ראשית זמן יוניקס (Unix epoch). התאריך יכול להיות עד 3,600 שניות אחרי התאריך iat.
הערה: ההגדרה הזו קובעת רק את הזמן שבו יפוג התוקף של האסימון המותאם אישית עצמו. אבל אחרי שמתחברים לחשבון של משתמש באמצעות signInWithCustomToken(), הוא יישאר מחובר למכשיר עד שהסשן שלו יבוטל או עד שהמשתמש יתנתק.
uid מזהה משתמש המזהה הייחודי של המשתמש, באורך של 1 עד 36 תווים.
tenant_id מזהה דייר (tenant) המזהה של הדייר שאליו המשתמש נכנס.
תלונות (אופציונלי) טענות מותאמות אישית אופציונליות שייכללו במשתנים של כללי האבטחה auth או request.auth.
Response Payload
שם המאפיין סוג תיאור
idToken מחרוזת אסימון מזהה של Identity Platform שנוצר מהאסימון המותאם אישית שסופק.
refreshToken מחרוזת אסימון רענון של Identity Platform שנוצר מהטוקן המותאם אישית שסופק.
expiresIn מחרוזת מספר השניות עד שתוקף אסימון ה-ID יפוג.

בקשה לדוגמה 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"token":"[CUSTOM_TOKEN]","returnSecureToken":true}'

בקשה שמתבצעת בהצלחה מסומנת באמצעות קוד סטטוס HTTP 200 OK. התשובה מכילה את אסימון הזהות ואסימון הרענון של Identity Platform שמשויכים לאסימון המותאם אישית.

דוגמה לתשובה 

{
  "idToken": "[ID_TOKEN]",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600"
}

קודי שגיאה נפוצים

  • ‫INVALID_CUSTOM_TOKEN: הפורמט של הטוקן המותאם אישית שגוי או שהטוקן לא תקף מסיבה כלשהי (למשל, פג תוקפו, החתימה לא תקפה וכו')
  • ‫CREDENTIAL_MISMATCH: האסימון המותאם אישית מתאים לפרויקט אחר של Google Cloud .

החלפת טוקן רענון באסימון מזהה

אפשר לרענן את אסימון המזהה של Identity Platform על ידי שליחת בקשת HTTP POST לנקודת הקצה securetoken.googleapis.com.

Method: POST

Content-Type: application/x-www-form-urlencoded

נקודת קצה (endpoint) 
https://securetoken.googleapis.com/v1/token?key=[API_KEY]
 מטען ייעודי (payload) של גוף הבקשה
שם המאפיין סוג תיאור
grant_type מחרוזת סוג ההרשאה של טוקן הרענון, תמיד refresh_token.
refresh_token מחרוזת טוקן רענון של Identity Platform.
Response Payload
שם המאפיין סוג תיאור
expires_in מחרוזת מספר השניות עד שתוקף אסימון ה-ID יפוג.
token_type מחרוזת סוג טוקן הרענון, תמיד 'Bearer'.
refresh_token מחרוזת אסימון הרענון של Identity Platform שסופק בבקשה או אסימון רענון חדש.
id_token מחרוזת אסימון מזהה של Identity Platform.
user_id מחרוזת מספר ה-UID שמתאים לאסימון המזהה שסופק.
project_id מחרוזת מזהה הפרויקט Google Cloud .

בקשה לדוגמה 

curl 'https://securetoken.googleapis.com/v1/token?key=[API_KEY]' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=refresh_token&refresh_token=[REFRESH_TOKEN]'

בקשה שמתבצעת בהצלחה מסומנת באמצעות קוד סטטוס HTTP 200 OK. התשובה תכלול את האסימון המזהה ואת אסימון הרענון החדשים של Identity Platform.

דוגמה לתשובה 

{
  "expires_in": "3600",
  "token_type": "Bearer",
  "refresh_token": "[REFRESH_TOKEN]",
  "id_token": "[ID_TOKEN]",
  "user_id": "tRcfmLH7o2XrNELi...",
  "project_id": "1234567890"
}

קודי שגיאה נפוצים

  • ‫TOKEN_EXPIRED: פרטי הכניסה של המשתמש כבר לא בתוקף. המשתמש צריך להיכנס שוב לחשבון.
  • USER_DISABLED: חשבון המשתמש הושבת על ידי אדמין.
  • USER_NOT_FOUND: The user corresponding to the refresh token was not found. סביר להניח שהמשתמש נמחק.
  • מפתח ה-API לא תקין. צריך להעביר מפתח API תקין. (צוין מפתח API לא תקין)
  • INVALID_REFRESH_TOKEN: סופק טוקן רענון לא תקין.
  • התקבל מטען ייעודי (payload) לא תקין של JSON. השם 'refresh_tokens' לא מוכר: אי אפשר לקשור פרמטר של שאילתה. השדה 'refresh_tokens' לא נמצא בהודעת הבקשה.
  • INVALID_GRANT_TYPE: סוג ההרשאה שצוין לא חוקי.
  • ‫MISSING_REFRESH_TOKEN: לא סופק טוקן רענון.
  • PROJECT_NUMBER_MISMATCH: מספר הפרויקט של אסימון הרענון לא תואם למספר הפרויקט של מפתח ה-API שצוין.

הרשמה באמצעות כתובת אימייל וסיסמה

אפשר ליצור משתמש חדש עם כתובת אימייל וסיסמה על ידי שליחת בקשת HTTP POST לנקודת הקצה של Auth signupNewUser.

Method: POST

‫Content-Type: application/json

נקודת קצה (endpoint) 
https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]
 מטען ייעודי (payload) של גוף הבקשה
שם המאפיין סוג תיאור
אימייל מחרוזת כתובת האימייל של המשתמש שרוצים ליצור.
סיסמה מחרוזת הסיסמה שהמשתמש צריך ליצור.
returnSecureToken בוליאני האם להחזיר מזהה ואסימון רענון. הערך צריך להיות תמיד true.
tenantId מחרוזת מזהה הדייר של המשתמש שרוצים ליצור. המאפיין הזה משמש רק במערכות מרובות דיירים.
Response Payload
שם המאפיין סוג תיאור
idToken מחרוזת אסימון מזהה של Identity Platform עבור המשתמש שנוצר.
אימייל מחרוזת כתובת האימייל של המשתמש החדש שנוצר.
refreshToken מחרוזת אסימון רענון של Identity Platform עבור המשתמש שנוצר.
expiresIn מחרוזת מספר השניות עד שתוקף אסימון ה-ID יפוג.
localId מחרוזת ה-uid של המשתמש החדש שנוצר.

בקשה לדוגמה 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"email":"[user@example.com]","password":"[PASSWORD]","returnSecureToken":true}'

בקשה שמתבצעת בהצלחה מסומנת באמצעות קוד סטטוס HTTP 200 OK. התגובה מכילה את טוקן הזהות ואת טוקן הרענון של Identity Platform שמשויכים לחשבון החדש.

דוגמה לתשובה 

{
  "idToken": "[ID_TOKEN]",
  "email": "[user@example.com]",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "localId": "tRcfmLH7..."
}

קודי שגיאה נפוצים

  • EMAIL_EXISTS: כתובת האימייל כבר נמצאת בשימוש בחשבון אחר.
  • ‫OPERATION_NOT_ALLOWED: הכניסה באמצעות סיסמה מושבתת בפרויקט הזה.
  • TOO_MANY_ATTEMPTS_TRY_LATER: חסמנו את כל הבקשות מהמכשיר הזה עקב פעילות חריגה. צריך לנסות שוב מאוחר יותר. אפשר לנסות שוב אחר כך.

כניסה באמצעות כתובת אימייל או סיסמה

כדי לאפשר למשתמש להיכנס באמצעות כתובת אימייל וסיסמה, צריך לשלוח בקשת HTTP POST לנקודת הקצה של Auth verifyPassword.

Method: POST

‫Content-Type: application/json

נקודת קצה (endpoint) 
https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=[API_KEY]
 מטען ייעודי (payload) של גוף הבקשה
שם המאפיין סוג תיאור
אימייל מחרוזת כתובת האימייל שדרכה המשתמש נכנס לחשבון.
סיסמה מחרוזת הסיסמה לחשבון.
returnSecureToken בוליאני האם להחזיר מזהה ואסימון רענון. הערך צריך להיות תמיד true.
tenantId מחרוזת מזהה הדייר שאליו המשתמש נכנס. המאפיין הזה משמש רק במערכות מרובות דיירים.
Response Payload
שם המאפיין סוג תיאור
idToken מחרוזת טוקן ID של Identity Platform עבור המשתמש המאומת.
אימייל מחרוזת כתובת האימייל של המשתמש המאומת.
refreshToken מחרוזת אסימון רענון של Identity Platform עבור המשתמש המאומת.
expiresIn מחרוזת מספר השניות עד שתוקף אסימון ה-ID יפוג.
localId מחרוזת מזהה המשתמש המאומת.
רשום בוליאני האם כתובת האימייל שייכת לחשבון קיים.

בקשה לדוגמה 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"email":"[user@example.com]","password":"[PASSWORD]","returnSecureToken":true}'

בקשה שמתבצעת בהצלחה מסומנת באמצעות קוד סטטוס HTTP 200 OK. התשובה תכיל את אסימון הזהות ואסימון הרענון של Identity Platform שמשויכים לחשבון הקיים עם כתובת האימייל והסיסמה.

דוגמה לתשובה 

{
  "localId": "ZY1rJK0eYLg...",
  "email": "[user@example.com]",
  "displayName": "",
  "idToken": "[ID_TOKEN]",
  "registered": true,
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600"
}

קודי שגיאה נפוצים

  • EMAIL_NOT_FOUND: אין רשומת משתמש שתואמת למזהה הזה. יכול להיות שהמשתמש נמחק.
  • INVALID_PASSWORD: הסיסמה לא תקינה או שלמשתמש אין סיסמה.
  • USER_DISABLED: חשבון המשתמש הושבת על ידי אדמין.

כניסה אנונימית

אפשר להכניס משתמש באופן אנונימי על ידי שליחת בקשת HTTP ‏POST לנקודת הקצה (endpoint) של Auth ‏signupNewUser.

Method: POST

‫Content-Type: application/json

נקודת קצה (endpoint) 
https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]
 מטען ייעודי (payload) של גוף הבקשה
שם המאפיין סוג תיאור
returnSecureToken בוליאני האם להחזיר מזהה ואסימון רענון. הערך צריך להיות תמיד true.
tenantId מחרוזת מזהה הדייר שאליו המשתמש נכנס. המאפיין הזה משמש רק במערכות מרובות דיירים.
Response Payload
שם המאפיין סוג תיאור
idToken מחרוזת אסימון מזהה של Identity Platform עבור המשתמש שנוצר.
אימייל מחרוזת השדה הזה צריך להיות ריק כי המשתמש אנונימי.
refreshToken מחרוזת אסימון רענון של Identity Platform עבור המשתמש שנוצר.
expiresIn מחרוזת מספר השניות עד שתוקף אסימון ה-ID יפוג.
localId מחרוזת ה-uid של המשתמש החדש שנוצר.

בקשה לדוגמה 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]' \
-H 'Content-Type: application/json' --data-binary '{"returnSecureToken":true}'

בקשה שמתבצעת בהצלחה מסומנת באמצעות קוד סטטוס HTTP 200 OK. התשובה מכילה את טוקן ה-ID ואת טוקן הרענון של Identity Platform שמשויכים למשתמש לא רשום.

דוגמה לתשובה 

{
  "idToken": "[ID_TOKEN]",
  "email": "",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "localId": "Jws4SVjpT..."
}

קודי שגיאה נפוצים

  • ‫OPERATION_NOT_ALLOWED: הכניסה של משתמשים לא רשומים מושבתת בפרויקט הזה.