GoAuth

https://goauth.gitbook.io/goauth-documentation
Admin
GoAuth is a private authorization service that simplifies adding social login (Google, Yandex, VK...
Tokens:954
Snippets:6
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Session Creation Workflow

Source: https://goauth.gitbook.io/goauth-documentation/handling-callback

Steps to create a user session in your application after successful data verification.

```APIDOC
## Session Creation Workflow

### Description
Once the data authenticity is confirmed via the hash, proceed to create a user session within your application.

### Steps
1. **Find or Create User**: Locate or create a user record in your database using a combination of `provider` and `provider_user_id`.
2. **Update Profile Data**: Refresh the user's profile information (email, name, avatar) with the data received.
3. **Generate Session Token**: Create a session token for the authenticated user.
4. **Redirect User**: Redirect the user to the appropriate section of your application.
```

--------------------------------

### Data Verification using Hash

Source: https://goauth.gitbook.io/goauth-documentation/handling-callback

Instructions on how to verify the authenticity of the user data received in the callback by checking the HMAC hash.

```APIDOC
## Data Verification using Hash

### Description
It is crucial to verify the `hash` parameter to ensure the data originates from GoAuth and has not been tampered with.

### Method
1. **Construct Data for Signing**: Assemble the relevant parameters into a JSON object.
   ```json
   {
     "provider": "google",
     "provider_user_id": "123",
     "email": "user@example.com",
     "name": "Ivan Petrov",
     "first_name": "Ivan",
     "last_name": "Petrov"
   }
   ```
2. **Sort Keys**: Alphabetically sort the keys of the JSON object.
3. **Calculate HMAC-SHA256**: Compute the HMAC-SHA256 hash of the sorted JSON string using your `project_secret` as the key.
4. **Compare Hash**: Compare the calculated hash with the `hash` parameter received in the callback URL.

If the hashes match, the data is considered valid.
```

--------------------------------

### Error Handling

Source: https://goauth.gitbook.io/goauth-documentation/handling-callback

Information on how GoAuth handles authentication failures.

```APIDOC
## Error Handling

### Description
If the authentication process fails for any reason, the user will not be redirected to your callback URL. Instead, GoAuth will display an error page to the user.
```

--------------------------------

### Callback URL Format

Source: https://goauth.gitbook.io/goauth-documentation/handling-callback

This is the format of the callback URL that GoAuth redirects to after a successful authorization. It includes query parameters containing user profile data and a hash for verification.

```plaintext
https://example.com/auth/callback?provider=google&provider_user_id=123...&email=user@example.com&name=Ivan+Petrov&hash=abc123...
```

--------------------------------

### Callback URL Parameters

Source: https://goauth.gitbook.io/goauth-documentation/handling-callback

Details on the query parameters appended to the redirect URL after successful authorization, containing user profile information.

```APIDOC
## Callback URL Parameters

### Description
After successful authorization, the user is redirected to your `redirect_url` with GET parameters containing profile data.

### Format
`https://example.com/auth/callback?provider=google&provider_user_id=123...&email=user@example.com&name=Ivan+Petrov&hash=abc123...`

### Parameters
#### Query Parameters
- **provider** (string) - Required - The authentication provider (e.g., `google`, `yandex`, `vk`, `telegram`).
- **provider_user_id** (string) - Required - The unique user ID from the provider's system.
- **email** (string) - Optional - The user's email address, if provided by the provider.
- **name** (string) - Optional - The full name of the user.
- **first_name** (string) - Optional - The first name of the user.
- **last_name** (string) - Optional - The last name of the user.
- **username** (string) - Optional - The username of the user (e.g., in Telegram).
- **avatar** (string) - Optional - The URL of the user's avatar.
- **hash** (string) - Required - An HMAC signature of the data for verification.
```

--------------------------------

### User Data Signing JSON Structure

Source: https://goauth.gitbook.io/goauth-documentation/handling-callback

This JSON structure represents the data that needs to be signed for hash generation. The keys must be sorted alphabetically before calculating the HMAC-SHA256.

```json
{
  "provider": "google",
  "provider_user_id": "123",
  "email": "user@example.com",
  "name": "Ivan Petrov",
  "first_name": "Ivan",
  "last_name": "Petrov"
}
```
Tokens:
Raw