Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ricardomb-tech/auth-service/llms.txt

Use this file to discover all available pages before exploring further.

Auth Service supports federated login via Google and GitHub using Spring Security’s OAuth2 client infrastructure. Rather than embedding the issued JWT access and refresh tokens in the redirect URL (which would expose them in browser history, proxy logs, and Referer headers), the service follows a one-time exchange code pattern: after the provider authenticates the user, Auth Service redirects the browser to a frontend URL carrying a short-lived, opaque code parameter. The client then exchanges that code for the real token pair via a direct back-channel POST request. This keeps tokens out of the URL entirely.

​
OAuth2 login flow

1

Redirect the user to the provider

Your frontend sends the user’s browser to one of the two authorization endpoints. Spring Security handles building the full authorization URL, including state and code_challenge parameters. The state value is stored in a cookie (instead of the HTTP session) to keep the service fully stateless.Google
GET /oauth2/authorization/google
GitHub
GET /oauth2/authorization/github
No request body or custom headers are required. Simply redirect or link the browser to these URLs.
2

User authenticates with the provider

The user is taken to Google’s or GitHub’s consent screen. Auth Service is not involved at this stage. The provider validates the user’s identity and, if successful, redirects the browser back to the Auth Service callback URL.
3

Auth Service processes the callback

Spring Security validates the authorization code returned by the provider and fetches the user’s profile from the provider’s userinfo endpoint. For Google this uses the OIDC id_token flow; for GitHub a custom GitHubOAuth2UserService resolves the primary verified email from the GitHub emails API.Federated identity linking: if the provider’s verified email matches an email address already registered in Auth Service (whether via credentials or another provider), the OAuth2 identity is linked to that existing account. No duplicate accounts are created. If no account exists for that email, a new one is created in ACTIVE state (email is considered verified by the provider).
GitHub accounts that do not have a verified primary email (e.g. a private email-only setup with no public email) will fail the federated login. Auth Service requires a verified email from every provider.
4

Auth Service issues a one-time exchange code and redirects

On success, OAuth2AuthenticationSuccessHandler issues a short-lived, single-use exchange code (stored server-side) and redirects the browser to:
{OAUTH2_SUCCESS_REDIRECT_URI}?code=<one-time-code>
For example:
https://app.example.com/oauth2/success?code=a1b2c3d4e5f6...
The exchange code — not the access or refresh token — travels in the redirect URL. This is intentional: a code is useless once consumed, has a short TTL, and does not grant direct API access on its own. Tokens sent in query parameters would be logged by web servers, visible in browser history, and potentially leaked via the Referer header to any third-party resource on the redirect target page.
5

Exchange the code for tokens

Your frontend reads the code query parameter and immediately exchanges it for a real token pair by calling POST /auth/oauth2/exchange. This call should be made server-side or from a trusted context — not exposed as a user-facing URL.
curl -X POST https://your-auth-service/auth/oauth2/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "code": "a1b2c3d4e5f6..."
  }'
Response — 200 OK
{
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "d3f4a2b1c9e8...",
  "tokenType": "Bearer",
  "expiresInSeconds": 900
}
The response is identical to the credential login response (LoginResponse). From this point on, the access and refresh token lifecycle is the same as for credential-based login — see Token Management.If the exchange code is invalid, expired, or has already been consumed, the endpoint returns 401 Unauthorized with a application/problem+json body.

​
Failure handling

When the OAuth2 flow fails — the user denies consent, the provider returns an error, or Auth Service cannot process the user’s profile — the browser is redirected to: 
{OAUTH2_FAILURE_REDIRECT_URI}?error=federated_login_failed
The error query parameter is always federated_login_failed, regardless of the actual cause. Auth Service intentionally reveals no details about why the federated login failed (provider error vs. internal validation failure vs. unverified email). Your frontend should display a generic “social login failed” message and prompt the user to try again or use a different method.

​
Required environment variables

Configure the following variables before enabling OAuth2 social login. All six are required; missing values will cause the service to fail on startup in the prod profile.
VariableDescription
GOOGLE_CLIENT_IDOAuth2 client ID from the Google Cloud Console.
GOOGLE_CLIENT_SECRETOAuth2 client secret from the Google Cloud Console.
GITHUB_CLIENT_IDOAuth2 client ID from the GitHub Developer Settings.
GITHUB_CLIENT_SECRETOAuth2 client secret from the GitHub Developer Settings.
OAUTH2_SUCCESS_REDIRECT_URIFrontend URL that receives the ?code= parameter after a successful login. Example: https://app.example.com/oauth2/success.
OAUTH2_FAILURE_REDIRECT_URIFrontend URL that receives ?error=federated_login_failed after a failed login. Example: https://app.example.com/oauth2/failure.
Register {AUTH_SERVICE_BASE_URL}/login/oauth2/code/google and {AUTH_SERVICE_BASE_URL}/login/oauth2/code/github as authorized redirect URIs in each provider’s developer console.

Build docs developers (and LLMs) love

Get started for freeTalk to us