📘 תיעוד 26

אימות

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

#כניסה דרך הדפדפן (ברירת מחדל)

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

grok

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

#אחסון פרטי הזדהות

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

• העדיפו הצפנת דיסק מלאה (FileVault, BitLocker, LUKS, או מקבילה).
• אל תעתיקו את auth.json או את mcp_credentials.json לתיקיות משותפות, כרטיסים, או צ'אט.
• במארחים מרובי משתמשים, שמרו את $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

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

#OIDC (SSO של לקוח)

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

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

• סוג הרשאה: Authorization Code with PKCE (Proof Key for Code Exchange)
• כתובת הפניה: http://127.0.0.1/callback, כתובת loopback. גרוק נקשר לפורט אקראי בזמן הכניסה, ורוב ספקי ה-IdP מתייחסים להפניית loopback כלא תלויה בפורט לפי RFC 8252.
• אין סוד לקוח. 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 השמור.

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

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

כשכניסה מבוססת דפדפן אינה אפשרית, למשל במכונות וירטואליות בארגז חול, רצי CI, או רשתות מבודדות, האצילו את האימות לקובץ בינארי חיצוני או לסקריפט.

#איך זה עובד

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

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

#החוזה של stdout / stderr

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

#פורמט אסימון ב-stdout

מחרוזת חשופה, רק האסימון הגולמי:

eyJhbGciOiJSUzI1NiIs...

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

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

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

שדות 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_AUTH_EXPIRED הוא האופן שבו הוא מבדיל ביניהם. כל הרצה מחליפה במלואה את פרטי ההזדהות השמורים, ולכן פלטו את אותם שדות JSON (כגון issuer) בכל קריאה, כולל רענונים.

• GROK_AUTH_EXPIRED=1, רענון ללא ממשק. גרוק מנפיק מחדש מעל פרטי הזדהות שהוא כבר מחזיק: סבב קרוב לתפוגה, או אסימון שהשרת דחה. אף אחד לא צופה. stdin סגור, stderr שלכם נבלע, ולקובץ הבינארי ניתנות כמה שניות לפני שהוא נהרג. הנפיקו בשקט או צאו עם קוד שאינו אפס, ולעולם אל תחסמו.
• לא מוגדר, כניסה. grok login, מסך הכניסה, הרצת grok -p שמתחילה בלי הפעלה שמישה ובלי XAI_API_KEY שמותר להשתמש בו, או ההסלמה שגרוק מבצע כשהרצה ללא ממשק לא הצליחה להנפיק. ייתכן שמשתמש ממתין. stderr שלכם מגיע אליו. יש לכם 300 שניות, מספיק לסיבוב דפדפן או לקוד מכשיר. אם כניסת grok -p נכשלת, גרוק מדפיס אזהרה ועוצר עם "Not signed in".

#!/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}"

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

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

#משתני סביבה

#תהליך קוד מכשיר

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

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

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

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

#רענון אוטומטי של פרטי הזדהות

גרוק מרענן אוטומטית פרטי הזדהות שפגו:

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

#טעינה מחדש חמה

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

#סדר עדיפות באימות

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

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

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

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 של הדף הזה)

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

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

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

שיתוף נתוני קוד, נתוני קוד, שמירה, ואימון בהגדרות, ש-/privacy פותח, לא משנה את בוררי ההגדרה האלה:

חשבון אישי יכול להצטרף לשיתוף נתוני קוד או לצאת ממנו. כניסת צוות יכולה להוציא את הצוות מההגדרות. רק מנהל צוות יכול להוציא את הצוות. ניסיון של מי שאינו מנהל נדחה ונועל את השורה. יציאה חלה על כל חבר בצוות, וצוות לא יכול להצטרף בחזרה. בכניסות ארגון ומפתח API, ובכניסת משתמש בצוות משותף, השורה נעולה כי הכניסה משתמשת בהגדרת הצוות שלה. היכנסו עם החשבון האישי כדי לשנות את ההגדרה שלכם. מנהלי צוות יכולים להפעיל או לכבות Zero Data Retention (ZDR) לצוות שלהם. ראו איך להפעיל ZDR. כש-ZDR פועל, אי אפשר לשנות שיתוף נתוני קוד בכלל. שורת ההגדרות מציגה ZDR במקום הערך. ZDR לא מכבה OTEL חיצוני או user.email. ראו ZDR והזרם הזה.

ראו ניטור שימוש והגדרות.

#פתרון בעיות

#יומן ניפוי

הגדירו את 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 מאפשר כתובות הפניה של loopback (http://127.0.0.1/callback).
• ספק אימות חיצוני לא נמצא: בדקו שנתיב auth_provider_command נכון ושהקובץ הבינארי ניתן להרצה.