📘 תיעוד 26

אימות

Grok תומך במספר שיטות אימות, כולל התחברות אינטראקטיבית בדפדפן, כניסה יחידה ארגונית (SSO), ומריצי CI/CD ללא ממשק (headless).

#התחברות בדפדפן (ברירת מחדל)

בהפעלה הראשונה, Grok פותח את הדפדפן שלכם כדי לבצע אימות מול grok.com:

grok

Grok שומר אישורים ב-~/.grok/auth.json ועושה בהם שימוש חוזר בין הפעלות. Grok מרענן טוקנים של גישה באופן אוטומטי ברקע. כאשר לא ניתן לרענן טוקן, Grok מבקש מכם להתחבר שוב. אישורים ללא תפוגה שסופקה על ידי השרת מקבלים כברירת מחדל משך חיים של 30 יום.

#אחסון אישורים

טוקנים ב-~/.grok/auth.json (וטוקני MCP OAuth ב-~/.grok/mcp_credentials.json) נכתבים עם הרשאות בעלים בלבד (0600 ב-Unix). כל מי שיש לו גישה למערכת הקבצים בנתיבים אלה יכול להשתמש באישורים, לכן:

• העדיפו הצפנת דיסק מלאה (FileVault, BitLocker, LUKS, או שווה ערך).
• אל תעתיקו את auth.json או mcp_credentials.json לספריות משותפות, לכרטיסיות תמיכה (tickets), או לצ'אט.
• במחשבים מרובי משתמשים, שמרו על $HOME / $GROK_HOME פרטיים לחשבון שלכם.

#אימות מחדש

כדי להחליף חשבונות או לפתור בעיית אימות, הריצו:

grok login

הרצת grok login מתחילה מחדש את תהליך ההתחברות, ומחליפה את ההפעלה השמורה במטמון. כברירת מחדל, הפקודה פותחת את הדפדפן שלכם ומתחברת דרך SpaceXAI OAuth ב-auth.x.ai. העבירו דגל כדי לבחור תהליך אחר:

כדי להתנתק, הריצו grok logout. הפקודה אינה מקבלת דגלים ומנקה את האישורים השמורים במטמון.

#מפתח API

עבור CI/CD, אוטומציה, או סביבות ללא גישה לדפדפן, השתמשו במפתח API מ-console.x.ai:

export XAI_API_KEY="xai-..."
grok

Grok משתמש במפתח ה-API כברירת מחדל משנית כאשר אין טוקן הפעלה פעיל. אם כבר התחברתם באופן אינטראקטיבי, טוקן ההפעלה השמור מקבל עדיפות. כדי לחזור לשימוש במפתח ה-API, הריצו grok logout או מחקו את ~/.grok/auth.json.

#OIDC (SSO של לקוח)

אמתו מפתחים באמצעות ספק הזהויות (IdP) שלכם, כגון Okta, Azure AD או Auth0, במקום grok.com.

#1. רישום לקוח ציבורי ב-IdP שלכם

• סוג הרשאה (Grant type): Authorization Code עם PKCE (Proof Key for Code Exchange)
• כתובת URI להפניה מחדש (Redirect URI): http://127.0.0.1/callback, כתובת loopback. Grok מאזין ליציאה אקראית בזמן ההתחברות, ורוב ספקי ה-IdP מתייחסים להפניה מחדש של loopback ככזו שאינה תלויה ביציאה בהתאם ל-RFC 8252.
• ללא סוד לקוח (client secret). PKCE מחליף אותו.

#2. הגדרת ה-CLI

באמצעות קובץ הגדרה:

# ~/.grok/config.toml
[grok_com_config.oidc]
issuer = "https://acme.okta.com"
client_id = "0oa1b2c3d4e5f6g7h8i9"

או באמצעות משתני סביבה:

export GROK_OIDC_ISSUER="https://acme.okta.com"
export GROK_OIDC_CLIENT_ID="0oa1b2c3d4e5f6g7h8i9"

ניתן גם לעקוף את נקודת הקצה של ה-API כדי להפנות לשרת פרוקסי משלכם:

export GROK_CLI_CHAT_PROXY_BASE_URL="https://grok-proxy.acme.com/v1"

#3. הרצת grok

ה-CLI מגלה נקודות קצה דרך {issuer}/.well-known/openid-configuration, פותח את דף ההתחברות של ה-IdP, ושומר טוקנים ב-~/.grok/auth.json. טוקנים מתרעננים אוטומטית ובשקט באמצעות ה-refresh_token השמור.

#שדות אופציונליים

#ספק אימות חיצוני

כאשר התחברות מבוססת דפדפן אינה אפשרית, למשל במכונות וירטואליות בסביבת ארגז חול (sandbox VMs), במריצי CI או ברשתות מבודדות (air-gapped), העבירו את האימות לקובץ בינרי או לסקריפט חיצוני.

#איך זה עובד

+--------------+     sh -c     +------------------------+
|     Grok     |-------------->|  your auth binary      |
|              |               |                        |
|  reads       |<-- stdout ----|  prints token          |
|  auth.json   |               |                        |
|              |   (stderr)    |  prints status/URLs    |--> surfaced to user
+--------------+               +------------------------+

1. Grok מריץ את הפקודה שלכם דרך sh -c "<command>"
2. הקובץ הבינרי שלכם מריץ כל תהליך אימות שנדרש לו (SSO, קוד מכשיר, החלפת תעודות)
3. stderr מעביר פלט קריא לבני אדם, כגון כתובות URL להתחברות והודעות סטטוס. Grok קורא את stderr ומציג אותו למשתמש: ב-TUI, הוא הופך את כתובת ה-https:// הראשונה לקישור התחברות שניתן ללחוץ עליו.
4. stdout נלכד על ידי Grok ונשמר כטוקן הגישה
5. יציאה עם קוד 0 = הצלחה; יציאה עם קוד שאינו אפס = Grok חוזר להתחברות אינטראקטיבית

#החוזה של stdout / stderr

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

#פורמט הטוקן ב-stdout

מחרוזת בלבד (Bare string): רק הטוקן הגולמי:

eyJhbGciOiJSUzI1NiIs...

JSON: עם טוקן רענון, תפוגה ומנפיק אופציונליים:

{"access_token": "eyJhbGciOi...", "refresh_token": "ref-tok", "expires_in": 3600, "issuer": "https://idp.example.com"}

השתמשו ב-JSON אם הטוקנים שלכם פגים ואתם רוצים ש-Grok יריץ מחדש את הקובץ הבינרי באופן אוטומטי לפני התפוגה.

שדות JSON:

#הגדרה

באמצעות קובץ הגדרה:

# ~/.grok/config.toml
[auth]
auth_provider_command = "/usr/local/bin/my-auth-provider"
auth_provider_label = "Acme Corp"   
# optional -- customizes the TUI login button
auth_token_ttl = 3600               
# optional -- token lifetime in seconds

או באמצעות משתני סביבה:

export GROK_AUTH_PROVIDER_COMMAND="/usr/local/bin/my-auth-provider"
export GROK_AUTH_PROVIDER_LABEL="Acme Corp"
export GROK_AUTH_TOKEN_TTL=3600

#רענון טוקן

Grok מריץ את הקובץ הבינרי שלכם תחת שני חוזים שונים, ו-GROK_AUTH_EXPIRED הוא האופן שבו הוא מבדיל ביניהם. כל ריצה מחליפה לחלוטין את האישורים השמורים, לכן פלטו את אותם שדות JSON (כגון issuer) בכל הפעלה, כולל רענונים.

• GROK_AUTH_EXPIRED=1: רענון ללא ממשק (headless). Grok מנפיק מחדש עבור אישור שכבר קיים אצלו: החלפה לקראת תפוגה, או טוקן שהשרת דחה. אף אחד לא צופה. ערוץ stdin סגור, ה-stderr שלכם נבלע, והקובץ הבינרי מקבל מספר שניות לפני שהוא מושבת. הנפיקו בשקט או צאו עם קוד שאינו אפס, לעולם אל תחסמו.
• לא מוגדר: התחברות. grok login, מסך ההתחברות, או ההסלמה ש-Grok מבצע כאשר ריצה ללא ממשק לא הצליחה להנפיק טוקן. משתמש ממתין, ה-stderr שלכם מגיע אליו, ויש לכם 300 שניות, מספיק לסבב בדפדפן או לקוד מכשיר.

#!/bin/sh
if [ "$GROK_AUTH_EXPIRED" = "1" ]; then
    
# Headless: silent refresh only. Declining is the fast, correct answer
    
# when your SSO session has lapsed and only the user can renew it.
    echo "Refreshing token..." >&2
    TOKEN=$(my-company-auth --refresh --silent) || exit 1
else
    echo "Authenticating via Acme Corp SSO..." >&2
    TOKEN=$(my-company-auth --login --interactive)
fi

if [ -z "$TOKEN" ]; then
    echo "Authentication failed" >&2
    exit 1
fi

echo "{\"access_token\": \"$TOKEN\", \"expires_in\": 3600}"

כאשר הריצה ללא ממשק אינה יכולה להפיק טוקן, Grok מפסיק להתייחס לאישור השמור כפעיל ומתחיל במקום זאת את תהליך ההתחברות: אותו תהליך שמתקבל במכונה שמעולם לא התחברו בה, כאשר ה-stderr של הקובץ הבינרי שלכם מוצג, כך שכתובת URL של קוד מכשיר או הנחיית דפדפן מגיעות אליכם. יציאה מיידית כאשר GROK_AUTH_EXPIRED=1 היא מה שהופך את המסירה הזו למהירה; קובץ בינרי שחוסם במקום זאת גורם לכם להמתין את כל משך הזמן הקצוב לרענון בכל הפעלה. באמצע הפעלה, התור נכשל עם בקשה לאימות מחדש ו-/login מריץ מחדש את הקובץ הבינרי באופן אינטראקטיבי.

מקרה אחד נשאר מעורפל, ורק במצב מוביל (leader mode, באמצעות הדגל --leader או [cli] use_leader = true; כבוי כברירת מחדל): ללא אישור כלל, המוביל מבצע ניסיון נוסף אחד ברקע מיד לאחר ההפעלה, ובריצה זו המשתנה אינו מוגדר, בדומה להתחברות. קובץ בינרי שמנפיק ללא עזרה (חשבון שירות, keytab, טוקן מעוגן) מצליח שם וההפעלה מתקנת את עצמה. קובץ שחייב להציג הנחיה למשתמש פשוט ממתין, עד לתקרת ההתחברות של 300 שניות: שום דבר לא ממתין לו, מסך ההתחברות כבר מוצג, וה-stderr של אותה ריצה נשלח אל ~/.grok/leader.log במקום אליכם.

#משתני סביבה

#תהליך קוד מכשיר (Device Code Flow)

עבור סביבות ללא ממשק (הפעלות SSH, קונטיינרים של Docker, מכונות וירטואליות מרוחקות) שבהן אין דפדפן זמין מקומית:

grok login --device-auth    
# or: grok login --device-code

הפקודה מדפיסה כתובת URL וקוד לטרמינל. פתחו את כתובת ה-URL בכל מכשיר, הזינו את הקוד, והשלימו את האימות. Grok מבצע בדיקות תקופתיות (polls) עד שההתחברות מאושרת.

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

#רענון אישורים אוטומטי

Grok מרענן אוטומטית אישורים שפגו:

• לפני תפוגה: אם ספק האימות שלכם החזיר expires_in (פלט JSON) או שהגדרתם את auth_token_ttl, Grok מריץ מחדש את הקובץ הבינרי של האימות כ-5 דקות לפני התפוגה.
• בשגיאת אימות: אם השרת מחזיר 401 Unauthorized, Grok מרענן את האישורים ומנסה שוב את הבקשה.
• OIDC: אם refresh_token זמין, Grok מרענן בשקט דרך ה-IdP שלכם מבלי לפתוח מחדש את הדפדפן.

כוונון מרווח הרענון:

# Refresh 5 minutes before expiry (default)
export GROK_AUTH_EARLY_INVALIDATION_SECS=300

# Disable the proactive buffer: refresh at expiry or on a 401 (set to 0)
export GROK_AUTH_EARLY_INVALIDATION_SECS=0

#טעינה חמה (Hot Reload)

Grok מזהה שינויים ב-~/.grok/auth.json באופן אוטומטי. אם אתם מעדכנים אישורים באופן חיצוני (למשל, באמצעות סקריפט שכותב טוקנים חדשים), Grok משתמש באישורים החדשים בקריאת ה-API הבאה ללא צורך בהפעלה מחדש.

#קדימות אימות

Grok קובע אישורים עבור כל בקשה לפי סדר זה, מהגבוה לנמוך:

1. api_key או env_key לכל מודל: מוגדר תחת [model.<name>] ב-config.toml. קודם תמיד כאשר הוא קיים.
2. טוקן הפעלה פעיל: מתקבל דרך התחברות בדפדפן, OIDC/OAuth2 או התחברות באמצעות ספק חיצוני, ונשמר ב-~/.grok/auth.json.
3. XAI_API_KEY: ברירת מחדל משנית כאשר אין טוקן הפעלה פעיל.

כאשר יותר מתהליך התחברות אחד מוגדר, Grok מאכלס את טוקן ההפעלה מהמקור הראשון הזמין, מהגבוה לנמוך:

1. ספק אימות חיצוני (auth_provider_command)
2. OIDC ארגוני: כאשר OIDC מוגדר, דרך [grok_com_config.oidc] ב-config.toml או משתני הסביבה GROK_OIDC_ISSUER ו-GROK_OIDC_CLIENT_ID
3. התחברות דפדפן SpaceXAI OAuth2: ברירת המחדל

במהלך הפעלה, השיטה הפעילה מטפלת בכל הרענונים באמצע ההפעלה.

#אישורי Git של Grove (לא grok login שבעמוד זה)

כל מה שמופיע בעמוד זה מאמת את Grok מול ה-API של המודל. מאגרי Git מרוחקים מאחורי נקודת עיגון של Grove, מה ש-grok clone מושך ממנו, הם עולם נפרד, בבעלות ה-daemon של Grove.

הקובץ ~/.grok/auth.json לעולם אינו נקרא עבור Git. הפקודה grok login אינה יוצרת אישור Git ו-grok logout אינו מבטל אותו; ה-daemon בונה תא אישורים משלו מתוך auth_mode בהגדרות Grove. אישורים אלה מנוהלים באמצעות grove status ו-grove reload-credentials. עיינו ב-grok clone עבור סוגי הכשלים והשלבים הבאים שלהם.

#הגדרות קשורות

שיתוף נתוני קוד, Coding data, retention, and training בהגדרות, שפקודת /privacy פותחת, אינו משנה את מתגי ההגדרה האלה:

בחשבונות צוות, רק מנהל צוות יכול לשנות את שיתוף נתוני הקוד. מנהלי צוות יכולים גם להפעיל או להשבית את שמירת הנתונים לאפס (Zero Data Retention, או ZDR) עבור הצוות שלהם. עיינו ב-How to enable ZDR. כאשר ZDR מופעל, לא ניתן לשנות כלל את שיתוף נתוני הקוד: שורת ההגדרות מציגה ZDR במקום הערך. ZDR אינו מכבה OTEL חיצוני או user.email, עיינו בסעיף ZDR and this stream.

עיינו ב-Monitoring Usage וב-Configuration.

#פתרון בעיות

#רישום יומנים לניפוי שגיאות (Debug logging)

הגדירו את RUST_LOG כדי לשלוט ברמת הפירוט של יומן הקובץ ושל פלט ה-stderr ללא ממשק (לוח המעקב שעל המסך ב-TUI משתמש במסנן קבוע ומתעלם מ-RUST_LOG). ב-TUI, רישום היומן לקובץ מוגדר כברירת מחדל ל-DEBUG; במצב ללא ממשק (-p), ברירת המחדל של RUST_LOG היא off כך שרק התשובה מודפסת: הגדירו RUST_LOG=error (או רחב יותר) כדי לראות יומנים ב-stderr.

ב-TUI, הגדירו את GROK_LOG_FILE לנתיב מוחלט כדי לכתוב יומנים לקובץ זה:

GROK_LOG_FILE=/tmp/grok.log RUST_LOG=debug grok
tail -f /tmp/grok.log

הערך של GROK_LOG_FILE מטופל כנתיב קובץ מילולי. ערך יחסי כגון 1 כותב קובץ בשם 1 בספריה הנוכחית.

במצב ללא ממשק, יומנים נשלחים ל-stderr. הפנו אותם לקובץ:

RUST_LOG=debug grok -p "hello" 2> /tmp/grok.log

#הודעות יומן נפוצות

#תיקונים נפוצים

• "Authentication failed": הריצו grok logout כדי לנקות אישורים שמורים במטמון, ולאחר מכן grok login כדי להתחבר שוב.
• הטוקן פג מהר מדי: הגדירו את auth_token_ttl או החזירו expires_in בפלט ה-JSON של ספק האימות שלכם.
• הפניית OIDC נכשלת: ודאו שספק ה-IdP שלכם מאפשר כתובות URI להפניה מחדש של loopback (הכתובת http://127.0.0.1/callback).
• ספק אימות חיצוני לא נמצא: בדקו שנתיב auth_provider_command תקין ושהקובץ הבינרי ניתן להרצה.