Google OAuth 2.1 Integration

Overview

This document describes the integration of Google OAuth 2.1 for user authentication within the application. This feature allows users to sign in using their Google accounts, providing a seamless and secure authentication experience. The process involves initiating an OAuth flow with Google, handling the callback, exchanging authorization codes for tokens, and ultimately generating a JSON Web Token (JWT) for the authenticated user.

Configuration

To enable Google OAuth 2.1 authentication, the following environment variables must be configured. These variables are loaded into the central Env struct in imphnen-libs.

GOOGLE_CLIENT_ID: Your Google OAuth 2.1 Client ID.
GOOGLE_CLIENT_SECRET: Your Google OAuth 2.1 Client Secret.
GOOGLE_REDIRECT_URL: The URL to which Google will redirect the user after successful authentication. This must match one of the authorized redirect URIs configured in your Google Cloud Console.

Obtaining Credentials from Google Cloud Console

Navigate to Google Cloud Console: Go to the Google Cloud Console.
Select/Create a Project: Choose an existing project or create a new one.
Enable Google People API: In the navigation menu, go to APIs & Services > Library and search for "Google People API" and enable it.
Create OAuth Consent Screen: Go to APIs & Services > OAuth consent screen.
- Configure your consent screen, including application name, user support email, and developer contact information.
Create Credentials: Go to APIs & Services > Credentials.
- Click Create Credentials > OAuth client ID.
- Select "Web application" as the application type.
- Provide a name for your OAuth 2.0 client.
- Under Authorized redirect URIs, add the GOOGLE_REDIRECT_URL specified in your environment variables (e.g., http://127.0.0.1:8080/api/v1/auth/google/callback).
- Click "Create". Your Client ID and Client Secret will be displayed. Copy these values and set them as GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in your environment.

API Endpoints

1. Initiate Google OAuth Flow

Endpoint: /api/v1/auth/google/login
Method: GET
Description: This endpoint initiates the Google OAuth 2.1 authentication flow. When accessed, it generates a Google authorization URL and redirects the user's browser to Google's authentication page. The user will be prompted to grant permissions to your application.
Example curl command:
```
curl -v http://127.0.0.1:8080/api/v1/auth/google/login
```
Upon successful execution, this command will return a 302 Found status with a Location header containing the Google authorization URL. Your browser would typically follow this redirect.

2. Handle Google OAuth Callback

Endpoint: /api/v1/auth/google/callback
Method: GET
Description: This endpoint handles the redirect from Google after the user has authenticated and granted permissions. Google sends an authorization code and a state parameter to this URL. The application then uses this code to exchange it for an access token and user information with Google. Upon successful validation and user creation/login, a full LoginResponse object is returned, identical to the credential-based login, which includes an access token, refresh token, and user details.
Query Parameters:
- code (required): The authorization code provided by Google.
- state (required): The CSRF token generated during the login initiation.

Example curl command (conceptual, as code and state are dynamic):

# This curl command is illustrative. The `code` and `state` values are obtained dynamically
# from Google's redirect after the user authorizes your application.
# Replace <AUTHORIZATION_CODE> and <CSRF_STATE> with actual values from the Google redirect.

curl -v "http://127.0.0.1:8080/api/v1/auth/google/callback?code=<AUTHORIZATION_CODE>&state=<CSRF_STATE>"

A successful response will typically return a JSON object containing the generated JWT:

{
  "token": {
    "access_token": "your_access_token_here",
    "refresh_token": "your_refresh_token_here"
  },
  "user": {
    "id": "user_id_here",
    "role": {
      "id": "role_id_here",
      "name": "Role Name",
      "permissions": [],
      "created_at": "2023-01-01T12:00:00Z",
      "updated_at": "2023-01-01T12:00:00Z"
    },
    "fullname": "User Fullname",
    "email": "user@example.com",
    "avatar": "http://example.com/avatar.jpg",
    "phone_number": "1234567890",
    "is_active": true,
    "gender": "Male",
    "birthdate": "2000-01-01T00:00:00Z",
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  }
}

OAuth Flow Diagram

graph TD
    A[User] --> B{Access /api/v1/auth/google/login};
    B --> C[Backend generates Auth URL];
    C --> D{Redirect to Google Auth Page};
    D --> E[User Authenticates with Google];
    E --> F{Google Redirects to /api/v1/auth/google/callback};
    F --> G[Backend Exchanges Code for Token];
    G --> H[Backend Fetches User Info];
    H --> I{User Exists?};
    I -- Yes --> J[Retrieve User];
    I -- No --> K[Create New User];
    J --> L[Generate JWT];
    K --> L;
    L --> M[Return JWT to User];

5.4 KiB Raw Blame History