ניהול/ביצוע אימות דו-שלבי
הפקודה היא - 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" ] |
|