Handle repeat logins

Python

Navigate to the definitions of your Flask routes (routes.py if you're following our provided example). At the top of your add-on landing route (/classroom-addon in our provided example), retrieve and store the login_hint and hd query parameters:

# Retrieve the login_hint and hd query parameters.
login_hint = flask.request.args.get("login_hint")
hd = flask.request.args.get("hd")

Ensure that login_hint and hd are stored in the session. This is an appropriate place to store these values; they're ephemeral and you receive new values when the add-on is opened.

# It's possible that we might return to this route later, in which case the
# parameters will not be passed in. Instead, use the values cached in the
# session.

# If neither query parameter is available, use the values in the session.
if login_hint is None and hd is None:
    login_hint = flask.session.get("login_hint")
    hd = flask.session.get("hd")

# If there's no login_hint query parameter, then check for hd.
# Send the user to the sign in page.
elif hd is not None:
    flask.session["hd"] = hd
    return start_auth_flow()

# If the login_hint query parameter is available, we'll store it in the
# session.
else:
    flask.session["login_hint"] = login_hint

Java

Navigate to the add-on landing route in your controller class (/addon-discovery in AuthController.java in the provided example). At the beginning of this route, retrieve and store the login_hint and hd query parameters.

/** Retrieve the login_hint or hd query parameters from the request URL. */
String login_hint = request.getParameter("login_hint");
String hd = request.getParameter("hd");

Ensure that login_hint and hd are stored in the session. This is an appropriate place to store these values; they're ephemeral and you receive new values when the add-on is opened.

/** If neither query parameter is sent, use the values in the session. */
if (login_hint == null && hd == null) {
    login_hint = (String) session.getAttribute("login_hint");
    hd = (String) session.getAttribute("hd");
}

/** If the hd query parameter is provided, add hd to the session and route
*   the user to the authorization page. */
else if (hd != null) {
    session.setAttribute("hd", hd);
    return startAuthFlow(model);
}

/** If the login_hint query parameter is provided, add it to the session. */
else if (login_hint != null) {
    session.setAttribute("login_hint", login_hint);
}

Python

Navigate to the authorization route in your Flask server file (/authorize in our provided example). Add the login_hint and hd arguments to the call to flow.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",
    # The user will automatically be selected if we have the login_hint.
    login_hint=flask.session.get("login_hint"),
    # If we don't have login_hint, passing hd will reduce the list of
    # accounts in the account chooser to only those with the same domain.
    hd=flask.session.get("hd"))

Java

Navigate to the authorize() method in the AuthService.java class. Add login_hint and hd as parameters to the method, and add the login_hint and hd arguments to the authorization URL builder.

String authUrl = flow
    .newAuthorizationUrl()
    .setState(state)
    .set("login_hint", login_hint)
    .set("hd", hd)
    .setRedirectUri(REDIRECT_URI)
    .build();

Python

Define the User schema

A User contains the following attributes:

• id: The user's Google ID. This should match values provided in the login_hint query parameter.
• display_name: The user's first and last name, such as "Alex Smith".
• email: The user's email address.
• portrait_url: The URL of the user's profile picture.
• refresh_token: The previously acquired refresh token.

This example implements storage using SQLite, which is natively supported by Python. It uses the flask_sqlalchemy module to facilitate our database management.

Set up the database

First, specify a file location for our database. Navigate to your server configuration file (config.py in our provided example) and add the following.

import os

# Point to a database file in the project root.
DATABASE_FILE_NAME = os.path.join(
    os.path.abspath(os.path.dirname(__file__)), 'data.sqlite')

class Config(object):
    SQLALCHEMY_DATABASE_URI = f"sqlite:///{DATABASE_FILE_NAME}"
    SQLALCHEMY_TRACK_MODIFICATIONS = False

This points Flask to the file data.sqlite in the same directory as your main.py file.

Next, navigate to your module directory and create a new models.py file. This is webapp/models.py if you're following our provided example. Add the following to the new file to define the User table, substituting your module name for webapp if different.

from webapp import db

# Database model to represent a user.
class User(db.Model):
    # The user's identifying information:
    id = db.Column(db.String(120), primary_key=True)
    display_name = db.Column(db.String(80))
    email = db.Column(db.String(120), unique=True)
    portrait_url = db.Column(db.Text())

    # The user's refresh token, which will be used to obtain an access token.
    # Note that refresh tokens will become invalid if:
    # - The refresh token has not been used for six months.
    # - The user revokes your app's access permissions.
    # - The user changes passwords.
    # - The user belongs to a Google Cloud organization
    #   that has session control policies in effect.
    refresh_token = db.Column(db.Text())

Finally, in your module's __init__.py file, add the following to import the new models and create the database.

from webapp import models
from os import path
from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy(app)

# Initialize the database file if not created.
if not path.exists(config.DATABASE_FILE_NAME):
    db.create_all()

Java

Define the User schema

A User contains the following attributes:

• id: The user's Google ID. This should match value provided in the login_hint query parameter.
• email: The user's email address.

Create a schema.sql file in the module's resources directory. Spring reads this file and generates a schema for the database accordingly. Define the table with a table name, users, and columns to represent the User attributes, id and email.

CREATE TABLE IF NOT EXISTS users (
    id VARCHAR(255) PRIMARY KEY, -- user's unique Google ID
    email VARCHAR(255), -- user's email address
);

Create a Java class to define the User model for the database. This is User.java in the provided example.

Add the @Entity annotation to indicate that this is a POJO that can be saved to the database. Add the @Table annotation with the corresponding table name that you configured in schema.sql.

Note that the code example includes constructors and setters for the two attributes. The constructor and setters are used in AuthController.java to create or update a user in the database. You may also include getters and a toString method as you see fit, but for this particular walkthrough, these methods are not used and are omitted from the code example on this page for brevity.

/** An entity class that provides a model to store user information. */
@Entity
@Table(name = "users")
public class User {
    /** The user's unique Google ID. The @Id annotation specifies that this
     *   is the primary key. */
    @Id
    @Column
    private String id;

    /** The user's email address. */
    @Column
    private String email;

    /** Required User class no args constructor. */
    public User() {
    }

    /** The User class constructor that creates a User object with the
    *   specified parameters.
    *   @param id the user's unique Google ID
    *   @param email the user's email address
    */
    public User(String id, String email) {
        this.id = id;
        this.email = email;
    }

    public void setId(String id) { this.id = id; }

    public void setEmail(String email) { this.email = email; }
}

Create an interface called UserRepository.java to handle CRUD operations to the database. This interface extends the CrudRepository interface.

/** Provides CRUD operations for the User class by extending the
 *   CrudRepository interface. */
@Repository
public interface UserRepository extends CrudRepository<User, String> {
}

The controller class facilitates communication between the client and the repository. Therefore, update the controller class constructor to inject the UserRepository class.

/** Declare UserRepository to be used in the Controller class constructor. */
private final UserRepository userRepository;

/**
*   ...
*   @param userRepository the class that interacts with User objects stored in
*   persistent storage.
*/
public AuthController(AuthService authService, UserRepository userRepository) {
    this.authService = authService;
    this.userRepository = userRepository;
}

Set up the database

To store User-related information, use an H2 database that's intrinsically supported in Spring Boot. This database is also used in subsequent walkthroughs to store other Classroom-related information. Setting up the H2 database requires adding the following configuration to application.properties.

# Enable configuration for persistent storage using an H2 database
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.url=jdbc:h2:file:./h2/userdb
spring.datasource.username=<USERNAME>
spring.datasource.password=<PASSWORD>
spring.jpa.hibernate.ddl-auto=update
spring.jpa.open-in-view=false

The spring.datasource.url config creates a directory, called h2, with the file userdb stored inside it. Add the path to the H2 database to the .gitignore. You must update the spring.datasource.username and spring.datasource.password before you run the application to set the database with a username and password of your choice. To update the username and password for the database after running the application, delete the generated h2 directory, update the configuration, and re-run the application.

Setting the spring.jpa.hibernate.ddl-auto config to update ensures that data stored in the database is preserved when the application is restarted. To clear the database every time the application is restarted, set this config to create.

Set the spring.jpa.open-in-view config to false. This config is enabled by default and can be known to result in performance issues that are difficult to diagnose in production.

As described previously, you must be able to retrieve the credentials of a repeat user. This is facilitated by the built-in credential store support offered by the GoogleAuthorizationCodeFlow.

In the AuthService.java class, define a path to the file where the credential class is stored. In this example, the file is created in the /credentialStore directory. Add the path to the credential store to the .gitignore. This directory is generated once the user begins the authorization flow.

private static final File dataDirectory = new File("credentialStore");

Next, create a method in the AuthService.java file that creates and returns a FileDataStoreFactory object. This is the datastore that stores credentials.

/** Creates and returns FileDataStoreFactory object to store credentials.
 *   @return FileDataStoreFactory dataStore used to save and obtain users ids
 *   mapped to Credentials.
 *   @throws IOException if creating the dataStore is unsuccessful.
 */
public FileDataStoreFactory getCredentialDataStore() throws IOException {
    FileDataStoreFactory dataStore = new FileDataStoreFactory(dataDirectory);
    return dataStore;
}

Update the getFlow() method in AuthService.java to include setDataStoreFactory in the GoogleAuthorizationCodeFlow Builder() method and call getCredentialDataStore() to set the datastore.

GoogleAuthorizationCodeFlow authorizationCodeFlow =
    new GoogleAuthorizationCodeFlow.Builder(
        HTTP_TRANSPORT,
        JSON_FACTORY,
        getClientSecrets(),
        getScopes())
    .setAccessType("offline")
    .setDataStoreFactory(getCredentialDataStore())
    .build();

Next, update the getAndSaveCredentials(String authorizationCode) method. Previously, this method obtained credentials without storing them anywhere. Update the method to store the credentials in the datastore indexed by the user ID.

The user ID can be obtained from the TokenResponse object using the id_token, but it must be verified first. Otherwise, client applications may be able to impersonate users by sending modified user ids to the server. it's recommended that you use the Google API Client libraries to validate the id_token. See the [Google Identity page on verifying the Google ID token] for more information.

// Obtaining the id_token will help determine which user signed in to the application.
String idTokenString = tokenResponse.get("id_token").toString();

// Validate the id_token using the GoogleIdTokenVerifier object.
GoogleIdTokenVerifier googleIdTokenVerifier = new GoogleIdTokenVerifier.Builder(
        HTTP_TRANSPORT,
        JSON_FACTORY)
    .setAudience(Collections.singletonList(
        googleClientSecrets.getWeb().getClientId()))
    .build();

GoogleIdToken idToken = googleIdTokenVerifier.verify(idTokenString);

if (idToken == null) {
    throw new Exception("Invalid ID token.");
}

Once the id_token has been verified, obtain the userId to store along with the obtained credentials.

// Obtain the user id from the id_token.
Payload payload = idToken.getPayload();
String userId = payload.getSubject();

Update the call to flow.createAndStoreCredential to include the userId.

// Save the user id and credentials to the configured FileDataStoreFactory.
Credential credential = flow.createAndStoreCredential(tokenResponse, userId);

Add a method to the AuthService.java class that returns the credentials for a specific user if it exists in the datastore.

/** Find credentials in the datastore based on a specific user id.
*   @param userId key to find in the file datastore.
*   @return Credential object to be returned if a matching key is found in the datastore. Null if
*   the key doesn't exist.
*   @throws Exception if building flow object or checking for userId key is unsuccessful. */
public Credential loadFromCredentialDataStore(String userId) throws Exception {
    try {
        GoogleAuthorizationCodeFlow flow = getFlow();
        Credential credential = flow.loadCredential(userId);
        return credential;
    } catch (Exception e) {
        e.printStackTrace();
        throw e;
    }
}

Python

def get_credentials_from_storage(id):
    """
    Retrieves credentials from the storage and returns them as a dictionary.
    """
    return User.query.get(id)

Java

In the AuthController.java class, define a method to retrieve a user from the database based on their user ID.

/** Retrieves stored credentials based on the user id.
*   @param id the id of the current user
*   @return User the database entry corresponding to the current user or null
*   if the user doesn't exist in the database.
*/
public User getUser(String id) {
    if (id != null) {
        Optional<User> user = userRepository.findById(id);
        if (user.isPresent()) {
            return user.get();
        }
    }
    return null;
}

Python

First define a utility method that implements the storage or update behavior.

def save_user_credentials(credentials=None, user_info=None):
    """
    Updates or adds a User to the database. A new user is added only if both
    credentials and user_info are provided.

    Args:
        credentials: An optional Credentials object.
        user_info: An optional dict containing user info returned by the
            OAuth 2.0 API.
    """

    existing_user = get_credentials_from_storage(
        flask.session.get("login_hint"))

    if existing_user:
        if user_info:
            existing_user.id = user_info.get("id")
            existing_user.display_name = user_info.get("name")
            existing_user.email = user_info.get("email")
            existing_user.portrait_url = user_info.get("picture")

        if credentials and credentials.refresh_token is not None:
            existing_user.refresh_token = credentials.refresh_token

    elif credentials and user_info:
        new_user = User(id=user_info.get("id"),
                        display_name=user_info.get("name"),
                        email=user_info.get("email"),
                        portrait_url=user_info.get("picture"),
                        refresh_token=credentials.refresh_token)

        db.session.add(new_user)

    db.session.commit()

There are two instances in which you might save credentials to your database: when the user returns to your application at the end of the authorization flow and when issuing an API call. These are where we previously set the session credentials key.

Call save_user_credentials at the end of your callback route. Keep the user_info object instead of just extracting the user's name.

# The flow is complete! We'll use the credentials to fetch the user's info.
user_info_service = googleapiclient.discovery.build(
    serviceName="oauth2", version="v2", credentials=credentials)

user_info = user_info_service.userinfo().get().execute()

flask.session["username"] = user_info.get("name")

save_user_credentials(credentials, user_info)

You should also update the credentials following calls to the API. In this case you can provide the updated credentials as arguments to the save_user_credentials method.

# Save credentials in case access token was refreshed.
flask.session["credentials"] = credentials_to_dict(credentials)
save_user_credentials(credentials)

Java

First define a method that stores or updates a User object in the H2 database.

/** Adds or updates a user in the database.
*   @param credential the credentials object to save or update in the database.
*   @param userinfo the userinfo object to save or update in the database.
*   @param session the current session.
*/
public void saveUser(Credential credential, Userinfo userinfo, HttpSession session) {
    User storedUser = null;
    if (session != null && session.getAttribute("login_hint") != null) {
        storedUser = getUser(session.getAttribute("login_hint").toString());
    }

    if (storedUser != null) {
        if (userinfo != null) {
            storedUser.setId(userinfo.getId());
            storedUser.setEmail(userinfo.getEmail());
        }
        userRepository.save(storedUser);
    } else if (credential != null && userinfo != null) {
        User newUser = new User(
            userinfo.getId(),
            userinfo.getEmail(),
        );
        userRepository.save(newUser);
    }
}

There are two instances in which you might save credentials to your database: when the user returns to your application at the end of the authorization flow and when issuing an API call. These are where we previously set the session credentials key.

Call saveUser at the end of the /callback route. You should keep the user_info object instead of just extracting the user's email.

/** This is the end of the auth flow. We should save user info to the database. */
Userinfo userinfo = authService.getUserInfo(credentials);
saveUser(credentials, userinfo, session);

You should also update the credentials following calls to the API. In this case, you can provide the updated credentials as arguments to the saveUser method.

/** Save credentials in case access token was refreshed. */
saveUser(credentials, null, session);

Python

Ensure that the database file has been created when the application launches. Insert the following into a module initializer (such as webapp/__init__.py in our provided example) or in the main method that launches the server.

# Initialize the database file if not created.
if not os.path.exists(DATABASE_FILE_NAME):
    db.create_all()

Your method should then handle the login_hint and hd query parameters as discussed above. Then load the store credentials if this is a repeat visitor. You know it's a repeat visitor if you received login_hint. Retrieve any stored credentials for this user and load them into the session.

stored_credentials = get_credentials_from_storage(login_hint)

# If we have stored credentials, store them in the session.
if stored_credentials:
    # Load the client secrets file contents.
    client_secrets_dict = json.load(
        open(CLIENT_SECRETS_FILE)).get("web")

    # Update the credentials in the session.
    if not flask.session.get("credentials"):
        flask.session["credentials"] = {}

    flask.session["credentials"] = {
        "token": stored_credentials.access_token,
        "refresh_token": stored_credentials.refresh_token,
        "token_uri": client_secrets_dict["token_uri"],
        "client_id": client_secrets_dict["client_id"],
        "client_secret": client_secrets_dict["client_secret"],
        "scopes": SCOPES
    }

    # Set the username in the session.
    flask.session["username"] = stored_credentials.display_name

Finally, route the user to the sign in page if we don't have their credentials. If we do, route them to the main add-on page.

if "credentials" not in flask.session or \
    flask.session["credentials"]["refresh_token"] is None:
    return flask.render_template("authorization.html")

return flask.render_template(
    "addon-discovery.html",
    message="You've reached the addon discovery page.")

Java

Navigate to your add-on landing route (/addon-discovery in the provided example). As discussed above, this is where you handled the login_hint and hd query parameters.

First, check if credentials exist in the session. If they don't, route the user through the auth flow by calling the startAuthFlow method.

/** Check if the credentials exist in the session. The session could have
 *   been cleared when the user clicked the Sign-Out button, and the expected
 *   behavior after sign-out would be to display the sign-in page when the
 *   iframe is opened again. */
if (session.getAttribute("credentials") == null) {
    return startAuthFlow(model);
}

Then, load the user from the H2 database if this is a repeat visitor. It's a repeat visitor if you receive the login_hint query parameter. If the user exists in the H2 database, load the credentials from the credential datastore set up previously, and set the credentials in the session. If the credentials were not obtained from the credential datastore, route the user through the auth flow by calling startAuthFlow.

/** At this point, we know that credentials exist in the session, but we
 *   should update the session credentials with the credentials in persistent
 *   storage in case they were refreshed. If the credentials in persistent
 *   storage are null, we should navigate the user to the authorization flow
 *   to obtain persisted credentials. */

User storedUser = getUser(login_hint);

if (storedUser != null) {
    Credential credential = authService.loadFromCredentialDataStore(login_hint);
    if (credential != null) {
        session.setAttribute("credentials", credential);
    } else {
        return startAuthFlow(model);
    }
}

Finally, route the user to the add-on landing page.

/** Finally, if there are credentials in the session and in persistent
 *   storage, direct the user to the addon-discovery page. */
return "addon-discovery";