Authentication

Ingress supports multiple authentication methods to secure your backend services. You can configure authentication at the rule level or path level.

Supported Authentication Methods

Basic Authentication: Username/password authentication
Bearer Token: Token-based authentication
JWT: JSON Web Token authentication
OAuth2: OAuth 2.0 authentication
OIDC: OpenID Connect authentication

Enabling / Disabling Authentication

When you configure auth.type, authentication is enabled by default. You can use the enabled field to temporarily disable authentication (e.g. for debugging or gradual rollouts) without removing the auth configuration:

auth:
  enabled: false   # set to true to re-enable; omit to default to true when type is set
  type: basic
  basic:
    users:
      - username: admin
        password: admin123

`enabled` value	`type` set?	Behavior
(omitted)	No	No auth (default)
(omitted)	Yes	Auth enabled (default)
`true`	Any	Auth enabled
`false`	Any	Auth disabled (config preserved)

Basic Authentication

Basic Authentication uses username and password credentials.

Single User

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        auth:
          type: basic
          basic:
            users:
              - username: admin
                password: admin123

Multiple Users

You can configure multiple users for Basic Authentication:

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        auth:
          type: basic
          basic:
            users:
              - username: admin
                password: admin123
              - username: user1
                password: user123
              - username: user2
                password: user456

Using Basic Auth

Clients must include the Authorization header with base64-encoded credentials:

curl -u admin:admin123 http://example.com/api

Or manually:

curl -H "Authorization: Basic $(echo -n 'admin:admin123' | base64)" http://example.com/api

Bearer Token Authentication

Bearer Token authentication uses token-based authentication.

Single Token

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        auth:
          type: bearer
          bearer:
            tokens:
              - my-secret-token-123

Multiple Tokens

You can configure multiple valid tokens:

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        auth:
          type: bearer
          bearer:
            tokens:
              - token1-abc123xyz
              - token2-def456uvw
              - token3-ghi789rst

Using Bearer Token

Clients must include the Authorization header with the Bearer token:

curl -H "Authorization: Bearer my-secret-token-123" http://example.com/api

JWT Authentication

JWT (JSON Web Token) authentication validates JWT tokens using a secret key.

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        auth:
          type: jwt
          secret: your-secret-key

Using JWT

Clients must include a valid JWT token in the Authorization header:

curl -H "Authorization: Bearer <jwt-token>" http://example.com/api

OAuth2 Authentication

OAuth2 authentication enables a redirect-based login flow using third-party identity providers. When a user visits a protected route without a valid session, ingress redirects them to the provider's authorization page. After successful login, the provider redirects back to ingress, which stores the user session and forwards the request to the upstream service.

Supported Providers

Provider	Identifier
GitHub	`github`
GitLab	`gitlab`
Google	`google`
Microsoft	`microsoft`
Feishu (飞书)	`feishu`
Slack	`slack`
Kakao	`kakao`
Auth0	`auth0`
Okta	`okta`
Doreamon	`doreamon`

Basic Configuration

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        auth:
          type: oauth2
          oauth2:
            provider: github
            client_id: your-github-client-id
            client_secret: your-github-client-secret
            # scopes is optional — defaults are provider-specific
            scopes:
              - user:email

Required fields:

Field	Description
`type`	Must be `oauth2`
`oauth2.provider`	Identity provider name (see table above)
`oauth2.client_id`	OAuth application client ID
`oauth2.client_secret`	OAuth application client secret

Optional fields:

Field	Default	Description
`oauth2.scopes`	Provider-specific (see below)	OAuth scopes to request
`oauth2.redirect_url`	Auto-generated from request host	Custom callback URL

Default scopes per provider:

Provider	Default scopes
GitHub	`user:email`
GitLab	`read_user`
Google	`openid profile email`
Microsoft	`openid profile email`
Feishu	`user:email`
Slack	`users:read`
Auth0	`openid profile email`
Okta	`openid profile email`
Doreamon / Kakao	(provider default)

The callback path is always /oauth2/callback (fixed). The full redirect URL is auto-generated from the incoming request's scheme and host, e.g. http://example.com/oauth2/callback.

Connect JWT Headers

When connect.enabled is true, ingress injects user identity headers into the upstream request after successful OAuth2 authentication. This allows the backend service to identify the authenticated user without re-implementing the OAuth2 flow.

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        auth:
          type: oauth2
          oauth2:
            provider: github
            client_id: your-client-id
            client_secret: your-client-secret
            scopes:
              - user:email
            connect:
              enabled: true
              jwt:
                secret: your-shared-jwt-secret
                algorithm: hs256       # optional, default: hs256
                expires_in: "5m"       # optional, default: 5m

Injected headers:

Header	Description
`X-Connect-Token`	JWT containing `id`, `username`, `email`, `nickname`, `avatar`
`X-Connect-Timestamp`	Unix millisecond timestamp of token issuance

JWT decoding by the upstream (example in Go):

import "github.com/go-zoox/jwt"

token := r.Header.Get("X-Connect-Token")
j := jwt.New("your-shared-jwt-secret")
claims, err := j.Verify(token)
if err != nil {
    // invalid token
}
userID := claims.Get("id").String()

Authentication Flow

Client visits https://example.com/protected
Ingress detects no session → generates CSRF state → redirects to provider login
User authenticates with the provider
Provider redirects to https://example.com/oauth2/callback?code=xxx&state=yyy
Ingress validates state, exchanges code for token, fetches user info
User info is stored in an encrypted session cookie
Client is redirected back to the original URL (/protected)
On subsequent requests, the session cookie identifies the authenticated user
If connect.enabled: true, X-Connect-Token and X-Connect-Timestamp are injected into the upstream request

OIDC Authentication

OpenID Connect (OIDC) authentication extends OAuth2 with identity verification.

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        auth:
          type: oidc
          provider: google
          client_id: your-client-id
          client_secret: your-client-secret
          redirect_url: https://example.com/callback
          scopes:
            - openid
            - profile
            - email

Path-Level Authentication

You can configure different authentication methods for different paths:

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        auth:
          type: basic
          basic:
            users:
              - username: default
                password: default123
    paths:
      - path: /admin
        backend:
          service:
            name: admin-service
            port: 8080
            auth:
              type: basic
              basic:
                users:
                  - username: admin
                    password: admin123
                  - username: superadmin
                    password: super123
      - path: /api
        backend:
          service:
            name: api-service
            port: 8080
            auth:
              type: bearer
              bearer:
                tokens:
                  - api-token-1
                  - api-token-2
                  - api-token-3

In this example:

Requests to /admin require admin credentials
Requests to /api require a bearer token
All other requests use the default basic authentication

Authentication Flow

Client makes a request to Ingress
Ingress checks if authentication is required for the matched rule/path
If authentication is required:
- Ingress validates the credentials/token
- If valid, the request is forwarded to the backend
- If invalid, Ingress returns a 401 Unauthorized response
If no authentication is required, the request is forwarded directly

Security Best Practices

Use HTTPS: Always use SSL/TLS when authentication is enabled
Strong Passwords: Use strong, unique passwords for Basic Auth
Secure Tokens: Generate secure, random tokens for Bearer authentication
Token Rotation: Regularly rotate tokens and update configurations
Secret Management: Store secrets securely, avoid hardcoding in configuration files
Least Privilege: Grant minimum necessary access to users
Audit Logging: Monitor authentication attempts and failures

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Authentication

Supported Authentication Methods

Enabling / Disabling Authentication

Basic Authentication

Single User

Multiple Users

Using Basic Auth

Bearer Token Authentication

Single Token

Multiple Tokens

Using Bearer Token

JWT Authentication

Using JWT

OAuth2 Authentication

Supported Providers

Basic Configuration

Connect JWT Headers

Authentication Flow

OIDC Authentication

Path-Level Authentication

Authentication Flow

Security Best Practices

Troubleshooting

401 Unauthorized

Authentication Not Working

FilesExpand file tree

authentication.md

Latest commit

History

authentication.md

File metadata and controls

Authentication

Supported Authentication Methods

Enabling / Disabling Authentication

Basic Authentication

Single User

Multiple Users

Using Basic Auth

Bearer Token Authentication

Single Token

Multiple Tokens

Using Bearer Token

JWT Authentication

Using JWT

OAuth2 Authentication

Supported Providers

Basic Configuration

Connect JWT Headers

Authentication Flow

OIDC Authentication

Path-Level Authentication

Authentication Flow

Security Best Practices

Troubleshooting

401 Unauthorized

Authentication Not Working