AWS Cognito (OIDC/JWT)

Use Amazon Cognito user pools as your OIDC/JWT identity provider. MAPS validates JWTs issued by your Cognito user pool and can (optionally) call AWS APIs for metadata when configured.

---

Configuration

1) AuthManager (global)

AuthManager:
  authenticationEnabled: true
  authorizationEnabled: false
  config:
    identityProvider: "cognito"
    userPoolId: "ap-southeast-2_XXXXXXX"  # Cognito User Pool ID
    appClientId: "YOUR_APP_CLIENT_ID"     # App client (user pool client) ID
    appClientSecret: "YOUR_APP_CLIENT_SECRET"  # If your app client uses a secret
    region: "ap-southeast-2"              # AWS region for the user pool
    accessKeyId: "{{AWS_ACCESS_KEY_ID}}"  # (Optional) for AWS API calls
    secretAccessKey: "{{AWS_SECRET_ACCESS_KEY}}" # (Optional) for AWS API calls
    cacheTime: 600000                     # ms to cache Cognito-derived results

For pure JWT validation you typically don’t need AWS API calls. Prefer IAM roles (EC2/ECS/EKS) over embedding access keys; use {{ENV_VAR}} style tokens if keys are unavoidable.

2) JAAS (jaasAuth.config)

JWTAuthConfig {
  io.mapsmessaging.security.jaas.AwsJwtLoginModule Required
    region="ap-southeast-2"
    poolId="ap-southeast-2_XXXXXXX"
    clientId="YOUR_APP_CLIENT_ID"
    clientSecret="YOUR_APP_CLIENT_SECRET"
    debug=false;
};

• The module validates JWTs from the specified user pool in the given region.
• If needed, JWKS resolves from: https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json.

3) SecurityManager mapping

SecurityManager:
  - public: JWTAuthConfig

4) Listener example

- name: "REST API (Cognito)"
  url: "http://0.0.0.0:8080/"
  protocol: rest
  auth: public

---

Field Reference

Key	Required	Description
cognito.userPoolId	Yes	User Pool ID (e.g., ap-southeast-2_XXXXXXX).
cognito.appClientId	Yes	App client ID in that user pool.
cognito.appClientSecret	No	Secret for the app client (only if your client uses one).
cognito.region	Yes	AWS region of the user pool (e.g., ap-southeast-2).
cognito.accessKeyId	No	Used if MAPS calls AWS APIs; prefer IAM roles instead.
cognito.secretAccessKey	No	Secret key for the above; prefer IAM roles instead.
cognito.cacheTime	No	Cache TTL (ms) for Cognito-derived lookups/metadata.

JWT validation relies on user-pool keys (JWKS). Management calls are optional and controlled by your deployment needs.

---

Notes & Best Practices

• Prefer RS256 tokens (Cognito default); MAPS validates via JWKS.
• Ensure tokens include the expected audience (your app client ID) and issuer (pool’s issuer URL).
• Avoid hard‑coding secrets. Use IAM roles or environment tokens ({{ENV_VAR}}).
• Tune cacheTime to balance freshness against API limits if lookups are enabled.

---

Troubleshooting

• Token rejected: verify region/pool ID, client ID, and that the token’s issuer matches the pool. Check system clock skew.
• Signature verification fails: ensure JWKS URL resolves and the token is RS256-signed.
• Unexpected 401 on REST: confirm the listener uses the public realm (or your chosen realm) and that aud claims match appClientId.