[FEAT] Google OAuth2 Authentication for User Login

[johnson-oragui]

Description

Iimplement Google OAuth2 authentication as a login option for our API. This feature will allow users to log in using their Google accounts, making the authentication process seamless and secure. Enhancing user convenience and security, reduce the need for password management, and offer a popular and trusted authentication method.

Acceptance Criteria

1. Google OAuth2 Login Endpoint:

   • A new endpoint GET /api/v1/auth/login/google that redirects the user to Google's OAuth2 login page.
   • The endpoint should handle the OAuth2 flow and redirect the user to the Google authentication page.

2. Callback Endpoint:

   • An Internal(not exposed) new endpoint GET /api/v1/auth/callback/google to handle the OAuth2 callback from Google.
   • This endpoint should handle the exchange of the authorization code for access and refresh tokens.
   • The endpoint should fetch user information from Google and create or update the user in our database.

3. Token Management:

   • Issue a JWT access token and a refresh token for the authenticated user.
   • Store the access and refresh tokens in relation to the user.
   • Ensure that the access token has a limited lifespan (e.g., 30 minutes) and the refresh token has a longer lifespan (e.g., 7 days).

4. Refresh Token Endpoint:

   • The endpoint POST /api/v1/auth/token/refresh must already exist to handle refresh token requests.
   • Verify the refresh token and issue a new access token if valid.

5. User Information Update:

   • On each re-authentication, fetch the latest user information from Google and update the database if there are changes.
   • Ensure the system handles cases where the user re-authenticates with a different Google account.

6. Error Handling:

   • Handle errors gracefully and provide meaningful error messages to the user.
   • Ensure that authentication failures, token exchange errors, and user information fetch errors are properly managed.

Purpose

This feature will allow users to log in using their Google accounts, making the authentication process seamless and secure, ensuring that any user who does not intend to use and memorized a new password can be able register and use the service.

Requirem#ents

1. Google OAuth2 Registration:

   • Register the application with Google and obtain a client_id and client_secret.
   • Configure the OAuth2 consent screen with necessary details.

2. Configuration:

   • Add the client_id, client_secret, and OAuth2 endpoints to the application's configuration.

3. Database Schema Updates:

   • Update the user model to store additional fields (e.g., Google user ID, access token, refresh token).

4. Dependencies:

   • Ensure the application includes necessary dependencies for handling OAuth2 (e.g., httpx for HTTP requests, jose for JWT handling).

Tasks:

1. Register Application with Google:

   • [ ] Register the application with Google and configure OAuth2 consent screen.
   • [ ] Obtain client_id and client_secret.
   • Store the credentials as environment variables on the server or use dedicated secret management tools offered by cloud providers or third-party services for secured storage and access controls.

2. Create OAuth2 Login Endpoint:

   • [ ] Implement the /api/v1/auth/login/google endpoint.
   • [ ] Redirect users to Google OAuth2 login.
   • payload

     {
     "code": "AUTHORIZATION_CODE",
     "client_id": "YOUR_CLIENT_ID",
     "client_secret": "YOUR_CLIENT_SECRET",
     "redirect_uri": "https://example.com/api/auth/callback/google",
     "grant_type": "authorization_code"
     }

   • response

     {
     "access_token": "ACCESS_TOKEN",
     "expires_in": 3599,
     "refresh_token": "REFRESH_TOKEN",
     "scope": "https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid",
     "token_type": "Bearer",
     "id_token": "ID_TOKEN"
     }

3. Implement Callback Handling:

   • [ ] Implement the /api/auth/callback/google endpoint.
   • [ ] Handle the exchange of authorization code for tokens and fetch user information.
   • GET request to "https://www.googleapis.com/oauth2/v1/userinfo?alt=json" for example with a header containing the access token from google Authorization: Bearer ACCESS_TOKEN
   • Google responds with the user's profile information. response:

     {
     "id": "12je23u-d2i9j2in-f4imi91jf98-49junu8d3un8dnuei",
     "email": "johnson.oragui@gmail.com",
     "verified_email": true,
     "name": "Johnson Oragui",
     "given_name": "Johnson",
     "family_name": "Oragui",
     "picture": "https://lh3.googleusercontent.com/a-/AOh14Gh2G_YHMAI",
     "locale": "en"
     }

   • Processes the user's profile information and creates or updates the user record in the database.
   • Save the access token and the refresh token from Google for future API calls(upon user re-authentication, update the access token and refresh token from Google in the database).

4. Token Issuance and Management:

   • [ ] Generate and issue JWT access and refresh tokens to user upon successful authentication with Google.
   • response

     {
     "status": "success",
     "message": "User successfully authenticated",
     "access_token": 1093e1398jd98913d09209048...,
     "refresh_token": 10kd0i9489i9238901.09r92009209j2.9389r8j239j889...,
     "user": {
     "id": "iomdi2j982j-309vkq309-3qrvq3v-34ijmqi9i3uvn3",
     "email": "johnson.oragui@gmail.com",
     "name": "Johnson Oragui",
     "given_name": "Johnson",
     "family_name": "Oragui",
     "picture": "https://lh3.googleusercontent.com/a-/AOh14Gh2G_YHMAI"
     }
     }

   • [ ] Implement token storage and management.

5. Refresh Token Endpoint:

   • [ ] Use the existing /api/auth/token/refresh endpoint.
   • [ ] Handle the refresh token verification and new access token issuance.

6. User Information Update Logic:

   • [ ] Implement logic to update user information on each re-authentication.
   • Check for changes in User information on every Google re-authentication
   • [ ] Handle cases of re-authentication with different Google accounts.
   • Create a new entry for the user upon re-authenticating with a different email
   • Update the database for the access and refresh tokens from Google
   • Blacklist the previous jwt tokens given to the user after issuing new token and refresh tokens

7. Error Handling and Testing:

   • [ ] Implement error handling for all authentication and token-related processes.
   • [ ] Write unit tests and integration tests for all new endpoints and functionalities.

Database Designs:

Table users{
    id varchar [pk, not null, unique]
    email varcahr [unique, not null]
    verified_email bool [default: 0, not null]
    first_name varchar
    last_name varchar
    password varchar [null]
    oauth_provider varchar [note: 'e.g., google', null]
    avatar varchar [note: 'a url']
    phone varc [null]
    last_login timestamp
    joined_at timestamp [default: `now()`, not null]
    updated_at timestamp [default: `now()`, not null]
    country_code int

    indexes {
      (id, email)
    }
}

Table google_oauth2_users {
    id varchar [pk, not null, unique]
    user_id varchar [ref: > users.id]
    email varchar [not null]
    google_id varchar [not null]
    expires_in int [not null]
    token_type varchar [not null]
    id_token varchar [not null]
    scope varchar
    access_token varchar [not null]
    refresh_token varchar [not null]
    created_at timestamp [default: `now()`, not null]
    updated_at timestamp [default: `now()`, not null]
    indexes {
      (google_id, user_id) [unique]
    }
}

Table user_tokens {
    id varchar [pk, not null, unique]
    user_id varchar [ref: > users.id, not null]
    token_type varchar [note: "access or refresh", not null]
    token_value varchar [not null]
    expires_at int [not null]
    created_at timestamp [default: `now()`, not null]
    Indexes {
      (user_id, token_type) [unique]
      id [unique]
    }
}

Expected Outcome

The user would easily authenticate with google account, be issued a token and a refresh token, and be able to use the service with the issued tokens.

[johnson-oragui]

Referred from the already approved Issue #139