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.

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.

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).

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).

{
    "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:

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

Response

{
    "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

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

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