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 `token` expires, use the `refresh token` to get a new access `token`.

# 1. Authorization Request (User Initiates Login)

1. A user clicks on the **Login with Google** button on the the app `xorismesiti.gr`.
2. The app request permission to access certain Google APIs (like the user's email, profile, etc.).

```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.
- `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. User Login and Consent

1. The user is redirected to Google's login page.
2. If they're not already logged in, they will be prompted to enter their Google credentials.
3. After successful login, the user will be shown a consent screen where they can grant or deny permission for your app to access their Google account (e.g., email and profile information).

**User Action**: The user clicks "Allow" to grant access.

# 3. Authorization Code Response (Google Redirects to Your Platform)

1. Google redirects the user back to your platform's redirect_uri `https://xorismesiti.gr/callback` with an authorization_code in the query parameters.

```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
}
```