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 the standard OAuth2 authorization code flow. Initiating social login is as simple as directing the user’s browser to one of the two provider-specific endpoints below — Spring Security’s OAuth2 client handles the rest, including the callback, PKCE state parameter, and provider token exchange. After the provider confirms the user’s identity, Auth Service either creates a new account or links the identity to an existing one, then redirects the browser back to your frontend with a short-lived, single-use exchange code that your client must trade for a JWT access token and refresh token pair.

​
Endpoints

​
GET /oauth2/authorization/google

Redirects the user’s browser to Google’s OAuth2 consent screen to begin the authorization code flow. Auth: None required Response: 302 Found — the redirect is handled entirely by Spring Security OAuth2 Client; no JSON body is returned. Scopes requested: openid, email, profile 
# Open in a browser or trigger via a frontend redirect
GET http://localhost:8080/oauth2/authorization/google

​
GET /oauth2/authorization/github

Redirects the user’s browser to GitHub’s OAuth2 authorization page to begin the authorization code flow. Auth: None required Response: 302 Found — the redirect is handled entirely by Spring Security OAuth2 Client; no JSON body is returned. Scopes requested: read:user, user:email 
# Open in a browser or trigger via a frontend redirect
GET http://localhost:8080/oauth2/authorization/github
The user:email scope is required for GitHub because GitHub users can mark their email address as private on their profile. Without this scope, the /user/emails API endpoint is inaccessible and Auth Service cannot retrieve a verified primary email address to associate with the account.

​
The OAuth2 callback

After the user authorizes (or denies) access, the provider redirects back to the Spring Security-managed callback URL: 
GET /login/oauth2/code/{provider}
Where {provider} is either google or github. You do not need to implement or call this endpoint yourself — Spring Security handles the provider token exchange and user info fetch automatically. Auth Service’s OAuth2AuthenticationSuccessHandler then takes over.

​
What happens after a successful authorization

Once the provider confirms the user’s identity, Auth Service performs the following steps in order:
  1. Creates or links the account. If no account exists for the provider identity, a new one is created. If an account with the same verified email already exists, the federated identity is linked to it.
  2. Generates a one-time exchange code. The JWT access token and refresh token are placed in an in-memory store keyed by a short-lived, single-use code. The tokens themselves are not placed in the redirect URL.
  3. Redirects to your frontend at OAUTH2_SUCCESS_REDIRECT_URI with the exchange code as a query parameter:
{OAUTH2_SUCCESS_REDIRECT_URI}?code=<one-time-code>
  1. Your client must exchange the code by calling POST /auth/oauth2/exchange with the code from the query parameter. See POST /auth/oauth2/exchange for the full reference.
If login fails at any point — the user denies consent, the provider rejects the token exchange, or Auth Service cannot process the identity — the browser is redirected to: 
{OAUTH2_FAILURE_REDIRECT_URI}?error=federated_login_failed

​
Initiating login from a frontend

Because the OAuth2 flow requires browser redirects, you initiate it by pointing the user’s browser directly at the endpoint — not via a JavaScript fetch or XMLHttpRequest call. 
<!-- Simple HTML link -->
<a href="http://localhost:8080/oauth2/authorization/google">
  Sign in with Google
</a>

<a href="http://localhost:8080/oauth2/authorization/github">
  Sign in with GitHub
</a>

// Or trigger programmatically
window.location.href = "http://localhost:8080/oauth2/authorization/google";
After the flow completes, your frontend landing page (at OAUTH2_SUCCESS_REDIRECT_URI) receives the ?code= query parameter and must call POST /auth/oauth2/exchange to retrieve the actual tokens.

​
Configuration

Both OAUTH2_SUCCESS_REDIRECT_URI and OAUTH2_FAILURE_REDIRECT_URI must be set as environment variables before starting Auth Service. If either is missing, the OAuth2 redirect handlers will fail at runtime. Additionally, you must register the Spring Security callback URL (http://localhost:8080/login/oauth2/code/google and /login/oauth2/code/github) as an authorized redirect URI in your Google Cloud Console and GitHub OAuth App settings respectively.
VariableDescriptionExample
OAUTH2_SUCCESS_REDIRECT_URIFrontend URL to redirect to after successful login. Receives ?code=<exchange-code>.http://localhost:3000/oauth2/success
OAUTH2_FAILURE_REDIRECT_URIFrontend URL to redirect to after failed login. Receives ?error=federated_login_failed.http://localhost:3000/oauth2/failure
GOOGLE_CLIENT_IDGoogle OAuth2 application client ID.—
GOOGLE_CLIENT_SECRETGoogle OAuth2 application client secret.—
GITHUB_CLIENT_IDGitHub OAuth App client ID.—
GITHUB_CLIENT_SECRETGitHub OAuth App client secret.—

Build docs developers (and LLMs) love

Get started for freeTalk to us