OAuth 2.0 dan Library Klien Google OAuth untuk Java

Ringkasan

Tujuan: Dokumen ini menjelaskan fungsi OAuth 2.0 generik yang ditawarkan oleh Library Klien Google OAuth untuk Java. Anda dapat menggunakan fungsi ini untuk autentikasi dan otorisasi untuk layanan Internet apa pun.

Untuk mengetahui petunjuk tentang cara menggunakan GoogleCredential guna melakukan otorisasi OAuth 2.0 dengan layanan Google, lihat Menggunakan OAuth 2.0 dengan Library Klien Google API untuk Java.

Ringkasan: OAuth 2.0 adalah spesifikasi standar yang memungkinkan pengguna akhir untuk dengan aman mengizinkan aplikasi klien mengakses resource sisi server yang dilindungi. Selain itu, spesifikasi token pemilik OAuth 2.0 menjelaskan cara mengakses resource yang dilindungi tersebut menggunakan token akses yang diberikan selama proses otorisasi pengguna akhir.

Untuk mengetahui detailnya, lihat dokumentasi Javadoc untuk paket berikut:

• com.google.api.client.auth.oauth2 (dari google-oauth-client)
• com.google.api.client.extensions.servlet.auth.oauth2 (dari google-oauth-client-servlet)
• com.google.api.client.extensions.appengine.auth.oauth2 (dari google-oauth-client-appengine)

Pendaftaran klien

Sebelum menggunakan Library Klien Google OAuth untuk Java, Anda mungkin perlu mendaftarkan aplikasi ke server otorisasi untuk menerima client ID dan rahasia klien. (Untuk mengetahui informasi umum tentang proses ini, lihat spesifikasi Pendaftaran Klien.)

Penyimpanan kredensial dan kredensial

Kredensial adalah class helper OAuth 2.0 yang aman untuk thread guna mengakses resource yang dilindungi menggunakan token akses. Saat menggunakan token refresh, Credential juga akan me-refresh token akses saat token akses berakhir menggunakan token refresh. Misalnya, jika Anda sudah memiliki token akses, Anda dapat membuat permintaan dengan cara berikut:

  public static HttpResponse executeGet(
      HttpTransport transport, JsonFactory jsonFactory, String accessToken, GenericUrl url)
      throws IOException {
    Credential credential =
        new Credential(BearerToken.authorizationHeaderAccessMethod()).setAccessToken(accessToken);
    HttpRequestFactory requestFactory = transport.createRequestFactory(credential);
    return requestFactory.buildGetRequest(url).execute();
  }

Sebagian besar aplikasi harus mempertahankan token akses dan token refresh kredensial untuk menghindari pengalihan di masa mendatang ke halaman otorisasi di browser. Implementasi CredentialStore di library ini tidak digunakan lagi dan akan dihapus dalam rilis mendatang. Alternatifnya adalah menggunakan antarmuka DataStoreFactory dan DataStore dengan StoredCredential, yang disediakan oleh Library Klien HTTP Google untuk Java.

Anda bisa menggunakan salah satu implementasi berikut yang disediakan oleh library:

• JdoDataStoreFactory mempertahankan kredensial menggunakan JDO.
• AppEngineDataStoreFactory mempertahankan kredensial menggunakan API App Store Data Google App Engine.
• MemoryDataStoreFactory"persisten" kredensial dalam memori, yang hanya berguna sebagai penyimpanan jangka pendek sepanjang waktu proses.
• FileDataStoreFactory mempertahankan kredensial dalam sebuah file.

Pengguna Google App Engine:

AppEngineCredentialStore tidak digunakan lagi dan sedang dihapus.

Sebaiknya gunakan AppEngineDataStoreFactory dengan StoredCredential. Jika memiliki kredensial yang disimpan dengan cara lama, Anda dapat menggunakan metode helper yang ditambahkan migrateTo(AppEngineDataStoreFactory) atau migrateTo(DataStore) untuk bermigrasi.

Gunakan DataStoreCredentialRefreshListener dan setel untuk kredensial menggunakan GoogleCredential.Builder.addRefreshListener(CredentialRefreshListener).

Alur kode otorisasi

Gunakan alur kode otorisasi untuk memungkinkan pengguna akhir memberikan akses aplikasi Anda ke data yang dilindungi. Protokol untuk alur ini ditentukan dalam spesifikasi Pemberian Kode Otorisasi.

Alur ini diimplementasikan menggunakan AuthorizationCodeFlow. Langkah-langkahnya adalah:

• Pengguna akhir login ke aplikasi Anda. Anda harus mengaitkan pengguna tersebut dengan ID pengguna yang unik untuk aplikasi Anda.
• Panggil AuthorizationCodeFlow.loadCredential(String), berdasarkan ID pengguna, untuk memeriksa apakah kredensial pengguna sudah diketahui. Jika ya, Anda sudah selesai.
• Jika tidak, panggil AuthorizationCodeFlow.newAuthorizationUrl() dan arahkan browser pengguna akhir ke halaman otorisasi tempat mereka dapat memberikan akses aplikasi Anda ke data yang dilindungi.
• Kemudian, browser web akan mengalihkan ke URL alihan dengan parameter kueri "code" yang kemudian dapat digunakan untuk meminta token akses menggunakan AuthorizationCodeFlow.newTokenRequest(String).
• Gunakan AuthorizationCodeFlow.createAndStoreCredential(TokenResponse, String) untuk menyimpan dan mendapatkan kredensial dalam mengakses resource yang dilindungi.

Atau, jika tidak menggunakan AuthorizationCodeFlow, Anda dapat menggunakan class level yang lebih rendah:

• Gunakan DataStore.get(String) untuk memuat kredensial dari penyimpanan, berdasarkan ID pengguna.
• Gunakan AuthorizationCodeRequestUrl untuk mengarahkan browser ke halaman otorisasi.
• Gunakan AuthorizationCodeResponseUrl untuk memproses respons otorisasi dan menguraikan kode otorisasi.
• Gunakan AuthorizationCodeTokenRequest untuk meminta token akses dan mungkin token refresh.
• Buat Kredensial baru dan simpan menggunakan DataStore.set(String, V).
• Akses resource yang dilindungi menggunakan Kredensial. Token akses yang tidak berlaku akan otomatis dimuat ulang menggunakan token refresh, jika berlaku. Pastikan untuk menggunakan DataStoreCredentialRefreshListener dan tetapkan untuk kredensial menggunakan Credential.Builder.addRefreshListener(CredentialRefreshListener).

Alur kode otorisasi Servlet

Library ini menyediakan class helper servlet untuk menyederhanakan alur kode otorisasi secara signifikan bagi kasus penggunaan dasar. Anda cukup menyediakan subclass konkret AbstractAuthorizationCodeServlet dan AbstractAuthorizationCodeCallbackServlet (dari google-oauth-client-servlet) dan menambahkannya ke file web.xml. Perhatikan bahwa Anda tetap perlu menangani login pengguna untuk aplikasi web Anda dan mengekstrak ID pengguna.

Contoh kode:

public class ServletSample extends AbstractAuthorizationCodeServlet {

  @Override
  protected void doGet(HttpServletRequest request, HttpServletResponse response)
      throws IOException {
    // do stuff
  }

  @Override
  protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException {
    GenericUrl url = new GenericUrl(req.getRequestURL().toString());
    url.setRawPath("/oauth2callback");
    return url.build();
  }

  @Override
  protected AuthorizationCodeFlow initializeFlow() throws IOException {
    return new AuthorizationCodeFlow.Builder(BearerToken.authorizationHeaderAccessMethod(),
        new NetHttpTransport(),
        new JacksonFactory(),
        new GenericUrl("https://server.example.com/token"),
        new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw"),
        "s6BhdRkqt3",
        "https://server.example.com/authorize").setCredentialDataStore(
            StoredCredential.getDefaultDataStore(
                new FileDataStoreFactory(new File("datastoredir"))))
        .build();
  }

  @Override
  protected String getUserId(HttpServletRequest req) throws ServletException, IOException {
    // return user ID
  }
}

public class ServletCallbackSample extends AbstractAuthorizationCodeCallbackServlet {

  @Override
  protected void onSuccess(HttpServletRequest req, HttpServletResponse resp, Credential credential)
      throws ServletException, IOException {
    resp.sendRedirect("/");
  }

  @Override
  protected void onError(
      HttpServletRequest req, HttpServletResponse resp, AuthorizationCodeResponseUrl errorResponse)
      throws ServletException, IOException {
    // handle error
  }

  @Override
  protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException {
    GenericUrl url = new GenericUrl(req.getRequestURL().toString());
    url.setRawPath("/oauth2callback");
    return url.build();
  }

  @Override
  protected AuthorizationCodeFlow initializeFlow() throws IOException {
    return new AuthorizationCodeFlow.Builder(BearerToken.authorizationHeaderAccessMethod(),
        new NetHttpTransport(),
        new JacksonFactory(),
        new GenericUrl("https://server.example.com/token"),
        new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw"),
        "s6BhdRkqt3",
        "https://server.example.com/authorize").setCredentialDataStore(
            StoredCredential.getDefaultDataStore(
                new FileDataStoreFactory(new File("datastoredir"))))
        .build();
  }

  @Override
  protected String getUserId(HttpServletRequest req) throws ServletException, IOException {
    // return user ID
  }
}

Alur kode otorisasi Google App Engine

Alur kode otorisasi di App Engine hampir identik dengan alur kode otorisasi servlet, kecuali bahwa kita dapat memanfaatkan Users Java API Google App Engine. Pengguna harus login agar User Java API dapat diaktifkan; untuk mengetahui informasi tentang cara mengalihkan pengguna ke halaman login jika mereka belum login, lihat Keamanan dan Autentikasi (di web.xml).

Perbedaan utama dari kasus servlet adalah Anda memberikan subclass konkret AbstractAppEngineAuthorizationCodeServlet dan AbstractAppEngineAuthorizationCodeCallbackServlet (dari google-oauth-client-appengine). Class tersebut memperluas class servlet abstrak dan menerapkan metode getUserId untuk Anda menggunakan Users Java API. AppEngineDataStoreFactory (dari Google HTTP Client Library for Java adalah opsi yang baik untuk mempertahankan kredensial menggunakan Google App Engine Data Store API.

Contoh kode:

public class AppEngineSample extends AbstractAppEngineAuthorizationCodeServlet {

  @Override
  protected void doGet(HttpServletRequest request, HttpServletResponse response)
      throws IOException {
    // do stuff
  }

  @Override
  protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException {
    GenericUrl url = new GenericUrl(req.getRequestURL().toString());
    url.setRawPath("/oauth2callback");
    return url.build();
  }

  @Override
  protected AuthorizationCodeFlow initializeFlow() throws IOException {
    return new AuthorizationCodeFlow.Builder(BearerToken.authorizationHeaderAccessMethod(),
        new UrlFetchTransport(),
        new JacksonFactory(),
        new GenericUrl("https://server.example.com/token"),
        new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw"),
        "s6BhdRkqt3",
        "https://server.example.com/authorize").setCredentialStore(
            StoredCredential.getDefaultDataStore(AppEngineDataStoreFactory.getDefaultInstance()))
        .build();
  }
}

public class AppEngineCallbackSample extends AbstractAppEngineAuthorizationCodeCallbackServlet {

  @Override
  protected void onSuccess(HttpServletRequest req, HttpServletResponse resp, Credential credential)
      throws ServletException, IOException {
    resp.sendRedirect("/");
  }

  @Override
  protected void onError(
      HttpServletRequest req, HttpServletResponse resp, AuthorizationCodeResponseUrl errorResponse)
      throws ServletException, IOException {
    // handle error
  }

  @Override
  protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException {
    GenericUrl url = new GenericUrl(req.getRequestURL().toString());
    url.setRawPath("/oauth2callback");
    return url.build();
  }

  @Override
  protected AuthorizationCodeFlow initializeFlow() throws IOException {
    return new AuthorizationCodeFlow.Builder(BearerToken.authorizationHeaderAccessMethod(),
        new UrlFetchTransport(),
        new JacksonFactory(),
        new GenericUrl("https://server.example.com/token"),
        new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw"),
        "s6BhdRkqt3",
        "https://server.example.com/authorize").setCredentialStore(
            StoredCredential.getDefaultDataStore(AppEngineDataStoreFactory.getDefaultInstance()))
        .build();
  }
}

Alur kode otorisasi command line

Contoh kode yang diambil dari dailymotion-cmdline-sample:

/** Authorizes the installed application to access user's protected data. */
private static Credential authorize() throws Exception {
  OAuth2ClientCredentials.errorIfNotSpecified();
  // set up authorization code flow
  AuthorizationCodeFlow flow = new AuthorizationCodeFlow.Builder(BearerToken
      .authorizationHeaderAccessMethod(),
      HTTP_TRANSPORT,
      JSON_FACTORY,
      new GenericUrl(TOKEN_SERVER_URL),
      new ClientParametersAuthentication(
          OAuth2ClientCredentials.API_KEY, OAuth2ClientCredentials.API_SECRET),
      OAuth2ClientCredentials.API_KEY,
      AUTHORIZATION_SERVER_URL).setScopes(Arrays.asList(SCOPE))
      .setDataStoreFactory(DATA_STORE_FACTORY).build();
  // authorize
  LocalServerReceiver receiver = new LocalServerReceiver.Builder().setHost(
      OAuth2ClientCredentials.DOMAIN).setPort(OAuth2ClientCredentials.PORT).build();
  return new AuthorizationCodeInstalledApp(flow, receiver).authorize("user");
}

private static void run(HttpRequestFactory requestFactory) throws IOException {
  DailyMotionUrl url = new DailyMotionUrl("https://api.dailymotion.com/videos/favorites");
  url.setFields("id,tags,title,url");

  HttpRequest request = requestFactory.buildGetRequest(url);
  VideoFeed videoFeed = request.execute().parseAs(VideoFeed.class);
  ...
}

public static void main(String[] args) {
  ...
  DATA_STORE_FACTORY = new FileDataStoreFactory(DATA_STORE_DIR);
  final Credential credential = authorize();
  HttpRequestFactory requestFactory =
      HTTP_TRANSPORT.createRequestFactory(new HttpRequestInitializer() {
        @Override
        public void initialize(HttpRequest request) throws IOException {
          credential.initialize(request);
          request.setParser(new JsonObjectParser(JSON_FACTORY));
        }
      });
  run(requestFactory);
  ...
}

Alur klien berbasis browser

Berikut adalah langkah-langkah umum alur klien berbasis browser yang ditentukan dalam spesifikasi Hibah Implisit:

• Dengan menggunakan BrowserClientRequestUrl, alihkan browser pengguna akhir ke halaman otorisasi, tempat pengguna akhir dapat memberi aplikasi Anda akses ke data yang dilindungi.
• Gunakan aplikasi JavaScript untuk memproses token akses yang ditemukan dalam fragmen URL di URI pengalihan yang terdaftar dengan server otorisasi.

Contoh penggunaan untuk aplikasi web:

public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException {
  String url = new BrowserClientRequestUrl(
      "https://server.example.com/authorize", "s6BhdRkqt3").setState("xyz")
      .setRedirectUri("https://client.example.com/cb").build();
  response.sendRedirect(url);
}

Mendeteksi token akses yang habis masa berlakunya

Menurut spesifikasi pemilik OAuth 2.0, saat server dipanggil untuk mengakses resource yang dilindungi dengan token akses yang sudah tidak berlaku, server biasanya merespons dengan kode status 401 Unauthorized HTTP seperti berikut:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: Bearer realm="example",
                     error="invalid_token",
                     error_description="The access token expired"

Namun, tampaknya ada banyak fleksibilitas dalam spesifikasi ini. Untuk mengetahui detailnya, periksa dokumentasi penyedia OAuth 2.0.

Pendekatan alternatifnya adalah memeriksa parameter expires_in dalam respons token akses. Ini menentukan masa aktif dalam token akses yang diberikan dalam hitungan detik, yang biasanya satu jam. Namun, token akses mungkin tidak benar-benar habis masa berlakunya pada akhir periode tersebut, dan server mungkin terus mengizinkan akses. Itulah sebabnya kami biasanya merekomendasikan untuk menunggu kode status 401 Unauthorized, bukannya menganggap token sudah tidak berlaku berdasarkan waktu berlalu. Atau, Anda dapat mencoba memperbarui token akses sesaat sebelum masa berlakunya habis, dan jika server token tidak tersedia, terus gunakan token akses hingga Anda menerima 401. Ini adalah strategi yang digunakan secara default di Kredensial.

Opsi lainnya adalah mengambil token akses baru sebelum setiap permintaan, tetapi setiap kali akan diperlukan permintaan HTTP tambahan ke server token, sehingga kemungkinan akan menjadi pilihan yang buruk dalam hal kecepatan dan penggunaan jaringan. Idealnya, simpan token akses di penyimpanan yang aman dan persisten untuk meminimalkan permintaan aplikasi untuk token akses baru. (Namun, untuk aplikasi yang terinstal, penyimpanan yang aman adalah masalah yang sulit.)

Perhatikan bahwa token akses mungkin menjadi tidak valid karena alasan selain masa berlaku, misalnya jika pengguna telah secara eksplisit mencabut token. Jadi, pastikan kode penanganan error Anda kuat. Setelah mendeteksi bahwa token tidak lagi valid, misalnya jika masa berlaku token telah berakhir atau dicabut, Anda harus menghapus token akses dari penyimpanan. Di Android, misalnya, Anda harus memanggil AccountManager.invalidateAuthToken.