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 Gateway
2.8.x LTS
github-edit-pageEdit this page
report-issueReport an issue
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.