ALB Auth


1. Important Points#

ALB Auth 可以在请求进入应用前完成 Cognito 或 OIDC 登录。它适合保护 admin、internal tools、低代码后台、临时运营页面，不适合替代完整应用权限系统。

ALB Auth 适合:
    admin web UI
    internal dashboard
    low-volume operations tool
    legacy app without built-in login
    path-based protection, for example /admin/*

ALB Auth 不适合:
    complex app-level RBAC
    fine-grained object permission
    API token authorization
    multi-tenant business authorization
    mobile-native auth flow as primary design

Core behavior:

listener rule:
    condition matches request
    authenticate-cognito or authenticate-oidc action runs first
    forward action runs after authentication succeeds

application receives:
    x-amzn-oidc-accesstoken
    x-amzn-oidc-identity
    x-amzn-oidc-data

2. Auth Patterns#

Pattern Use Case Notes
Cognito user pool AWS-native login for internal app simplest AWS-managed option
OIDC IdP Okta/Auth0/Keycloak/Entra ID use existing enterprise identity
Auth only on /admin/* public app plus protected admin path path rule priority matters
Auth on separate host admin.example.com cleaner cookie/session boundary
App validates ALB headers defense in depth app should only trust traffic from ALB 
recommended:
    separate host for admin:
        admin.example.com

    listener rule:
        host-header = admin.example.com
        authenticate
        forward to admin target group

    security:
        target security group only accepts ALB security group
        app trusts x-amzn-oidc-* only from ALB path

3. Cognito Auth#

Listener rule with Cognito authentication:

[
  {
    "Type": "authenticate-cognito",
    "AuthenticateCognitoConfig": {
      "UserPoolArn": "arn:aws:cognito-idp:ap-east-1:111122223333:userpool/ap-east-1_example",
      "UserPoolClientId": "exampleclientid",
      "UserPoolDomain": "prod-admin-auth",
      "SessionCookieName": "AWSELBAuthSessionCookie",
      "Scope": "openid profile email",
      "SessionTimeout": 604800,
      "OnUnauthenticatedRequest": "authenticate"
    },
    "Order": 1
  },
  {
    "Type": "forward",
    "TargetGroupArn": "arn:aws:elasticloadbalancing:ap-east-1:111122223333:targetgroup/prod-admin/abc123",
    "Order": 2
  }
]

Create listener rule:

aws elbv2 create-rule \
  --listener-arn arn:aws:elasticloadbalancing:ap-east-1:111122223333:listener/app/prod-public-alb/abc123/listener123 \
  --priority 10 \
  --conditions Field=host-header,Values=admin.example.com \
  --actions file://alb-cognito-actions.json \
  --region ap-east-1

Cognito checklist:

user pool:
    app client created
    app client has no client secret when required by ALB flow
    callback URL points to ALB OAuth2 callback path
    logout URL configured if needed
    domain configured

ALB:
    HTTPS listener required
    authenticate action before forward action
    session timeout reviewed
    unauthenticated behavior selected

4. OIDC Auth#

Listener rule with OIDC authentication:

[
  {
    "Type": "authenticate-oidc",
    "AuthenticateOidcConfig": {
      "Issuer": "https://idp.example.com/oauth2/default",
      "AuthorizationEndpoint": "https://idp.example.com/oauth2/default/v1/authorize",
      "TokenEndpoint": "https://idp.example.com/oauth2/default/v1/token",
      "UserInfoEndpoint": "https://idp.example.com/oauth2/default/v1/userinfo",
      "ClientId": "alb-admin-client",
      "ClientSecret": "replace-with-secret-from-secure-store",
      "SessionCookieName": "AWSELBAuthSessionCookie",
      "Scope": "openid profile email",
      "SessionTimeout": 604800,
      "OnUnauthenticatedRequest": "authenticate"
    },
    "Order": 1
  },
  {
    "Type": "forward",
    "TargetGroupArn": "arn:aws:elasticloadbalancing:ap-east-1:111122223333:targetgroup/prod-admin/abc123",
    "Order": 2
  }
]

Create rule:

aws elbv2 create-rule \
  --listener-arn arn:aws:elasticloadbalancing:ap-east-1:111122223333:listener/app/prod-public-alb/abc123/listener123 \
  --priority 20 \
  --conditions Field=path-pattern,Values='/admin/*' \
  --actions file://alb-oidc-actions.json \
  --region ap-east-1

Security note:

do not commit OIDC client secret:
    generate action JSON from CI secret store
    use temporary file during deploy
    delete file after create-rule / modify-rule

5. Application Header Handling#

ALB sends identity context to target after authentication.

headers:
    x-amzn-oidc-accesstoken:
        access token from IdP

    x-amzn-oidc-identity:
        subject / user identity

    x-amzn-oidc-data:
        user claims encoded by ALB

Application rule:

trust boundary:
    only trust x-amzn-oidc-* if request comes from ALB
    target security group must only allow ALB security group
    do not allow direct public access to target

authorization:
    ALB Auth proves login
    app still decides role / permission when needed

Example app-side checks:

admin page:
    require x-amzn-oidc-identity exists
    map user email/group to app role
    log user identity in audit log

API:
    prefer app-native JWT validation or API Gateway/Lambda authorizer
    use ALB Auth only when browser redirect flow makes sense

6. OnUnauthenticatedRequest#

Value Behavior Use Case
authenticate redirect user to IdP normal browser login
deny return 401 non-browser clients or strict admin path
allow forward unauthenticated request mixed public/private app logic

Production default:

admin / internal page:
    authenticate

API endpoint:
    deny, or do not use ALB Auth

public page with optional login:
    allow only when app handles anonymous state correctly

7. Operations#

Modify rule:

aws elbv2 modify-rule \
  --rule-arn arn:aws:elasticloadbalancing:ap-east-1:111122223333:listener-rule/app/prod-public-alb/abc123/listener123/rule123 \
  --conditions Field=host-header,Values=admin.example.com \
  --actions file://alb-cognito-actions.json \
  --region ap-east-1

List rules:

aws elbv2 describe-rules \
  --listener-arn arn:aws:elasticloadbalancing:ap-east-1:111122223333:listener/app/prod-public-alb/abc123/listener123 \
  --region ap-east-1 \
  --query 'Rules[*].[Priority,Conditions,Actions[*].Type,RuleArn]' \
  --output table

Troubleshooting:

redirect loop:
    check callback URL
    check host header
    check HTTPS listener
    check IdP allowed redirect URI

401 / auth failure:
    check client id / secret
    check issuer and endpoints
    check scope
    check IdP app assignment

app missing user:
    inspect x-amzn-oidc-* headers
    check whether request matched authenticate rule
    confirm target is not directly exposed

8. Production Checklist#

listener:
    HTTPS only for auth rule
    auth action order before forward action
    rule priority documented
    default action does not bypass auth

identity:
    Cognito/OIDC client configured
    redirect/callback URL correct
    session timeout reviewed
    logout behavior documented

security:
    target not public
    target SG only allows ALB SG
    app does not blindly trust spoofed headers from non-ALB path
    OIDC client secret stored in secret manager / CI secret store

operations:
    rule config is reproducible by CLI/IaC
    auth failures visible in logs
    break-glass access exists for admin tool
Backward ALB Monitoring
ALB Security Forward