Skip to content
Kong Docs are moving soon! Our docs are migrating to a new home. You'll be automatically redirected to the new site in the future. In the meantime, view this page on the new site!
Kong Logo | Kong Docs Logo
  • Docs
    • Explore the API Specs
      View all API Specs View all API Specs View all API Specs arrow image
    • Documentation
      API Specs
      Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong AI Gateway
      Multi-LLM AI Gateway for GenAI infrastructure
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      AI's icon
      AI
      Govern, secure, and control AI traffic with multi-LLM AI Gateway plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Gateway
2.8.x LTS
  • Home icon
  • Kong Gateway
  • Configure
  • Auth
  • OpenID Connect with Amazon Cognito
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Kong AI Gateway
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.10.x (latest)
  • 3.9.x
  • 3.8.x
  • 3.7.x
  • 3.6.x
  • 3.5.x
  • 3.4.x (LTS)
  • 3.3.x
  • 2.8.x (LTS)
  • Archive (3.0.x and pre-2.8.x)
  • Introduction
    • Overview of Kong Gateway
    • Version Support Policy
    • Stages of Software Availability
    • Changelog
  • Install and Run
    • Overview
    • Kubernetes
    • Helm
    • OpenShift with Helm
    • Docker
    • Amazon Linux
    • CentOS
    • Debian
    • RHEL
    • Ubuntu
    • Migrating from OSS to EE
    • Upgrade Kong Gateway
    • Upgrade Kong Gateway OSS
    • Upgrade from 2.8 LTS to 3.4 LTS
  • Get Started
    • Quickstart Guide
      • Configuring a Service
      • Configuring a gRPC Service
      • Enabling Plugins
      • Adding Consumers
    • Comprehensive Guide
      • Prepare to Administer
      • Expose your Services
      • Protect your Services
      • Improve Performance
      • Secure Services
      • Set Up Intelligent Load Balancing
      • Manage Administrative Teams
      • Publish, Locate, and Consume Services
  • Plan and Deploy
    • Running Kong as a Non-Root User
    • Resource Sizing Guidelines
    • Hybrid Mode
      • Deploy Kong Gateway in Hybrid Mode
    • Kubernetes Deployment Options
    • Control Kong Gateway through systemd
    • Performance Testing Framework
    • DNS Considerations
    • Default Ports
    • Licenses
      • Access Your License
      • Deploy Your License
      • Monitor License Usage
    • Security
      • Start Kong Gateway Securely
      • Keyring and Data Encryption
      • Kong Security Update Process
      • Secrets Management
        • Getting Started
        • Advanced Usage
        • Backends
          • Environment Variables
          • AWS Secrets Manager
          • GCP Secret Manager
          • HashiCorp Vault
        • Reference Format
  • Configure
    • Authentication and Authorization
      • Authentication Reference
      • OpenID Connect Plugin
        • OpenID Connect with Curity
        • OpenID Connect with Azure AD
        • OpenID Connect with Google
        • OpenID Connect with Okta
        • OpenID Connect with Auth0
        • OpenID Connect with Cognito
        • OpenID Connect Plugin Reference
      • Allowing Multiple Authentication Methods
      • Auth for Kong Manager
        • Create a Super Admin
        • Configure Networking
        • Configure Kong Manager to Send Email
        • Reset Passwords and RBAC Tokens
        • Configure Workspaces
        • Basic Auth
        • LDAP
        • OIDC
        • Sessions
      • Role-based Access Control (RBAC)
        • Add a Role
        • Add a User
        • Add an Admin
      • Mapping LDAP Service Directory Groups to Kong Roles
    • Configure gRPC Plugins
    • GraphQL Quickstart
    • Logging Reference
    • Network and Firewall
  • Dev Portal
    • Overview
    • Enable the Dev Portal
    • Structure and File Types
    • Portal API Documentation
    • Working with Templates
    • Using the Editor
    • Configuration
      • Authentication
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
      • SMTP
      • Workspaces
    • Administration
      • Manage Developers
      • Developer Roles and Content Permissions
      • Application Registration
        • Authorization Provider Strategy
        • Enable Application Registration
        • Enable Key Authentication for Application Registration
        • External OAuth2 Support
        • Set up Okta and Kong for external OAuth
        • Set Up Azure AD and Kong for External Authentication
        • Manage Applications
    • Customization
      • Easy Theme Editing
      • Migrating Templates Between Workspaces
      • Markdown Rendering Module
      • Customizing Portal Emails
      • Adding and Using JavaScript Assets
      • Single Page App in Dev Portal
      • Alternate OpenAPI Renderer
    • Helpers CLI
  • Monitor
    • Kong Vitals
      • Metrics
      • Reports
      • Vitals with InfluxDB
      • Vitals with Prometheus
      • Estimate Vitals Storage in PostgreSQL
    • Prometheus plugin
    • Zipkin plugin
  • Reference
    • Admin API
      • DB-less Mode
      • Declarative Configuration
      • Supported Content Types
      • Information Routes
      • Health Routes
      • Tags
      • Service Object
      • Route Object
      • Consumer Object
      • Plugin Object
      • Certificate Object
      • CA Certificate Object
      • SNI Object
      • Upstream Object
      • Target Object
      • Vaults Beta
      • Licenses
        • Licenses Reference
        • Licenses Examples
      • Workspaces
        • Workspaces Reference
        • Workspace Examples
      • RBAC
        • RBAC Reference
        • RBAC Examples
      • Admins
        • API Reference
        • Examples
      • Developers
      • Consumer Groups
        • API Reference
        • Examples
      • Event Hooks
        • Event Hooks Reference
        • Examples
      • Audit Logging
      • Keyring and Data Encryption
      • Securing the Admin API
    • DB-less and Declarative Configuration
    • Configuration Reference
    • CLI Reference
    • Load Balancing Reference
    • Proxy Reference
    • Rate Limiting Library
    • Health Checks and Circuit Breakers Reference
    • Clustering Reference
    • Plugin Development Kit
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.vault
    • Plugin Development Guide
      • Introduction
      • File structure
      • Implementing custom logic
      • Plugin configuration
      • Accessing the datastore
      • Storing custom entities
      • Caching custom entities
      • Extending the Admin API
      • Writing tests
      • (un)Installing your plugin
    • Plugins in Other Languages
    • File Permissions Reference
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Amazon Cognito Configuration
  • Application Definition
  • OIDC Plugin Configuration
  • Validating the Flows
  • Dev Portal Integration
You are browsing documentation for an older version. See the latest documentation here.

OpenID Connect with Amazon Cognito

Amazon Cognito Configuration

Amazon Cognito has two significant components: Identity Pools and User Pools. Identity Pools are the original functionality deployed in 2014; they mainly use proprietary AWS interfaces and libraries to accomplish the task of authenticating users. Furthermore, Identity Pools have no concept of claims (standard or custom) stored in the system; it is entirely a federated identity construct. User Pools are the more recent addition to the Cognito feature set; User Pools are a multi-tenant LDAP-like user repository combined with an OAuth2 and an OpenID Connect interface.

In this configuration, we use User Pools.

  1. Log in to AWS Console.
  2. Navigate to the Amazon Cognito Service.

  3. Click on Manage User Pools.

  4. Click the Create a user pool button on the right-hand side.

  5. Enter a pool name; we use “test-pool” for this example.

  6. Click Step Through Settings.

  7. Select Email address or phone number, and under that, select Allow email addresses. Select the following standard attributes as required: email, family name, given name.

  8. Click Next step.
  9. Accept the defaults for Password settings, then click Next step.
  10. Accept the defaults for MFA and verifications, then click Next step.
  11. Accept the defaults for Message customizations, click Next step.
  12. On the next screen, we are not going to create any tags. Click Next step.
  13. Select No for Do you want to remember your user’s devices, then click Next step.
  14. We can create an application definition later. Keep things simple for now and click Next step.
  15. We don’t have any need for Triggers or customized Sign Up/Sign In behavior for this example. Scroll down and click Save Changes.

  16. Click Create pool. Wait a moment for the success message.
  17. Make a note of the Pool ID. You will need this when configuring the application later.

Application Definition

You need to add an OAuth2 application definition to the User Pool we just created.

  1. Go to the App clients screen in the AWS Cognito management screen for the User Pool we just created.

  2. Click “Add an app client”.

  3. Enter an App client name. This demo is using “kong-api”.

  4. Enter a Refresh token expiration (in days). We will use the default of 30 days.
  5. Do not select “Generate client secret”. This example will use a public client.

  6. Do not select any other checkboxes.

  7. Click the “Set attribute read and write permissions” button.

  8. Let’s make this simple and only give the user read and write access to the required attributes. So, uncheck everything except the email, given name, and family name fields.

  9. Click “Create app client”.

  10. Click “Show Details”.

  11. Take note of the App client ID. We will need that later.
  12. Go to the App integration -> App client settings screen.
  13. Click the “Cognito User Pool” checkbox under Enabled Identity Providers.
  14. Add the following to the Callback URLs field:

     “https://kong-ee:8446/default, https://kong-ee:8447/default/, https://kong-ee:8447/default/auth, https://kong-ee:8443/cognito”
    

    Note that AWS Cognito doesn’t support HTTP callback URLs. This field should include the API and Dev Portal URLs that you want to secure using AWS Cognito.

  15. Click the “Authorization code grant” checkbox under Allowed OAuth Flows.
  16. Click the checkboxes next to email, OpenID, aws.cognito.signin.user.admin, and profile.
  17. Click the “Save changes” button.
  18. Click on the domain name tab.
  19. Add a sub-domain name.
  20. Click the Check Availability button.
  21. As long as it reports “This domain is available”, the name you have chosen will work.
  22. Click the “Save changes” button.

Now that you have created an Amazon Cognito User Pool and Application Definition, we can configure the OpenID Connect plugin in Kong. We can then test integration between Dev Portal and Amazon Cognito.

Amazon’s OIDC discovery endpoint is available from:

https://cognito-idp.<REGION>.amazonaws.com/<USER-POOL-ID>

For example, in this demo, the OIDC discovery endpoint is:

https://cognito-idp.ap-southeast-1.amazonaws.com/ap-southeast-1_ie577myCv/.well-known/openid-configuration

The OAuth + OIDC debugger is a handy utility that you may use to test the authorization flow before configurations in Kong.

OIDC Plugin Configuration

Identify the Route or Service to be secured. In our example, we created a new route called /cognito to which we added the OpenID Connect plug-in.
The number of options in the plug-in can seem overwhelming but the configuration is rather simple. All you need to do is configure:

  • issuer - You can use the OIDC discovery endpoint here, e.g.
      https://cognito-idp.ap-southeast-1.amazonaws.com/ap-southeast-1_ie577myCv/.well-known/openid-configuration
    
  • config.client_id - This is the client ID noted when the application was created
  • config.client_secret - This is the client secret noted when the application was created. In this demo we are leaving this blank as we didn’t create a client secret.
  • config.auth_methods - If this is left blank, all flows will be enabled. If only specific flows are in scope, configure the appropriate flows accordingly.

Validating the Flows

You can test the route by accessing URL “https://kong-ee:8443/cognito/anything”, and you should redirect to the Amazon Cognito login page. You need to click “Sign up” link to create a user first using your email address. The application sends a verification code to your email. Once you enter the verification code, Amazon Cognito acknowledges the account.

You can verify the confirmed user from the Cognito page under “General settings” -> “Users and groups”.

Dev Portal Integration

Important: The settings below are intended for non-production use only, as they override the default admin_listen setting to listen for requests from any source. Do not use these settings in environments directly exposed to the internet.


If you need to expose the admin_listen port to the internet in a production environment, secure it with authentication.

Since AWS Cognito only supports the HTTPS protocol, when you start Kong Gateway, ensure that HTTPS protocol for Dev Portal is enabled. For example:

docker run -d --name kong-ee --link kong-ee-database:kong-ee-database \
  -e "KONG_DATABASE=postgres" \
  -e "KONG_PG_HOST=kong-ee-database" \
  -e "KONG_CASSANDRA_CONTACT_POINTS=kong-ee-database" \
  -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
  -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
  -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_LISTEN=0.0.0.0:8001 , 0.0.0.0:8444 ssl" \
  -e "KONG_PORTAL=on" \
  -e "KONG_ENFORCE_RBAC=off" \
  -e "KONG_ADMIN_GUI_URL=http://kong-ee:8002" \
  -e "KONG_AUDIT_LOG=on" \
  -e "KONG_PORTAL_GUI_PROTOCOL=https" \
  -e "KONG_PORTAL_GUI_HOST=kong-ee:8446" \
  -e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \
  -p 8000-8004:8000-8004 \
  -p 8443-8447:8443-8447 \
  kong-ee

Under Dev Portal settings, select “Open ID Connect” as the authentication plugin.

Copy and paste the following Auth Config JSON object:

{
    "leeway": 100,
    "consumer_by": [
        "username",
        "custom_id",
        "id"
    ],
    "scopes": [
        "openid",
        "profile",
        "email"
    ],
    "logout_query_arg": "logout",
    "client_id": [
        "1pf00c5or942c2hm37mgv0u509"
    ],
    "login_action": "redirect",
    "logout_redirect_uri": [
        "https://kongdemo.auth.ap-southeast-1.amazoncognito.com/logout?client_id=1pf00c5or942c2hm37mgv0u509&logout_uri=kong-ee:8446/default"
    ],
    "login_tokens": {},
    "login_redirect_uri": [
        "https://kong-ee:8446/default"
    ],
    "forbidden_redirect_uri": [
        "https://kong-ee:8446/default/unauthorized"
    ],
    "ssl_verify": false,
    "issuer": "https://cognito-idp.ap-southeast-1.amazonaws.com/ap-southeast-1_ie577myCv/.well-known/openid-configuration",
    "logout_methods": [
        "GET"
    ],
    "consumer_claim": [
        "email"
    ],
    "login_redirect_mode": "query",
    "redirect_uri": [
        "https://kong-ee:8447/default/auth"
    ]
}

To log out the user completely, we need to use the logout endpoint provided by Cognito (https://docs.aws.amazon.com/cognito/latest/developerguide/logout-endpoint.html). Therefore, in the above configuration, we have passed in Cognito logout endpoint of logout redirect URL.

Please also note that the developer signed up from Dev Portal doesn’t get created in Cognito automatically. Therefore, developer sign-up is a two-step process:

  • The developer signs up from Dev Portal itself, so a Kong Admin needs to approve the developer access.
  • The developer signs up from Amazon Cognito. Please make sure that you use the same email address for both sign-ups. Now you should be able to login to Developer Portal using the Amazon Cognito user and credential.
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    Powering the API world

    Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller.

    • Products
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • Product Updates
      • Get Started
    • Documentation
      • Kong Konnect Docs
      • Kong Gateway Docs
      • Kong Mesh Docs
      • Kong Insomnia Docs
      • Kong Konnect Plugin Hub
    • Open Source
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kong Community
    • Company
      • About Kong
      • Customers
      • Careers
      • Press
      • Events
      • Contact
  • Terms• Privacy• Trust and Compliance
© Kong Inc. 2025