dev/OAuth2.md

### OAuth2 purpose

A way for the `user` to tell `google` to give an access token to `xorismesiti.gr` app

### OAuth2 Flow:

1. **User clicks** "Login with Google" on your platform `xorismesiti.gr`
2. **Authorization Request**: Redirect to Google's authorization endpoint `accounts.google.com/o/oauth2`, requesting the user's data
3. **User Login and Consent**: User login to Google and grants permissions.
4. **Authorization Code Response**: Google redirects back to your platform `xorismesiti.gr/callback` with an authorization `code`.
5. **Access Token Request**: Exchange the authorization `code` for an `access_token`.
6. **Access Protected Resources**: Use the `access_token` to fetch the user's Google profile and email from `googleapis.com/oauth2`
7. **Token Refresh** (Optional): If the `access_token` expires, use the `refresh token` to get a new `access_token`.




# 1. [Frontend] Authorization Request: Redirect the user to Google's OAuth Authorization Endpoint

1. Action: The frontend provides a "Login with Google" button.
2. When the user clicks it, the frontend constructs a URL to Google's OAuth 2.0 authorization endpoint and redirects the user there.
3. After this redirection, the user will log in to Google and grant permissions (if they haven’t already).
4. Google will redirect the user back to your specified redirect_uri with an authorization code.

```sh
GET https://accounts.google.com/o/oauth2/v2/auth?
    response_type=code&
    client_id=YOUR_GOOGLE_CLIENT_ID&
    redirect_uri=https://xorismesiti.gr/callback&
    scope=email%20profile&
    state=xyz123
```

- `response_type=code`: This indicates you're using the "authorization code" flow.
- `client_id`: Your Google API client ID. Created by the developers of the `xorismesiti.gr` on the google API console.
- `redirect_uri`: The URI Google will redirect to after the user consents.
- `scope`: The permissions you're requesting (e.g., email, profile).
- `state`: A random string to protect against CSRF attacks.




# 2. Frontend (Next.js): Receive the Authorization Code and Send it to the Backend

1. Once the user grants permission,
2. Google will redirect the user to the `redirect_uri` you specified in the previous step (e.g., https://xorismesiti.gr/api/auth/callback)

The frontend must not directly exchange the `code` for an `access_token`. 

Instead, it sends the `code` to the backend via an API request.



# 3. Backend (Node.js): Handle Token Exchange

1. The backend makes a `POST` request to Google token endpoint, to exchange the authorization `code` for the `access_token` and optionally a `refresh token`
2. Ensure you never expose the client_secret to the frontend. This step should always be handled on the backend.
3. The backend will exchange the `code` for an `access_token` and `refresh_token`, which are sent back to the frontend or stored securely for subsequent API calls.

```sh
GET https://xorismesiti.gr/callback?
    code=4/0AX4XfWgNmGZVbV7Kdr8Q9yVyzIYBnbbBdLfX39ZaE8m0w8zT8jKRLl7w-uT8k7WiyLg0Q&
    state=xyz123
```

- `HTTP` Method: GET
- `URL`: https://xorismesiti.gr/callback
- `Parameters`:
    - `code`: The authorization code sent by Google.
    - `state`: The same state value sent in the original request (for CSRF protection).


# 4. Access Token Request (Exchange Authorization Code for Token)

Now your platform can use exchange the authorization code for an access token and refresh token. 

1. it sends a POST request to Google's token endpoint

- `HTTP` Method: POST
- `URL`: https://oauth2.googleapis.com/token
- `Headers`:
    - `Content`-Type: application/x-www-form-urlencoded
- `Body` Parameters:
    - `grant_type`=authorization_code: This specifies the grant type.
    - `code`: The authorization code you received in the previous step.
    - `redirect_uri`: The same redirect URI used in the authorization request.
    - `client_id`: Your Google API client ID.
    - `client_secret`: Your Google API client secret (which should be kept secure).


```sh
POST https://oauth2.googleapis.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=4/0AX4XfWgNmGZVbV7Kdr8Q9yVyzIYBnbbBdLfX39ZaE8m0w8zT8jKRLl7w-uT8k7WiyLg0Q&
redirect_uri=https://xorismesiti.gr/callback&
client_id=YOUR_GOOGLE_CLIENT_ID&
client_secret=YOUR_GOOGLE_CLIENT_SECRET
```

# 5. Access Token Response (Google Returns Tokens)

1. Google validates the request 
2. and returns a response with the access token (which can be used to access the user's Google resources) 
3. and optionally, a refresh token (which can be used to refresh the access token when it expires).

```json
{
    "access_token": "ya29.a0AfH6SMC8Op6zXZkHi2XITkDoOVzYXt3hTY6sny54UlWlxrnKlX5Xv78is7BEHekVX-VoA",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "1//04d5XHqmn6Hdy3wTf5OYDP1SyBa74zEFURjddQ2A1cFw78PY13pQyWhlD2A6XhDQtKlrjAqU4kS3vGdMvckw",
    "scope": "email profile"
}
```

- HTTP Method: 200 OK
- Response Body:
    - access_token: The access token used for accessing the user's resources (e.g., profile, email).
    - token_type: Usually Bearer, indicating the type of token.
    - expires_in: The lifetime of the access token in seconds (e.g., 3600 seconds = 1 hour).
    - refresh_token: (Optional) The refresh token used to obtain a new access token when the current one expires.
    - scope: The scope of access granted (e.g., email, profile).


# 6. Access Protected Resources (Fetching User Profile Data)

With the access token obtained in the previous step, 

your platform can now use it to fetch the user's Google profile and email information. 

The token is included in the Authorization header of the request.


- URL: https://www.googleapis.com/oauth2/v3/userinfo
- HTTP Method: GET
- Headers:
- Authorization: Bearer {access_token}: The access token obtained in step 5.


**Request:**

```sh
GET https://www.googleapis.com/oauth2/v3/userinfo
Authorization: Bearer ya29.a0AfH6SMC8Op6zXZkHi2XITkDoOVzYXt3hTY6sny54UlWlxrnKlX5Xv78is7BEHekVX-VoA
```

**Response**

```json
{
    "sub": "1234567890",
    "name": "John Doe",
    "given_name": "John",
    "family_name": "Doe",
    "profile": "https://plus.google.com/1234567890",
    "picture": "https://lh3.googleusercontent.com/a-/AOh14GgIXXl5JXzW0c1Szbl-e1Jch1vhl5rHhH65vlK6J5g5PqkGjj1O0p3t8bgVEOykQ6ykFSQ=s96",
    "email": "john.doe@example.com",
    "email_verified": true,
    "locale": "en"
}
```


# 7. Refreshing the Access Token (If Necessary)

If the access token expires, 

your platform can use the refresh token (if provided) to obtain a new access token without requiring the user to log in again.

- `URL`: https://oauth2.googleapis.com/token
- `HTTP` Method: POST
- `Headers`:
- `Content`-Type: application/x-www-form-urlencoded
- `Body` Parameters:
- `grant_type`=refresh_token: This indicates the refresh token flow.
- `refresh_token`: The refresh token obtained in step 5.
- `client_id`: Your Google API client ID.
- `client_secret`: Your Google API client secret.

**Request**

```sh
POST https://oauth2.googleapis.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=1//04d5XHqmn6Hdy3wTf5OYDP1SyBa74zEFURjddQ2A1cFw78PY13pQyWhlD2A6XhDQtKlrjAqU4kS3vGdMvckw&
client_id=YOUR_GOOGLE_CLIENT_ID&
client_secret=YOUR_GOOGLE_CLIENT_SECRET
```

**Response**

```json
{
    "access_token": "ya29.a0AfH6SMC8Op6zXZkHi2XITkDoOVzYXt3hTY6sny54UlWlxrnKlX5Xv78is7BEHekVX-VoA",
    "token_type": "Bearer",
    "expires_in": 3600
}
```