Authentication

This page covers all authentication and authorization settings in NpgsqlRest, including cookie authentication, bearer token authentication, and external OAuth providers.

Overview

NpgsqlRest supports multiple authentication methods:

• Cookie Authentication - Traditional session-based authentication
• Bearer Token Authentication - JWT-style token authentication
• External OAuth Providers - Google, LinkedIn, GitHub, Microsoft, Facebook

{
  "Auth": {
    "CookieAuth": false,
    "BearerTokenAuth": false,
    "External": {
      "Enabled": false
    }
  }
}

Cookie Authentication

Cookie authentication provides session-based authentication using HTTP cookies.

{
  "Auth": {
    "CookieAuth": true,
    "CookieAuthScheme": null,
    "CookieValidDays": 14,
    "CookieName": null,
    "CookiePath": null,
    "CookieDomain": null,
    "CookieMultiSessions": true,
    "CookieHttpOnly": true
  }
}

Cookie Settings Reference

Setting	Type	Default	Description
CookieAuth	bool	false	Enable cookie authentication.
CookieAuthScheme	string	null	Authentication scheme name. Uses default if null.
CookieValidDays	int	14	Number of days the cookie remains valid.
CookieName	string	null	Custom name for the authentication cookie. Uses default if null.
CookiePath	string	null	Path scope for the cookie. Uses default if null.
CookieDomain	string	null	Domain scope for the cookie. Uses default if null.
CookieMultiSessions	bool	true	Allow multiple concurrent sessions for the same user.
CookieHttpOnly	bool	true	Make cookie accessible only via HTTP (not JavaScript).

Cookie Security

When CookieHttpOnly is true (recommended), the cookie cannot be accessed by client-side JavaScript, protecting against XSS attacks.

TIP

For production, always use HTTPS and consider setting CookieDomain to your specific domain.

Bearer Token Authentication

Bearer token authentication provides stateless token-based authentication, suitable for APIs and single-page applications.

{
  "Auth": {
    "BearerTokenAuth": true,
    "BearerTokenAuthScheme": null,
    "BearerTokenExpireHours": 1,
    "BearerTokenRefreshPath": "/api/token/refresh"
  }
}

Bearer Token Settings Reference

Setting	Type	Default	Description
BearerTokenAuth	bool	false	Enable bearer token authentication.
BearerTokenAuthScheme	string	null	Authentication scheme name. Uses default if null.
BearerTokenExpireHours	int	1	Number of hours before the token expires.
BearerTokenRefreshPath	string	"/api/token/refresh"	Endpoint path for refreshing tokens.

External OAuth Providers

NpgsqlRest supports OAuth authentication with popular external providers.

{
  "Auth": {
    "External": {
      "Enabled": true,
      "SigninUrl": "/signin-{0}",
      "ReturnToPath": "/",
      "LoginCommand": "select * from external_login($1,$2,$3,$4,$5)"
    }
  }
}

External Auth Settings Reference

Setting	Type	Default	Description
Enabled	bool	false	Enable external OAuth providers.
BrowserSessionStatusKey	string	"__external_status"	sessionStorage key for auth status (HTTP status code).
BrowserSessionMessageKey	string	"__external_message"	sessionStorage key for auth message.
SigninUrl	string	"/signin-{0}"	Sign-in page URL pattern. {0} is replaced with provider name.
SignInHtmlTemplate	string	(see below)	HTML template for the sign-in page.
RedirectUrl	string	null	URL to redirect after auth. Usually auto-detected.
ReturnToPath	string	"/"	Default path to redirect after auth completes.
ReturnToPathQueryStringKey	string	"return_to"	Query string key for dynamic return path.
LoginCommand	string	"select * from external_login($1,$2,$3,$4,$5)"	PostgreSQL command to execute after OAuth login. Uses the same result processing logic as the login endpoint.
ClientAnalyticsData	string	(JavaScript object)	Browser analytics data sent to login command.
ClientAnalyticsIpKey	string	"ip"	JSON key for client IP in analytics data.

Login Command Parameters

The LoginCommand receives up to five parameters:

Parameter	Type	Description
$1	text	External login provider name (e.g., "google", "github")
$2	text	User's email address
$3	text	User's display name
$4	text/json/jsonb	Raw JSON data from the OAuth provider
$5	text/json/jsonb	Browser analytics data (screen size, timezone, etc.)

OAuth Providers

Google

{
  "Auth": {
    "External": {
      "Enabled": true,
      "Google": {
        "Enabled": true,
        "ClientId": "{GOOGLE_CLIENT_ID}",
        "ClientSecret": "{GOOGLE_CLIENT_SECRET}",
        "AuthUrl": "https://accounts.google.com/o/oauth2/v2/auth?response_type=code&client_id={0}&redirect_uri={1}&scope=openid profile email&state={2}",
        "TokenUrl": "https://oauth2.googleapis.com/token",
        "InfoUrl": "https://www.googleapis.com/oauth2/v3/userinfo",
        "EmailUrl": null
      }
    }
  }
}

Configure your app at Google Cloud Console.

LinkedIn

{
  "Auth": {
    "External": {
      "Enabled": true,
      "LinkedIn": {
        "Enabled": true,
        "ClientId": "{LINKEDIN_CLIENT_ID}",
        "ClientSecret": "{LINKEDIN_CLIENT_SECRET}",
        "AuthUrl": "https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id={0}&redirect_uri={1}&state={2}&scope=r_liteprofile%20r_emailaddress",
        "TokenUrl": "https://www.linkedin.com/oauth/v2/accessToken",
        "InfoUrl": "https://api.linkedin.com/v2/me",
        "EmailUrl": "https://api.linkedin.com/v2/emailAddress?q=members&projection=(elements//(handle~))"
      }
    }
  }
}

Configure your app at LinkedIn Developers.

GitHub

{
  "Auth": {
    "External": {
      "Enabled": true,
      "GitHub": {
        "Enabled": true,
        "ClientId": "{GITHUB_CLIENT_ID}",
        "ClientSecret": "{GITHUB_CLIENT_SECRET}",
        "AuthUrl": "https://github.com/login/oauth/authorize?client_id={0}&redirect_uri={1}&state={2}&allow_signup=false",
        "TokenUrl": "https://github.com/login/oauth/access_token",
        "InfoUrl": "https://api.github.com/user",
        "EmailUrl": null
      }
    }
  }
}

Configure your app at GitHub Developer Settings.

Microsoft

{
  "Auth": {
    "External": {
      "Enabled": true,
      "Microsoft": {
        "Enabled": true,
        "ClientId": "{MICROSOFT_CLIENT_ID}",
        "ClientSecret": "{MICROSOFT_CLIENT_SECRET}",
        "AuthUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?response_type=code&client_id={0}&redirect_uri={1}&scope=openid%20profile%20email&state={2}",
        "TokenUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
        "InfoUrl": "https://graph.microsoft.com/oidc/userinfo",
        "EmailUrl": null
      }
    }
  }
}

Configure your app at Azure Portal. See Microsoft Identity Platform documentation.

Facebook

{
  "Auth": {
    "External": {
      "Enabled": true,
      "Facebook": {
        "Enabled": true,
        "ClientId": "{FACEBOOK_CLIENT_ID}",
        "ClientSecret": "{FACEBOOK_CLIENT_SECRET}",
        "AuthUrl": "https://www.facebook.com/v20.0/dialog/oauth?response_type=code&client_id={0}&redirect_uri={1}&scope=public_profile%20email&state={2}",
        "TokenUrl": "https://graph.facebook.com/v20.0/oauth/access_token",
        "InfoUrl": "https://graph.facebook.com/me?fields=id,name,email",
        "EmailUrl": null
      }
    }
  }
}

Configure your app at Facebook Developers. See Facebook Login documentation.

Provider Settings Reference

Each provider has the same configuration options:

Setting	Type	Description
Enabled	bool	Enable this provider.
ClientId	string	OAuth client ID from the provider.
ClientSecret	string	OAuth client secret from the provider.
AuthUrl	string	Authorization URL with placeholders: {0} = client ID, {1} = redirect URI, {2} = state.
TokenUrl	string	Token exchange URL.
InfoUrl	string	User info URL.
EmailUrl	string	Email URL (some providers require separate request).

Complete Example

Here's a complete authentication configuration with cookie auth and Google OAuth:

{
  "Auth": {
    "CookieAuth": true,
    "CookieValidDays": 30,
    "CookieHttpOnly": true,
    "CookieMultiSessions": false,

    "BearerTokenAuth": false,

    "External": {
      "Enabled": true,
      "ReturnToPath": "/dashboard",
      "LoginCommand": "select * from external_login($1, $2, $3, $4, $5)",

      "Google": {
        "Enabled": true,
        "ClientId": "{GOOGLE_CLIENT_ID}",
        "ClientSecret": "{GOOGLE_CLIENT_SECRET}"
      },

      "GitHub": {
        "Enabled": true,
        "ClientId": "{GITHUB_CLIENT_ID}",
        "ClientSecret": "{GITHUB_CLIENT_SECRET}"
      }
    }
  }
}

Related

• authorize annotation - Require authentication on endpoints
• allow_anonymous annotation - Allow unauthenticated access
• login annotation - Mark endpoint as sign-in
• logout annotation - Mark endpoint as sign-out
• Comment Annotations Guide - How annotations work
• Configuration Guide - How configuration works

Next Steps

• Connection Settings - Configure database connections
• Server & SSL - Configure HTTPS and Kestrel web server