קבלת אסימוני הרשאה

ערכת ה-SDK לצרכנים מספקת הרשאה באמצעות אסימוני JWT (‏JSON Web Tokens). אסימון JWT‏ (JSON Web Token) הוא אסימון הרשאה שמספק טענה אחת או יותר לגבי שירות.

ה-SDK לצרכן משתמש בטוקן רשת מבוסס JSON שסופק על ידי האפליקציה כדי לתקשר עם Fleet Engine. פרטים על האסימונים שנדרשים על ידי שרת Fleet Engine מופיעים במאמרים JSON Web Tokens וIssue JSON Web tokens.

אסימון ההרשאה מספק גישה לשירותים הבאים של Fleet Engine:

  • TripService – מאפשר גישה לפרטי הנסיעה, כולל מיקום הרכב, המסלול והזמן המשוער להגעה. אסימוני הרשאה לשירות הנסיעות צריכים לכלול הצהרה tripid:TRIP_ID בכותרת authorization של האסימון, כאשר TRIP_ID הוא מזהה הנסיעה של הנסיעה לפי דרישה שמשותפת.

  • VehicleService – מאפשרת ל-Consumer SDK לקבל מידע על המיקום המשוער של הרכב כדי להציג את שכבת צפיפות התנועה של כלי הרכב ולהעריך את זמני ההגעה המשוערים לנקודת האיסוף. מכיוון ש-Consumer SDK משתמש רק במיקומים משוערים, טוקנים של הרשאה לשירות הרכב לא דורשים טענת vehicleid.

מה זה טוקן?

ב-Fleet Engine נדרש שימוש באסימוני JWT ‏ (JSON Web Tokens) לקריאות ל-method של API מסביבות עם רמת אבטחה נמוכה: סמארטפונים ודפדפנים.

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

פרטים חשובים

למידע נוסף על אסימוני JWT, אפשר לעיין במאמר אסימוני JWT במאמרים בנושא Fleet Engine.

איך לקוחות מקבלים אסימונים?

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

המפתח צריך להטמיע את הלקוח כך שיהיה אפשר לבצע את הפעולות הבאות:

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

המחלקות AuthTokenFactory יוצרות טוקנים של הרשאה בזמן עדכון המיקום. ערכת ה-SDK צריכה לארוז את האסימונים עם פרטי העדכון כדי לשלוח אותם ל-Fleet Engine. לפני שמפעילים את ה-SDK, צריך לוודא שההטמעה בצד השרת יכולה להנפיק טוקנים.

פרטים על האסימונים ששירות Fleet Engine מצפה להם מופיעים במאמר יצירת אסימוני אינטרנט מסוג JSON עבור Fleet Engine.

דוגמה ל-fetcher של טוקן הרשאה

בדוגמת הקוד הבאה אפשר לראות איך מטמיעים קריאה חוזרת (callback) של אסימון הרשאה.

Java

class JsonAuthTokenFactory implements AuthTokenFactory {

  private static final String TOKEN_URL =
      "https://yourauthserver.example/token";

  private static class CachedToken {
    String tokenValue;
    long expiryTimeMs;
    String tripId;
  }

  private CachedToken token;

  /*

*   This method is called on a background thread. Blocking is OK. However, be
*   aware that no information can be obtained from Fleet Engine until this
*   method returns.
*/
@Override
public String getToken(AuthTokenContext context) {
  // If there is no existing token or token has expired, go get a new one.
  String tripId = context.getTripId();
  if (tripId == null) {
    throw new RuntimeException("Trip ID is missing from AuthTokenContext");
  }
  if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
      !tripId.equals(token.tripId)) {
    token = fetchNewToken(tripId);
  }
  return token.tokenValue;
}

  private static CachedToken fetchNewToken(String tripId) {
    String url = TOKEN_URL + "/" + tripId;
    CachedToken token = new CachedToken();

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();

      token.tokenValue = obj.get("ServiceToken").getAsString();
      token.expiryTimeMs = obj.get("TokenExpiryMs").getAsLong();

      /*

    *   The expiry time could be an hour from now, but just to try and avoid
    *   passing expired tokens, we subtract 5 minutes from that time.
    */
    token.expiryTimeMs -= 5 * 60 * 1000;
  } catch (IOException e) {
    /*
    *   It's OK to throw exceptions here. The error listeners will receive the
    *   error thrown here.
    */
    throw new RuntimeException("Could not get auth token", e);
  }
  token.tripId = tripId;

    return token;
  }
}

Kotlin

class JsonAuthTokenFactory : AuthTokenFactory() {

  private var token: CachedToken? = null

  /*

*   This method is called on a background thread. Blocking is OK. However, be
*   aware that no information can be obtained from Fleet Engine until this
*   method returns.
*/
override fun getToken(context: AuthTokenContext): String {
  // If there is no existing token or token has expired, go get a new one.
  val tripId =
    context.getTripId() ?:
      throw RuntimeException("Trip ID is missing from AuthTokenContext")

    if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
        tripId != token.tripId) {
      token = fetchNewToken(tripId)
    }

    return token.tokenValue
  }

  class CachedToken(
    var tokenValue: String? = "",
    var expiryTimeMs: Long = 0,
    var tripId: String? = "",
  )

  private companion object {
    const val TOKEN_URL = "https://yourauthserver.example/token"

    fun fetchNewToken(tripId: String) {
      val url = "$TOKEN_URL/$tripId"
      val token = CachedToken()

      try {
        val reader = InputStreamReader(URL(url).openStream())

        reader.use {
          val obj = com.google.gson.JsonParser.parseReader(r).getAsJsonObject()

          token.tokenValue = obj.get("ServiceToken").getAsString()
          token.expiryTimeMs = obj.get("TokenExpiryMs").getAsLong()

          /*

        *   The expiry time could be an hour from now, but just to try and avoid
        *   passing expired tokens, we subtract 5 minutes from that time.
        */
        token.expiryTimeMs -= 5 * 60 * 1000
      }
    } catch (e: IOException) {
      /*
            *   It's OK to throw exceptions here. The error listeners will receive the
            *   error thrown here.
      */
      throw RuntimeException("Could not get auth token", e)
    }

      token.tripId = tripId

      return token
    }
  }
}

המאמרים הבאים

אתחול ה-Consumer SDK