111 lines
5.4 KiB
Markdown
111 lines
5.4 KiB
Markdown
# 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
|
|
|
|
1. **Navigate to Google Cloud Console:** Go to the [Google Cloud Console](https://console.cloud.google.com/).
|
|
2. **Select/Create a Project:** Choose an existing project or create a new one.
|
|
3. **Enable Google People API:** In the navigation menu, go to `APIs & Services` > `Library` and search for "Google People API" and enable it.
|
|
4. **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.
|
|
5. **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:**
|
|
|
|
```bash
|
|
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):**
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```mermaid
|
|
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]; |