ניהול/ביצוע אימות דו-שלבי
הפקודה היא - MFASession
השירות מאפשר לנהל כמה חלקים שקשורים לאימות הדו-שלבי, לבצע אימות דו שלבי בחיבור הנוכחי, לנהל שיטות התחברות, ועוד.
בכל פניה יש לצרף:
פרמטר
תיאור
סוג
token
טוקן
string
action
פעולה לביצוע
string
שימו לב: לא כל הפעולות אפשריות בכל שלב. יבואר בכל פעולה השלב שניתן לפנות אליה.
פעולות:
בדיקת האם הסשן עבר אימות דו-שלבי - isPass
הפעולה היא - isPass
כל סשן חייב להיות במצב ״pass״ של מנגנון האימות הדו-שלבי, אחרת עליו לבצע אימות דו-שלבי בפועל - לפני היכולת להשתמש עם כל שירות אחר בAPI. כאשר סשן לא עבר אימות דו שלבי - הוא יכול לגשת רק לשירות MFASession - וגם בו - לחלקים מסויימים. הדברים יבוארו בהמשך.
דרישה מקדימה לשימוש בשירות זה: אין.
מצב שבו השירות לא זמין: אין.
פירוט מענה:
מאפיין
סוג
הסבר
דוגמא
הערה
responseStatus
string
סטטוס הפעולה
OK
isAvailable
boolean
האם יש יכולת לבצע אימות דו-שלבי - מבחינת שיש שיטות אימות זמינות.
true
כאשר סשן לא עבר אימות - ואין אפשרות טכנית לאמת אותו - לא ניתן לבצע שום פעולות.
isPass
boolean
האם הסשן עבר אימות בהצלחה
true
לאחר שהסשן אומת - ישנם פעולות שלא ניתן לבצע בגלל זה, אבל ניתן להשתמש בסשן לטובת גישה לכל השירותים (שלא דורשים אימות קשיח - יבואר בהמשך).
passReason
string
סיבת מעבר מנגנון האימות הדו שלבי.
MFA_PASSED
ישנם הרבה סיבות למה הסשן עבר את מנגנון האימות הדו שלבי - ניתן לראות בטבלא את הסיבות האפשריות.
isPassInThisSession
boolean
האם הסשן עבר אימות בפועל בחיבור הנוכחי (אימות קשיח)
true
בהמשך לפרמטר מעלה - ישנם מצבים שבו הסשן ״עבר״ את מנגנון האימות הדו-שלבי - בגלל סיבות ש״פוטרות״ אותו מהצורך לבצע אימות דו שלבי בפועל - אבל לא בוצע ממש באותו הסשן אימות דו-שלבי. ישנם פעולות שדורשות ״אימות קשיח״ = רמה חזקה יותר של אימות - וזה דורש שיבוצע אימות דו-שלבי ממש באותו החיבור ממנו רוצים לגשת לשירותים האלה.
פירוט סיבות מעבר אימות:
כאמור, יש הבדל בין ״מעבר במנגון האימות הדו-שלבי״ לבין ״ביצוע אימות דו שלבי בפועל״.
בטבלא זו ניתן לראות פירוט של סוגי הסיבות שניתן לעבור בגינם במנגנון האימות - את הפירוט שלהם.
סיבת מעבר
הסבר
הערה
INACTIVE_SYSTEM
מנוע האימות הדו שלבי לא פעיל או לא זמין
WAIT_TO_BLOCK_DATE
תאריך אכיפת השירות לא הגיע
במצב שבו מגדירים זמן מסויים ממנו חובה לעבור אימות דו שלבי - כל עוד הזמן לא הגיע - כל הסשנים עוברים ״בהצלחה״ במנגנון - כי תאריך אכיפת השירות לא הגיע.
INIT_WHITELIST_IPS
כתובת IP ברשימה לבנה
כתובת הIP שממנה בוצעה הבקשה למעבר - קיבלה אישור כי היא נמצאת ברשימה הלבנה.
INIT_MASTER_LOGIN_WHITELIST_IPS
כתובת IP ברשימה לבנה בהתחברות מאסטר
כתובת הIP שממנה בוצעה הבקשה למעבר - קיבלה אישור כי היא נמצאת ברשימה הלבנה כאשר מתבצע התחברות עם סיסמת מאסטר של ריסיילר.
HAVE_ACTIVE_TRUST_TOKEN
בוצע מעבר על ידי אסימון ״זכור אותי״
INHERITED_FROM_ORIGINAL_SESSION
ירושה מסשן קודם כל שהוא
למשל, בעת מעבר מהאתר ניהול הרגיל לממשק חיצוני - נוצר טוקן API שסיבת המעבר שלו היא שכבר בוצע מעבר בסשן קודם.
MFA_PASSED
בוצע אימות בפועל בחיבור הנוכחי
אין להסתמך על הסיבה בלבד בנושא ״אימות קשיח״ - אלא להסתמך על isPassInThisSession
SPECIAL_VALID_TOKEN
טוקן שנוצר עם פטור מאימות מסיבה מיוחדת
ניסיון ביצוע אימות - try
הפעולה היא - try
הפעולה של מעבר אימות דו-שלבי בסשן מתבצעת פעם אחת - עד לסימון הסשן כסשן שעבר את המנגנון. כאשר סשן לא עבר אימות - ניתן לפנות לשירות זה על מנת לנסות להעביר אותו. למשל, אם הפניה תגיע מכתובת IP מאושרת, או עם אסימון ״זכור אותי״ - הסשן יעבור אימות.
דרישה מקדימה לשימוש בשירות זה: אין.
מצב שבו השירות לא זמין: לאחר מעבר שקיבל החלטת ״עבר״ (isPass: true).
פירוט מענה (מענה זהה ל isPass - רק שהנתונים יהיו לאחר ביצוע ניסיון אימות):
ניסיונות מרובים לבצע מעבר ב try שלא יצליחו - כלומר שלא יהיה מעבר בהם - יובילו לחסימת המערכת כולה לעבור אימות דו שלבי.
כל מערכת זכאית למספר מסויים של מעברים בדקה/שעה/יום וכו. מערכת שצריכה לעבור יותר מידי הרבה פעמים במנגנון - כלומר - מערכת שיוצרת יותר מידיי הרבה סשנים בפרק זמן קצר מידיי - תחסם מלעבור במנגנון ולא תוכל להשתמש בסשנים חדשים שנוצרים.
קבלת שיטות אימות זמינות - getMFAMethods
הפעולה היא - getMFAMethods
פעולה זו יכולה להחזיר נתונים שונים לפני ואחרי ביצוע אימות קשיח.
דרישה מקדימה לשימוש בשירות זה: אין.
מצב שבו השירות לא זמין: אין.
פירוט מענה:
מענה זהה ל isPass - בתוספת מערךmfaMethods עם שיטות האימות הזמינות. להלן פירוט של אובייקט מתוך המערך:
מאפיין
סוג
הסבר
דוגמא
הערה
ID
int
מזהה שיטה
1
מזהה השיטה אינו קבוע - ונבנה בצורה דינמית בעת הבקשה. צריך לפנות איתו בשביל לבצע אימות - אבל אי אפשר להתסמך לאורך זמן שהוא יהיה אותו הדבר.
STATUS
string
סטטוס שיטת האימות
ACTIVE
שיטה יכולה להיות ACTIVE = פעילה, או PENDING = ממתינה. שיטה ממתינה לאימות לא יכולה לשמש לטובת ביצוע אימות קשיח. יש לאמת אותה קודם.
MFA_METHOD_ID
int
מזהה שיטה קבוע
6598
בניגוד לשדה ID - מזהה השיטה שפה הוא קבוע, אבל זה אומר שהוא נוסף בצורה יזומה - ולא מוצע בצורה אוטמאטית, ויתכן שיהיה ריק.
NIKE
string
תיאור מקור שיטת האימות
RESET_MAIL
יכול להיות: CREATE_PHONE = המספר שיצר את המערכת. RESET_MAIL המייל לשחזור. PROFILE הגיע מהפרופיל הקבוע. MASTER_LOGIN הגיע מהתחברות מאסטר של ריסיילר. BY_CUSTOMER נוסף על ידי הלקוח.
NOTE
string
תיאור חופשי שנכתב בעת הוספת השיטה
הטלפון בבית
SEND_TYPE
סוגי שליחות אפשריות
מערך של שיטות שליחת אימות אפשריות
["CALL","SMS"]
יכול להיות: CALL = בשיחה. SMS בהודעת סמס. EMAIL בהודעה למייל. ישנם שיטות שלא יהיה אפשרי לשלוח עבורם בצורה יזומה אימות, והמערך עבורם יהיה ריק.
VALUE
string
היעד של השיטה
+972773137770
כאשר לא בוצע אימות קשיח - היעד לא יוצג במלואו ויראה למשל: shmu•••@•••.co.il כאשר מספר ה• אינם משקפות את האורך האמיתי של הערך.
EXPIRED_DATE
string
זמן תפוגת השיטה
2025-09-28 12:11:38
שיטות שפגו תוקף - לא יוצגו אחרי זה בכלל, ויש להוסיף ולאמת אותם מחדש.
LAST_USED
string
הזמן האחרון שהשיטה אומתה בהצלחה
2025-09-28 12:11:38
שיטות שלא יבצעו אימות הרבה זמן - יתכן ולא יהיה זמינות בפועל או יוסרו.
שליחת אימות לטובת אימות קשיח/מעבר - sendMFA
הפעולה היא - sendMFA
שליחת אימות יכולה להיות רלוונטית כאשר רוצים לבצע אימות קשיח בסשן שעבר את המנגנון - או במקרה שהסשן לא עבר try וחייב לבצע אימות.
דרישה מקדימה לשימוש בשירות זה: אין.
מצב שבו השירות לא זמין: לאחר ביצוע אימות קשיח (isPassInThisSession: true).
בכל פניה יש לצרף:
פרמטר
תיאור
סוג
הסבר
mfaId
מזהה שיטת האימות אליה רוצים לשלוח אימות
int
mfaSendType
סוג האימות הרצוי - מתוך SEND_TYPE
string
lang
שפת שליחת האימות.
string
HE או EN. ברירת מחדל ישלח בעברית.
autoOtpHostname
כתובת ה HOST_NAME שנמצאים בו לטובת הוספה שלו בסמס
string
מאפשר להשתמש עם OTPCredential בצד לקוח. רשות.
פירוט מענה:
כאשר responseStatus הוא OK השיחה/סמס/מייל - נשלחו.
כל שליחה חוזרת - תיצור קוד חדש - ותבטל את הקוד הקודם.
לכל סשן יש בקשת אימות ממתינה אחד בלבד.
שליחות רבות עלולות לחסום את המערכת ו/או את כתובת הIP מלשלוח לזמנים ארוכים מאד. בעת חסימה יופיע בפירוט הזמן שיש להמתין:
{
responseStatus: "Exception",
message: "exception send by customer. wait 55s",
file: "CustomerMFA.class.ym",
Line: "590:19",
yAfastVersion: "6.7.30"
}
כאשר בדוגמא מופיע wait 55s - 55 שניות.
כאמור, הזמן יכול לעלות למספרים גבוהים מאד באם מתבצעים נסיונות רבים.
ביצוע אימות בפועל לאחר שליחת אימות - validMFA
הפעולה היא - validMFA
דרישה מקדימה לשימוש בשירות זה: אין.
מצב שבו השירות לא זמין: לאחר ביצוע אימות קשיח (isPassInThisSession: true).
בכל פניה יש לצרף:
פרמטר
תיאור
סוג
הערה
mfaCode
קוד האימות שהתקבל
string
mfaRememberMe
יצירת אסימון ״זכור אותי״ בעת הצלחה
boolean
אסימון ״זכור אותי״ שנוצר ב API ייצור רק אסימון מסוג IP.
mfaRememberNote
תיאור לאסימון ״זכור אותי״ החדש.
string
פירוט מענה:
מאפיין
סוג
הסבר
דוגמא
הערה
responseStatus
string
סטטוס הפעולה
OK
mfa_valid_status
string
האם בוצע אימות.
VALID
יכול להיות UNVALIDאו VALID , או OVERTRY - שאומר שיש צורך לשלוח אימות חדש- כי עברו מספר הנסיונות האפשריים.
mfa_valid_trys
int
כמות הפעמים שבוצע ניסיון אימות קוד
1
mfa_valid_left
int
כמות הפעמים שנשארו לבצע ניסיון אימות לפני שהקוד לא רלוונטי
4
mfa_valid_message
string
הסבר מיוחד מדוע הקוד לא אומת.
validMFA not allow. over trys attempt
הוספת שיטת אימות חדשה - addMethod
הפעולה היא - addMethod
דרישה מקדימה לשימוש בשירות זה: לאחר ביצוע אימות קשיח (isPassInThisSession: true).
מצב שבו השירות לא זמין: אין
בכל פניה יש לצרף:
פרמטר
תיאור
סוג
אופציות
mfaNewType
סוג שיטה
string
מייל - EMAIL או טלפון - PHONE
mtaNewValue
הערך של השיטה החדשה
string
המייל או הטלפון.
mtaNewValidNote
תיאור של השיטה החדשה
string
למטרות נוחות בלבד. לא חובה.
newExpiredDate
זמן תפוגה של השיטה
string
תאריך תפוגה בתבנית YYYY-MM-DD HH:mm:ss.
שימו לב:
ניתן להוסיף עד 20 שיטות אימות
ניתן להוסיף מספרי טלפון של המדינות הבאות: ישראל, ארה״ב, קנדה.
פירוט מענה:
כאשר responseStatus הוא OK השיטה נוספה כממתינה לאימות, כאשר בפרמטר methodId מצויין מזהה השיטה לטובת האימות שלה/מחיקה שלה בעתיד.
אימות או שליחת אימות חוזר של שיטת אימות חדשה - reValidMethod
הפעולה היא - reValidMethod
דרישה מקדימה לשימוש בשירות זה: לאחר ביצוע אימות קשיח (isPassInThisSession: true).
מצב שבו השירות לא זמין: אין
בכל פניה יש לצרף:
פרמטר
תיאור
סוג
הסבר נוסף
mfaId
מזהה שיטת האימות
string
מתקבל כתגובה אחרי היצירה בפרמטר methodId, או בפרמטר MFA_METHOD_ID בפעולה getMFAMethods בתוך מערך mfaMethods כמו שהוסבר למעלה.
mfaSendType
סוג האימות הרצוי - מתוך SEND_TYPE
string
lang
שפת שליחת האימות.
string
HE או EN. ברירת מחדל ישלח בעברית.
autoOtpHostname
כתובת ה HOST_NAME שנמצאים בו לטובת הוספה שלו בסמס
string
מאפשר להשתמש עם OTPCredential בצד לקוח. רשות.
פירוט מענה:
כאשר responseStatus הוא OK הקוד לאימות נשלח.
ביצוע אימות של שיטה חדשה לאחר שליחת אימות - validMethod
הפעולה היא - validMethod
דרישה מקדימה לשימוש בשירות זה: לאחר ביצוע אימות קשיח (isPassInThisSession: true).
מצב שבו השירות לא זמין: אין
בכל פניה יש לצרף:
פרמטר
תיאור
סוג
הסבר נוסף
mfaId
מזהה שיטת האימות
string
מתקבל כתגובה אחרי היצירה בפרמטר methodId, או בפרמטר MFA_METHOD_ID בפעולה getMFAMethods בתוך מערך mfaMethods כמו שהוסבר למעלה.
mfaCode
קוד האימות שהתקבל
string
פירוט מענה:
זהה לתגובת בקשה אימות בפועל - validMFA.
מחיקת שיטת אימות - deleteMethod
הפעולה היא - deleteMethod
דרישה מקדימה לשימוש בשירות זה: לאחר ביצוע אימות קשיח (isPassInThisSession: true).
מצב שבו השירות לא זמין: אין
ניתן למחוק שיטות פעילות או ממתינות לאימות, אך לא ניתן למחוק שיטות שמגיעות מהפרופיל/רייסילר/מספר שפתח וכו.
בכל פניה יש לצרף:
פרמטר
תיאור
סוג
הסבר נוסף
mfaId
מזהה שיטת האימות
string
מתקבל כתגובה אחרי היצירה בפרמטר methodId, או בפרמטר MFA_METHOD_ID בפעולה getMFAMethods בתוך מערך mfaMethods כמו שהוסבר למעלה.
פירוט מענה:
כאשר responseStatus הוא OK השיטה נמחקה.
קבלת אסימוני ״זכור אותי״ פעילים - getMFATrustTokens
הפעולה היא - getMFATrustTokens
דרישה מקדימה לשימוש בשירות זה: לאחר ביצוע אימות קשיח (isPassInThisSession: true).
מצב שבו השירות לא זמין: אין
פירוט מענה:
בפרמטר trustTokens יש מערך אסימונים, להלן המבנה:
מאפיין
סוג
הסבר
דוגמא
הערה
id
int
מזהה אסימון
1
משמש לטובת מחיקתו
trust_key_type
string
סוג אסימון
YM_CALL2ALL_WEBSITE
יכול להיות או YM_CALL2ALL_WEBSITE אסימון אימות של אתר הניהול. או CUSTOMER_IP אסימון כתובת IP.
create_by
string
נוצר על ידי
192.168.1.1
create_date
string
זמן יצירה
2025-09-28 21:56:52
update_by
string
עודכן על ידי
192.168.1.1
עדכון אסימון מתבצע כאשר מסמנים ״זכור אותי״ עם אסימון שכבר שמור.
update_date
string
זמן עדכון
null
last_use
string
זמן שימוש בפועל
null
כאשר מתבצע שימוש באסימון - ומעבר של המנוע בגללו - הזמן מתעדכן.
trust_note
string
הערת האסימון מזמן היצירה
המחשב שלי
פרמטר mfaRememberNote בבקשת validMFA.
מחיקת אסימון ״זכור אותי״ - deleteTrustToken
הפעולה היא - deleteTrustToken
דרישה מקדימה לשימוש בשירות זה: לאחר ביצוע אימות קשיח (isPassInThisSession: true).
מצב שבו השירות לא זמין: אין
בכל פניה יש לצרף:
פרמטר
תיאור
סוג
הסבר נוסף
trustTokenId
מזהה האסימון
string
מתקבל בid בבקשת getMFATrustTokens.
פירוט מענה:
כאשר responseStatus הוא OK האסימון נמחקה.
קבלת כתובות IP לבנות - getMFATrustIps
הפעולה היא - getMFATrustIps
דרישה מקדימה לשימוש בשירות זה: לאחר ביצוע אימות קשיח (isPassInThisSession: true).
מצב שבו השירות לא זמין: אין
פירוט מענה:
בערך trustIps מערך כתובות IP לבנות.
שמירת כתובות IP לבנות - setMFATrustIps
הפעולה היא - setMFATrustIps
דרישה מקדימה לשימוש בשירות זה: לאחר ביצוע אימות קשיח (isPassInThisSession: true).
מצב שבו השירות לא זמין: אין
שימו לב: ניתן להוסיף עד 50 כתובות.
כתובת IP לבנה תעבור MFA עם סיבה INIT_WHITELIST_IPS כפי שהוסבר למעלה.
כתובת IP לבנה עדיין תצטרך לבצע אימות קשיח בשביל לקבל isPassInThisSession: true לטובת ביצוע פעולות רגישות.
ניתן להוסיף כתובות IPv4 או IPv6.
בכל פניה יש לצרף:
פרמטר
תיאור
סוג
הסבר נוסף
trustIps
רשימת כתובות IP
string/array
כאשר שולחים string ההפרדה תיהיה בין שורה לשורה. בשליחה מערך כל איבר זה כתובת.
פירוט מענה:
מאפיין
סוג
הסבר
דוגמא
הערה
responseStatus
string
סטטוס הפעולה
OK
okCount
int
מספר הכתובות שנוספו בהצלחה
1
save
boolean
האם בוצע שינוי בפועל
true
יהיה false אם הרשימה לא השתנתה.
valid_new_list
array
מערך הכתובות החדש
errors
array
מערך שגיאות
[ "ip: 0.192.66.2222 is not valid" ]
