Ini adalah panduan kedua dalam seri panduan add-on Classroom.
Dalam panduan ini, Anda menambahkan Login dengan Google ke aplikasi web. Ini adalah perilaku yang diperlukan untuk add-on Classroom. Gunakan kredensial dari alur otorisasi ini untuk semua panggilan mendatang ke API.
Selama panduan ini, Anda akan menyelesaikan hal berikut:
- Konfigurasikan aplikasi web Anda untuk mempertahankan data sesi dalam iframe.
- Terapkan alur login server ke server OAuth 2.0 Google.
- Lakukan panggilan ke API OAuth 2.0.
- Buat rute tambahan untuk mendukung otorisasi, logout, dan pengujian panggilan API.
Setelah selesai, Anda dapat sepenuhnya memberikan otorisasi kepada pengguna di aplikasi web dan melakukan panggilan ke Google API.
Memahami alur otorisasi
Google API menggunakan protokol OAuth 2.0 untuk autentikasi dan otorisasi. Deskripsi lengkap penerapan OAuth Google tersedia di panduan OAuth Google Identity.
Kredensial aplikasi Anda dikelola di Google Cloud. Setelah dibuat, terapkan proses empat langkah untuk mengautentikasi dan memberikan otorisasi kepada pengguna:
- Minta otorisasi. Berikan URL callback sebagai bagian dari permintaan ini. Setelah selesai, Anda akan menerima URL otorisasi.
- Arahkan pengguna ke URL otorisasi. Halaman yang dihasilkan memberi tahu pengguna tentang izin yang diperlukan aplikasi Anda, dan meminta mereka untuk memberikan akses. Setelah selesai, pengguna dirutekan ke URL callback.
- Terima kode otorisasi di rute callback Anda. Tukarkan kode otorisasi dengan token akses dan token refresh.
- Lakukan panggilan ke Google API menggunakan token.
Mendapatkan kredensial OAuth 2.0
Pastikan Anda telah membuat dan mendownload kredensial OAuth seperti yang dijelaskan di halaman Ringkasan. Project Anda harus menggunakan kredensial ini untuk membuat pengguna login.
Menerapkan alur otorisasi
Tambahkan logika dan rute ke aplikasi web untuk mewujudkan alur yang dijelaskan, termasuk fitur berikut:
- Memulai alur otorisasi setelah mencapai halaman landing.
- Minta otorisasi dan tangani respons server otorisasi.
- Hapus kredensial yang disimpan.
- Mencabut izin aplikasi.
- Menguji panggilan API.
Memulai otorisasi
Ubah halaman landing Anda untuk memulai alur otorisasi jika perlu. Add-on dapat memiliki dua kemungkinan status; ada token tersimpan di sesi saat ini, atau Anda perlu mendapatkan token dari server OAuth 2.0. Lakukan panggilan API pengujian jika ada token dalam sesi, atau minta pengguna untuk login.
Python
Buka file routes.py
Anda. Pertama, tetapkan beberapa konstanta dan konfigurasi cookie
sesuai dengan rekomendasi keamanan iframe.
# The file that contains the OAuth 2.0 client_id and client_secret.
CLIENT_SECRETS_FILE = "client_secret.json"
# The OAuth 2.0 access scopes to request.
# These scopes must match the scopes in your Google Cloud project's OAuth Consent
# Screen: https://console.cloud.google.com/apis/credentials/consent
SCOPES = [
"openid",
"https://www.googleapis.com/auth/userinfo.profile",
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/classroom.addons.teacher",
"https://www.googleapis.com/auth/classroom.addons.student"
]
# Flask cookie configurations.
app.config.update(
SESSION_COOKIE_SECURE=True,
SESSION_COOKIE_HTTPONLY=True,
SESSION_COOKIE_SAMESITE="None",
)
Berpindahlah ke rute landing add-on Anda (ini adalah /classroom-addon
dalam file
contoh). Tambahkan logika untuk merender halaman login jika sesi tidak berisi
kunci "kredensial".
@app.route("/classroom-addon")
def classroom_addon():
if "credentials" not in flask.session:
return flask.render_template("authorization.html")
return flask.render_template(
"addon-discovery.html",
message="You've reached the addon discovery page.")
Java
Kode untuk panduan ini dapat ditemukan di modul step_02_sign_in
.
Buka file application.properties
, lalu tambahkan konfigurasi sesi yang
mengikuti rekomendasi keamanan iframe.
# iFrame security recommendations call for cookies to have the HttpOnly and
# secure attribute set
server.servlet.session.cookie.http-only=true
server.servlet.session.cookie.secure=true
# Ensures that the session is maintained across the iframe and sign-in pop-up.
server.servlet.session.cookie.same-site=none
Buat class layanan (AuthService.java
dalam modul step_02_sign_in
)
untuk menangani logika di balik endpoint dalam file pengontrol dan siapkan
URI pengalihan, lokasi file secret klien, dan cakupan yang diperlukan
add-on Anda. URI pengalihan digunakan untuk mengalihkan pengguna ke URI tertentu
setelah mereka memberikan otorisasi ke aplikasi Anda. Lihat bagian Penyiapan Project dari
README.md
dalam kode sumber untuk mengetahui informasi tentang tempat meletakkan
file client_secret.json
.
@Service
public class AuthService {
private static final String REDIRECT_URI = "https://localhost:5000/callback";
private static final String CLIENT_SECRET_FILE = "client_secret.json";
private static final HttpTransport HTTP_TRANSPORT = new NetHttpTransport();
private static final JsonFactory JSON_FACTORY = GsonFactory.getDefaultInstance();
private static final String[] REQUIRED_SCOPES = {
"https://www.googleapis.com/auth/userinfo.profile",
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/classroom.addons.teacher",
"https://www.googleapis.com/auth/classroom.addons.student"
};
/** Creates and returns a Collection object with all requested scopes.
* @return Collection of scopes requested by the application.
*/
public static Collection<String> getScopes() {
return new ArrayList<>(Arrays.asList(REQUIRED_SCOPES));
}
}
Buka file pengontrol (AuthController.java
di modul step_02_sign_in
) dan tambahkan logika ke rute landing untuk merender halaman login jika sesi tidak berisi kunci credentials
.
@GetMapping(value = {"/start-auth-flow"})
public String startAuthFlow(Model model) {
try {
return "authorization";
} catch (Exception e) {
return onError(e.getMessage(), model);
}
}
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(HttpSession session, Model model) {
try {
if (session == null || session.getAttribute("credentials") == null) {
return startAuthFlow(model);
}
return "addon-discovery";
} catch (Exception e) {
return onError(e.getMessage(), model);
}
}
Halaman otorisasi Anda harus berisi link atau tombol bagi pengguna untuk "login". Mengklik opsi ini akan mengalihkan pengguna ke rute authorize
.
Minta otorisasi
Untuk meminta otorisasi, buat dan alihkan pengguna ke URL autentikasi. URL ini menyertakan beberapa informasi, seperti cakupan yang diminta, rute tujuan untuk otorisasi setelah, dan client ID aplikasi web. Anda dapat melihatnya di contoh URL otorisasi ini.
Python
Tambahkan impor berikut ke file routes.py
Anda.
import google_auth_oauthlib.flow
Buat rute baru /authorize
. Buat instance
google_auth_oauthlib.flow.Flow
; sebaiknya gunakan metode
from_client_secrets_file
yang disertakan untuk melakukannya.
@app.route("/authorize")
def authorize():
# Create flow instance to manage the OAuth 2.0 Authorization Grant Flow
# steps.
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
CLIENT_SECRETS_FILE, scopes=SCOPES)
Tetapkan redirect_uri
flow
; ini adalah rute yang Anda inginkan untuk pengguna
kembali setelah memberikan otorisasi ke aplikasi Anda. Ini adalah /callback
dalam contoh
berikut.
# The URI created here must exactly match one of the authorized redirect
# URIs for the OAuth 2.0 client, which you configured in the API Console. If
# this value doesn't match an authorized URI, you will get a
# "redirect_uri_mismatch" error.
flow.redirect_uri = flask.url_for("callback", _external=True)
Gunakan objek alur untuk membuat authorization_url
dan state
. Simpan
state
dalam sesi; ini digunakan untuk memverifikasi keaslian
respons server nanti. Terakhir, alihkan pengguna ke
authorization_url
.
authorization_url, state = flow.authorization_url(
# Enable offline access so that you can refresh an access token without
# re-prompting the user for permission. Recommended for web server apps.
access_type="offline",
# Enable incremental authorization. Recommended as a best practice.
include_granted_scopes="true")
# Store the state so the callback can verify the auth server response.
flask.session["state"] = state
# Redirect the user to the OAuth authorization URL.
return flask.redirect(authorization_url)
Java
Tambahkan metode berikut ke file AuthService.java
untuk membuat instance
objek alur, lalu gunakan untuk mengambil URL otorisasi:
- Metode
getClientSecrets()
membaca file secret klien dan membuat objekGoogleClientSecrets
. - Metode
getFlow()
membuat instanceGoogleAuthorizationCodeFlow
. - Metode
authorize()
menggunakan objekGoogleAuthorizationCodeFlow
, parameterstate
, dan URI pengalihan untuk mengambil URL otorisasi. Parameterstate
digunakan untuk memverifikasi keaslian respons dari server otorisasi. Metode ini kemudian menampilkan peta dengan URL otorisasi dan parameterstate
.
/** Reads the client secret file downloaded from Google Cloud.
* @return GoogleClientSecrets read in from client secret file. */
public GoogleClientSecrets getClientSecrets() throws Exception {
try {
InputStream in = SignInApplication.class.getClassLoader()
.getResourceAsStream(CLIENT_SECRET_FILE);
if (in == null) {
throw new FileNotFoundException("Client secret file not found: "
+ CLIENT_SECRET_FILE);
}
GoogleClientSecrets clientSecrets = GoogleClientSecrets
.load(JSON_FACTORY, new InputStreamReader(in));
return clientSecrets;
} catch (Exception e) {
throw e;
}
}
/** Builds and returns authorization code flow.
* @return GoogleAuthorizationCodeFlow object used to retrieve an access
* token and refresh token for the application.
* @throws Exception if reading client secrets or building code flow object
* is unsuccessful.
*/
public GoogleAuthorizationCodeFlow getFlow() throws Exception {
try {
GoogleAuthorizationCodeFlow authorizationCodeFlow =
new GoogleAuthorizationCodeFlow.Builder(
HTTP_TRANSPORT,
JSON_FACTORY,
getClientSecrets(),
getScopes())
.setAccessType("offline")
.build();
return authorizationCodeFlow;
} catch (Exception e) {
throw e;
}
}
/** Builds and returns a map with the authorization URL, which allows the
* user to give the app permission to their account, and the state parameter,
* which is used to prevent cross site request forgery.
* @return map with authorization URL and state parameter.
* @throws Exception if building the authorization URL is unsuccessful.
*/
public HashMap authorize() throws Exception {
HashMap<String, String> authDataMap = new HashMap<>();
try {
String state = new BigInteger(130, new SecureRandom()).toString(32);
authDataMap.put("state", state);
GoogleAuthorizationCodeFlow flow = getFlow();
String authUrl = flow
.newAuthorizationUrl()
.setState(state)
.setRedirectUri(REDIRECT_URI)
.build();
String url = authUrl;
authDataMap.put("url", url);
return authDataMap;
} catch (Exception e) {
throw e;
}
}
Gunakan injeksi konstruktor untuk membuat instance class layanan di class pengontrol.
/** Declare AuthService to be used in the Controller class constructor. */
private final AuthService authService;
/** AuthController constructor. Uses constructor injection to instantiate
* the AuthService and UserRepository classes.
* @param authService the service class that handles the implementation logic
* of requests.
*/
public AuthController(AuthService authService) {
this.authService = authService;
}
Tambahkan endpoint /authorize
ke class pengontrol. Endpoint ini memanggil
metode authorize()
AuthService untuk mengambil parameter state
dan URL otorisasi. Kemudian, endpoint menyimpan parameter state
dalam sesi dan mengalihkan pengguna ke URL otorisasi.
/** Redirects the sign-in pop-up to the authorization URL.
* @param response the current response to pass information to.
* @param session the current session.
* @throws Exception if redirection to the authorization URL is unsuccessful.
*/
@GetMapping(value = {"/authorize"})
public void authorize(HttpServletResponse response, HttpSession session)
throws Exception {
try {
HashMap authDataMap = authService.authorize();
String authUrl = authDataMap.get("url").toString();
String state = authDataMap.get("state").toString();
session.setAttribute("state", state);
response.sendRedirect(authUrl);
} catch (Exception e) {
throw e;
}
}
Menangani respons server
Setelah memberi otorisasi, pengguna kembali ke rute redirect_uri
dari langkah sebelumnya. Pada contoh sebelumnya, rute ini adalah /callback
.
Anda akan menerima code
dalam respons saat pengguna kembali dari halaman otorisasi. Kemudian, tukarkan kode dengan token akses dan token refresh:
Python
Tambahkan impor berikut ke file server Flask Anda.
import google.oauth2.credentials
import googleapiclient.discovery
Tambahkan rute ke server Anda. Buat instance lain dari
google_auth_oauthlib.flow.Flow
, tetapi kali ini gunakan kembali status yang disimpan di
langkah sebelumnya.
@app.route("/callback")
def callback():
state = flask.session["state"]
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
CLIENT_SECRETS_FILE, scopes=SCOPES, state=state)
flow.redirect_uri = flask.url_for("callback", _external=True)
Selanjutnya, minta akses dan token refresh. Untungnya, objek flow
juga
berisi metode fetch_token
untuk melakukannya. Metode ini mengharapkan argumen code
atau authorization_response
. Gunakan
authorization_response
, karena merupakan URL lengkap dari permintaan.
authorization_response = flask.request.url
flow.fetch_token(authorization_response=authorization_response)
Sekarang Anda memiliki kredensial lengkap. Simpan peristiwa tersebut dalam sesi sehingga dapat diambil di metode atau rute lain, lalu dialihkan ke halaman landing add-on.
credentials = flow.credentials
flask.session["credentials"] = {
"token": credentials.token,
"refresh_token": credentials.refresh_token,
"token_uri": credentials.token_uri,
"client_id": credentials.client_id,
"client_secret": credentials.client_secret,
"scopes": credentials.scopes
}
# Close the pop-up by rendering an HTML page with a script that redirects
# the owner and closes itself. This can be done with a bit of JavaScript:
# <script>
# window.opener.location.href = "{{ url_for('classroom_addon') }}";
# window.close();
# </script>
return flask.render_template("close-me.html")
Java
Tambahkan metode ke class layanan Anda yang menampilkan objek Credentials
dengan
meneruskan kode otorisasi yang diambil dari pengalihan yang dilakukan oleh
URL otorisasi. Objek Credentials
ini akan digunakan nanti untuk mengambil
token akses dan token refresh.
/** Returns the required credentials to access Google APIs.
* @param authorizationCode the authorization code provided by the
* authorization URL that's used to obtain credentials.
* @return the credentials that were retrieved from the authorization flow.
* @throws Exception if retrieving credentials is unsuccessful.
*/
public Credential getAndSaveCredentials(String authorizationCode) throws Exception {
try {
GoogleAuthorizationCodeFlow flow = getFlow();
GoogleClientSecrets googleClientSecrets = getClientSecrets();
TokenResponse tokenResponse = flow.newTokenRequest(authorizationCode)
.setClientAuthentication(new ClientParametersAuthentication(
googleClientSecrets.getWeb().getClientId(),
googleClientSecrets.getWeb().getClientSecret()))
.setRedirectUri(REDIRECT_URI)
.execute();
Credential credential = flow.createAndStoreCredential(tokenResponse, null);
return credential;
} catch (Exception e) {
throw e;
}
}
Tambahkan endpoint untuk URI pengalihan Anda ke pengontrol. Ambil kode otorisasi dan parameter state
dari permintaan. Bandingkan parameter
state
ini dengan atribut state
yang disimpan dalam sesi. Jika cocok, lanjutkan dengan alur otorisasi. Jika tidak cocok,
tampilkan error.
Kemudian, panggil metode AuthService
getAndSaveCredentials
dan teruskan
kode otorisasi sebagai parameter. Setelah mengambil objek Credentials
, simpan dalam sesi. Kemudian, tutup dialog dan alihkan
pengguna ke halaman landing add-on.
/** Handles the redirect URL to grant the application access to the user's
* account.
* @param request the current request used to obtain the authorization code
* and state parameter from.
* @param session the current session.
* @param response the current response to pass information to.
* @param model the Model interface to pass error information that's
* displayed on the error page.
* @return the close-pop-up template if authorization is successful, or the
* onError method to handle and display the error message.
*/
@GetMapping(value = {"/callback"})
public String callback(HttpServletRequest request, HttpSession session,
HttpServletResponse response, Model model) {
try {
String authCode = request.getParameter("code");
String requestState = request.getParameter("state");
String sessionState = session.getAttribute("state").toString();
if (!requestState.equals(sessionState)) {
response.setStatus(401);
return onError("Invalid state parameter.", model);
}
Credential credentials = authService.getAndSaveCredentials(authCode);
session.setAttribute("credentials", credentials);
return "close-pop-up";
} catch (Exception e) {
return onError(e.getMessage(), model);
}
}
Menguji panggilan API
Setelah alur selesai, Anda kini dapat melakukan panggilan ke Google API.
Sebagai contoh, minta informasi profil pengguna. Anda dapat meminta informasi pengguna dari OAuth 2.0 API.
Python
Baca dokumentasi untuk API penemuan OAuth 2.0 Gunakan untuk mendapatkan objek UserInfo yang terisi.
# Retrieve the credentials from the session data and construct a
# Credentials instance.
credentials = google.oauth2.credentials.Credentials(
**flask.session["credentials"])
# Construct the OAuth 2.0 v2 discovery API library.
user_info_service = googleapiclient.discovery.build(
serviceName="oauth2", version="v2", credentials=credentials)
# Request and store the username in the session.
# This allows it to be used in other methods or in an HTML template.
flask.session["username"] = (
user_info_service.userinfo().get().execute().get("name"))
Java
Buat metode di class layanan yang membuat objek UserInfo
menggunakan
Credentials
sebagai parameter.
/** Obtains the Userinfo object by passing in the required credentials.
* @param credentials retrieved from the authorization flow.
* @return the Userinfo object for the currently signed-in user.
* @throws IOException if creating UserInfo service or obtaining the
* Userinfo object is unsuccessful.
*/
public Userinfo getUserInfo(Credential credentials) throws IOException {
try {
Oauth2 userInfoService = new Oauth2.Builder(
new NetHttpTransport(),
new GsonFactory(),
credentials).build();
Userinfo userinfo = userInfoService.userinfo().get().execute();
return userinfo;
} catch (Exception e) {
throw e;
}
}
Tambahkan endpoint /test
ke pengontrol yang menampilkan email pengguna.
/** Returns the test request page with the user's email.
* @param session the current session.
* @param model the Model interface to pass error information that's
* displayed on the error page.
* @return the test page that displays the current user's email or the
* onError method to handle and display the error message.
*/
@GetMapping(value = {"/test"})
public String test(HttpSession session, Model model) {
try {
Credential credentials = (Credential) session.getAttribute("credentials");
Userinfo userInfo = authService.getUserInfo(credentials);
String userInfoEmail = userInfo.getEmail();
if (userInfoEmail != null) {
model.addAttribute("userEmail", userInfoEmail);
} else {
return onError("Could not get user email.", model);
}
return "test";
} catch (Exception e) {
return onError(e.getMessage(), model);
}
}
Hapus kredensial
Anda dapat "menghapus" kredensial pengguna dengan menghapusnya dari sesi saat ini. Dengan begitu, Anda dapat menguji pemilihan rute di halaman landing add-on.
Sebaiknya tampilkan indikasi bahwa pengguna telah logout sebelum mengalihkannya ke halaman landing add-on. Aplikasi Anda harus melalui alur otorisasi untuk mendapatkan kredensial baru, tetapi pengguna tidak diminta untuk memberi otorisasi ulang ke aplikasi Anda.
Python
@app.route("/clear")
def clear_credentials():
if "credentials" in flask.session:
del flask.session["credentials"]
del flask.session["username"]
return flask.render_template("signed-out.html")
Atau, gunakan flask.session.clear()
, tetapi hal ini dapat memiliki efek yang tidak diinginkan jika Anda memiliki nilai lain yang disimpan dalam sesi.
Java
Di pengontrol, tambahkan endpoint /clear
.
/** Clears the credentials in the session and returns the sign-out
* confirmation page.
* @param session the current session.
* @return the sign-out confirmation page.
*/
@GetMapping(value = {"/clear"})
public String clear(HttpSession session) {
try {
if (session != null && session.getAttribute("credentials") != null) {
session.removeAttribute("credentials");
}
return "sign-out";
} catch (Exception e) {
return onError(e.getMessage(), model);
}
}
Mencabut izin aplikasi
Pengguna dapat mencabut izin aplikasi Anda dengan mengirim permintaan POST
ke
https://oauth2.googleapis.com/revoke
. Permintaan harus berisi token akses pengguna.
Python
import requests
@app.route("/revoke")
def revoke():
if "credentials" not in flask.session:
return flask.render_template("addon-discovery.html",
message="You need to authorize before " +
"attempting to revoke credentials.")
credentials = google.oauth2.credentials.Credentials(
**flask.session["credentials"])
revoke = requests.post(
"https://oauth2.googleapis.com/revoke",
params={"token": credentials.token},
headers={"content-type": "application/x-www-form-urlencoded"})
if "credentials" in flask.session:
del flask.session["credentials"]
del flask.session["username"]
status_code = getattr(revoke, "status_code")
if status_code == 200:
return flask.render_template("authorization.html")
else:
return flask.render_template(
"index.html", message="An error occurred during revocation!")
Java
Tambahkan metode ke class layanan yang melakukan panggilan ke endpoint pencabutan.
/** Revokes the app's permissions to the user's account.
* @param credentials retrieved from the authorization flow.
* @return response entity returned from the HTTP call to obtain response
* information.
* @throws RestClientException if the POST request to the revoke endpoint is
* unsuccessful.
*/
public ResponseEntity<String> revokeCredentials(Credential credentials) throws RestClientException {
try {
String accessToken = credentials.getAccessToken();
String url = "https://oauth2.googleapis.com/revoke?token=" + accessToken;
HttpHeaders httpHeaders = new HttpHeaders();
httpHeaders.setContentType(MediaType.APPLICATION_FORM_URLENCODED_VALUE);
HttpEntity<Object> httpEntity = new HttpEntity<Object>(httpHeaders);
ResponseEntity<String> responseEntity = new RestTemplate().exchange(
url,
HttpMethod.POST,
httpEntity,
String.class);
return responseEntity;
} catch (RestClientException e) {
throw e;
}
}
Tambahkan endpoint, /revoke
, ke pengontrol yang menghapus sesi dan
mengarahkan pengguna ke halaman otorisasi jika pencabutan berhasil.
/** Revokes the app's permissions and returns the authorization page.
* @param session the current session.
* @return the authorization page.
* @throws Exception if revoking access is unsuccessful.
*/
@GetMapping(value = {"/revoke"})
public String revoke(HttpSession session) throws Exception {
try {
if (session != null && session.getAttribute("credentials") != null) {
Credential credentials = (Credential) session.getAttribute("credentials");
ResponseEntity responseEntity = authService.revokeCredentials(credentials);
Integer httpStatusCode = responseEntity.getStatusCodeValue();
if (httpStatusCode != 200) {
return onError("There was an issue revoking access: " +
responseEntity.getStatusCode(), model);
}
session.removeAttribute("credentials");
}
return startAuthFlow(model);
} catch (Exception e) {
return onError(e.getMessage(), model);
}
}
Menguji add-on
Login ke Google Classroom sebagai salah satu pengguna pengujian Pengajar Anda. Pilih tab Tugas Kelas dan buat Tugas baru. Klik tombol Add-ons di bawah area teks, lalu pilih add-on Anda. iframe akan terbuka dan add-on memuat URI Penyiapan Lampiran yang Anda tentukan di halaman Konfigurasi Aplikasi GWM SDK.
Selamat! Anda siap melanjutkan ke langkah berikutnya: menangani kunjungan berulang ke add-on Anda.