Skip to main content

​
Overview

The SGIVU Authorization Server (sgivu-auth) provides OAuth2 and OpenID Connect functionality. It issues signed JWT tokens using a JKS keystore and manages client registrations, user authorizations, and sessions.

​
Base URL

https://your-domain.com
In production, these endpoints are typically accessed through Nginx which routes OAuth2-related paths to the sgivu-auth service.

​
OAuth2 Endpoints

​
Authorization Endpoint

GET /oauth2/authorize
Initiates the OAuth2 authorization flow. Users are redirected here to grant authorization.
​
client_id
string
required
The OAuth2 client identifier
​
redirect_uri
string
required
The URI to redirect to after authorization
​
response_type
string
required
The OAuth2 response type (typically code)
​
scope
string
required
Space-separated list of requested scopes (e.g., openid profile email)
​
state
string
Opaque value to maintain state between request and callback
​
code_challenge
string
PKCE code challenge for public clients
​
code_challenge_method
string
PKCE code challenge method (S256 or plain)

​
Response

Redirects to redirect_uri with authorization code: 
HTTP/1.1 302 Found
Location: {redirect_uri}?code={authorization_code}&state={state}

​
Token Endpoint

POST /oauth2/token
Exchanges authorization code for access tokens or refreshes existing tokens. Content-Type: application/x-www-form-urlencoded Authentication: Client credentials via Basic Auth header or request body

​
Authorization Code Grant

​
grant_type
string
required
Must be authorization_code
​
code
string
required
The authorization code received from the authorization endpoint
​
redirect_uri
string
required
Must match the redirect_uri used in authorization request
​
client_id
string
Required if not using Basic Auth
​
client_secret
string
Required for confidential clients if not using Basic Auth
​
code_verifier
string
PKCE code verifier for public clients

​
Refresh Token Grant

​
grant_type
string
required
Must be refresh_token
​
refresh_token
string
required
The refresh token previously issued
​
scope
string
Optional: requested scope (must be subset of original scope)

​
Response

​
access_token
string
The JWT access token for accessing protected resources
​
token_type
string
Always Bearer
​
expires_in
integer
Token lifetime in seconds
​
refresh_token
string
Refresh token for obtaining new access tokens
​
scope
string
Space-separated list of granted scopes
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "v1.MRxzFDdS3L5rWnZ...",
  "scope": "openid profile email"
}

​
Status Codes

  • 200 OK - Token successfully issued
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Invalid client credentials

​
Example

curl -X POST https://your-domain.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "client_id:client_secret" \
  -d "grant_type=authorization_code" \
  -d "code=SplxlOBeZQQYbYS6WxSbIA" \
  -d "redirect_uri=https://client.example.com/callback"

​
JWKS Endpoint

GET /oauth2/jwks
Publishes the JSON Web Key Set used to verify JWT signatures. Authentication: None (public endpoint)

​
Response

​
keys
array
Array of JWK objects containing public keys
{
  "keys": [
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "sig",
      "kid": "sgivu-jwt-key",
      "alg": "RS256",
      "n": "xGOr-H7A..."
    }
  ]
}

​
OpenID Connect Endpoints

​
Discovery Endpoint

GET /.well-known/openid-configuration
Returns OpenID Connect discovery metadata. Authentication: None (public endpoint)

​
Response

​
issuer
string
The issuer identifier URL
​
authorization_endpoint
string
URL of the authorization endpoint
​
token_endpoint
string
URL of the token endpoint
​
jwks_uri
string
URL of the JWKS endpoint
​
response_types_supported
array
Supported OAuth2 response types
​
grant_types_supported
array
Supported OAuth2 grant types
​
subject_types_supported
array
Supported subject identifier types
​
id_token_signing_alg_values_supported
array
Supported signing algorithms for ID tokens
{
  "issuer": "https://your-domain.com",
  "authorization_endpoint": "https://your-domain.com/oauth2/authorize",
  "token_endpoint": "https://your-domain.com/oauth2/token",
  "jwks_uri": "https://your-domain.com/oauth2/jwks",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

​
Login Endpoint

GET /login
Displays the login page for user authentication. Authentication: None (public endpoint)

​
Security Considerations

​
JWT Signing

  • JWTs are signed using RSA keys from a JKS keystore
  • The keystore location and password are configured via sgivu.jwt.keystore.location and sgivu.jwt.keystore.password
  • Never commit keystore files to version control
  • Use a secret manager or secure pipeline to provide the keystore in production

​
Default Clients

Three OAuth2 clients are registered by default:
  1. sgivu-gateway - Backend-for-Frontend (BFF) client
    • Client ID: sgivu-gateway
    • Secret: Configured via gateway-client.secret
  2. postman-client - For API testing
    • Client ID: postman-client
    • Secret: postman-secret
  3. oauth2-debugger-client - For OAuth2 debugging
    • Client ID: oauth2-debugger-client
    • Secret: oauth2-debugger-secret
Default client secrets are not secure for production use. Always override them with strong, randomly generated secrets.

​
Issuer Configuration

  • Configure ISSUER_URL to match the public hostname/URL
  • Issuer mismatch will cause token validation failures
  • Ensure consistency between authorization server and resource servers

​
Error Responses

OAuth2 errors follow the standard OAuth2 error response format: 
{
  "error": "invalid_grant",
  "error_description": "The provided authorization code is invalid or expired"
}

​
Common Error Codes

  • invalid_request - Missing or malformed parameters
  • invalid_client - Client authentication failed
  • invalid_grant - Invalid or expired authorization code
  • unauthorized_client - Client not authorized for this grant type
  • unsupported_grant_type - Grant type not supported
  • invalid_scope - Requested scope is invalid or exceeds granted scope

Build docs developers (and LLMs) love

Get started for freeTalk to us