{"id":15779820,"url":"https://github.com/rgl/terraform-aws-cognito-example","last_synced_at":"2026-05-14T20:32:36.419Z","repository":{"id":233227507,"uuid":"786327602","full_name":"rgl/terraform-aws-cognito-example","owner":"rgl","description":"Example OIDC and OAuth authentication and authorization with Amazon Cognito IdP, Amazon API Gateway, and AWS Lambda Function","archived":false,"fork":false,"pushed_at":"2024-04-14T05:34:30.000Z","size":54,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-13T08:42:39.506Z","etag":null,"topics":["api-gateway","aws","aws-api-gateway","aws-cognito","aws-lambda","cognito","oauth","oauth2","oidc"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rgl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-14T05:32:16.000Z","updated_at":"2025-04-22T21:01:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"a135a4f2-7226-47b6-bd95-e220e5014de9","html_url":"https://github.com/rgl/terraform-aws-cognito-example","commit_stats":null,"previous_names":["rgl/terraform-aws-cognito-example"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rgl/terraform-aws-cognito-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fterraform-aws-cognito-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fterraform-aws-cognito-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fterraform-aws-cognito-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fterraform-aws-cognito-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rgl","download_url":"https://codeload.github.com/rgl/terraform-aws-cognito-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgl%2Fterraform-aws-cognito-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33042158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","aws","aws-api-gateway","aws-cognito","aws-lambda","cognito","oauth","oauth2","oidc"],"created_at":"2024-10-04T18:21:35.065Z","updated_at":"2026-05-14T20:32:36.400Z","avatar_url":"https://github.com/rgl.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# About\n\n[![Lint](https://github.com/rgl/terraform-aws-cognito-example/actions/workflows/lint.yml/badge.svg)](https://github.com/rgl/terraform-aws-cognito-example/actions/workflows/lint.yml)\n\nThis deploys an example [Amazon Cognito IdP](https://aws.amazon.com/cognito/), [Amazon API Gateway](https://aws.amazon.com/api-gateway/), and [AWS Lambda Function](https://aws.amazon.com/lambda/).\n\nThe following components are used:\n\n![components](components.png)\n\nThis will:\n\n* Use the [Amazon Cognito IdP Service](https://aws.amazon.com/cognito/).\n  * Create a Cognito User Pool.\n  * Create a Cognito User Pool Resource Server.\n  * Create a Cognito User Pool Domain.\n  * Create a Cognito User Pool User.\n  * Create a Cognito User Pool Client for the [OAuth 2.0 Client Credentials Grant Type](https://oauth.net/2/grant-types/client-credentials/).\n  * Create a Cognito User Pool Client for the [OAuth 2.0 Authorization Code Grant Type](https://oauth.net/2/grant-types/authorization-code/).\n* Build an example Go AWS Lambda Function as a Container Image.\n  * Implement a OAuth 2.0 Resource Server.\n    * Validate the token created by a OAuth 2.0 Client Credentials Grant Type Client.\n    * Validate the token created by a OAuth 2.0 Authorization Code Grant Type Client.\n      * With [Proof Key for Code Exchange (PKCE)](https://oauth.net/2/pkce/).\n  * Upload it to the [Amazon ECR](https://aws.amazon.com/ecr/).\n* Create an [Amazon API Gateway](https://aws.amazon.com/api-gateway/).\n  * Configure it to use the Go AWS Lambda Function.\n  * Configure a route to require JWT authorization.\n\n# Usage (on a Ubuntu Desktop)\n\nInstall the dependencies:\n\n* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).\n* [Terraform](https://www.terraform.io/downloads.html).\n* [Docker](https://docs.docker.com/engine/install/).\n\nSet the AWS Account credentials using SSO:\n\n```bash\n# set the environment variables to use a specific profile.\n# e.g. use the pattern \u003caws-sso-session-name\u003e-\u003caws-account-name\u003e-\u003caws-account-role\u003e-\u003caws-account-id\u003e\nexport AWS_PROFILE=example-dev-AdministratorAccess-123456\nunset AWS_ACCESS_KEY_ID\nunset AWS_SECRET_ACCESS_KEY\nunset AWS_DEFAULT_REGION\n# set the account credentials.\n# see https://docs.aws.amazon.com/cli/latest/userguide/sso-configure-profile-token.html#sso-configure-profile-token-auto-sso\naws configure sso\n# dump the configured profile and sso-session.\ncat ~/.aws/config\n# show the user, user amazon resource name (arn), and the account id, of the\n# profile set in the AWS_PROFILE environment variable.\naws sts get-caller-identity\n```\n\nOr, set the AWS Account credentials using an Access Key:\n\n```bash\n# set the account credentials.\n# NB get these from your aws account iam console.\n#    see Managing access keys (console) at\n#        https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey\nexport AWS_ACCESS_KEY_ID='TODO'\nexport AWS_SECRET_ACCESS_KEY='TODO'\nunset AWS_PROFILE\n# set the default region.\nexport AWS_DEFAULT_REGION='eu-west-1'\n# show the user, user amazon resource name (arn), and the account id.\naws sts get-caller-identity\n```\n\nReview the [`inputs.tf`](inputs.tf) file.\n\nInitialize the project:\n\n```bash\nterraform init -lockfile=readonly\n```\n\nDeploy the example:\n\n```bash\nterraform apply\n```\n\nShow the terraform state:\n\n```bash\nterraform state list\nterraform show\n```\n\nGet an authorization token using the OAuth 2.0 Client Credentials Grant:\n\n```bash\ntoken_url=\"$(terraform output --raw oidc_token_url)\"\njwks_url=\"$(terraform output --raw oidc_jwks_url)\"\nuserinfo_url=\"$(terraform output --raw oidc_userinfo_url)\"\nclient_id=\"$(terraform output --raw example_client_id)\"\nclient_secret=\"$(terraform output --raw example_client_secret)\"\n# see https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html\ntoken_response=\"$(curl \\\n  -s \\\n  -X POST \\\n  -u \"$client_id:$client_secret\" \\\n  -d \"grant_type=client_credentials\u0026client_id=$client_id\u0026client_secret=$client_secret\" \\\n  \"$token_url\")\"\njq \u003c\u003c\u003c\"$token_response\"\n# NB In Cognito, this token is a JWT (as defined in the JSON Web Token (JWT)\n#    Profile for OAuth 2.0 Access Tokens at\n#    https://datatracker.ietf.org/doc/html/rfc9068).\n# NB Cognito does not let us validate the a client credentials access token by\n#    calling the userinfo url (it requires the oidc scope; but client\n#    credentials clients cannot use that scope in Cognito). This means we must\n#    validate it using the keys available at the JWKS URL.\ntoken=\"$(jq -r .access_token \u003c\u003c\u003c\"$token_response\")\"\n# NB this will not work. its here just do show that it will not work.\n# NB the example service will validate the token using the JWKS, and will\n#    populate the response with the authorizationClaims property. see the\n#    source code in example/main.go.\ncurl \\\n  -s \\\n  -X GET \\\n  -H \"Authorization: Bearer $token\" \\\n  \"$userinfo_url\" \\\n  | jq\n```\n\nAccess the example service (hosted by the Go AWS Lambda Function Container),\nusing the token:\n\n```bash\nexample_url=\"$(terraform output --raw example_url)\"\ncurl \\\n  -s \\\n  -X GET \\\n  -H \"Authorization: Bearer $token\" \\\n  \"$example_url\" \\\n  | jq\n```\n\nThe authorization bearer token will be validated by the example service, and its claims will be returned in the `authorizationClaims` response property. It will returns something alike:\n\n```json\n{\n  \"authorizationClaims\": {\n    \"auth_time\": 1,\n    \"client_id\": \"6xxxxxxxxxxxxxxxxxxxxxxxx7\",\n    \"exp\": \"2024-04-10T07:12:09Z\",\n    \"iat\": \"2024-04-10T08:12:09Z\",\n    \"iss\": \"https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_xxxxxxxxxx\",\n    \"jti\": \"76543210-aaaa-bbbb-cccc-dddddddddddd\",\n    \"scope\": \"example/auth\",\n    \"sub\": \"6xxxxxxxxxxxxxxxxxxxxxxxx7\",\n    \"token_use\": \"access\",\n    \"version\": 2\n  }\n}\n```\n\nAccess the example service endpoint protected by the API Gateway, without, and with a token:\n\n```bash\nexample_url=\"$(terraform output --raw example_url)\"\n# without token.\n# NB this should fail with an Unauthorized error.\ncurl \\\n  -s \\\n  -X GET \\\n  \"$example_url/jwt-cognito-protected\" \\\n  | jq\n# with token.\n# NB this should succeed and you should see the claims, validated by the\n#    api gateway in the apiGatewayAuthorizationClaims response property.\ncurl \\\n  -s \\\n  -X GET \\\n  -H \"Authorization: Bearer $token\" \\\n  \"$example_url/jwt-cognito-protected\" \\\n  | jq\n```\n\nStart the OIDC Authorization Code Grant flow dance, and login as `alice:HeyH0Password!`:\n\n```bash\nexample_authorization_code_oidc_redirect_url=\"$(terraform output --raw example_authorization_code_oidc_redirect_url)\"\nxdg-open \"$example_authorization_code_oidc_redirect_url\"\n```\n\nAt the end of the dance, you should see the user claims, something like:\n\n```json\n{\n  \"iss\": \"https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_xxxxxxxxxx\",\n  \"sub\": \"c5e4ae65-7d41-4652-b9e0-6858b6446186\",\n  \"preferred_username\": \"alice\",\n  \"email\": \"alice@example.com\",\n  \"email_verified\": true,\n  \"name\": \"Alice Doe\",\n  \"given_name\": \"Alice\",\n  \"family_name\": \"Doe\"\n}\n```\n\nDestroy the example:\n\n```bash\nterraform destroy\n```\n\nList this repository dependencies (and which have newer versions):\n\n```bash\nGITHUB_COM_TOKEN='YOUR_GITHUB_PERSONAL_TOKEN' ./renovate.sh\n```\n\n# Notes\n\n* There is no way to rotate a `aws_cognito_user_pool_client` (aka app) client\n  secret. Instead, the client must be re-created.\n  * See the [App client types, Client secret documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html#user-pool-settings-client-app-client-types).\n\n# References\n\n* [Amazon Cognito Documentation](https://docs.aws.amazon.com/cognito/index.html).\n  * [OAuth 2.0, OpenID Connect, and SAML 2.0 federation endpoints reference](https://docs.aws.amazon.com/cognito/latest/developerguide/federation-endpoints.html).\n  * [Using PKCE in authorization code grants with Amazon Cognito user pools](https://docs.aws.amazon.com/cognito/latest/developerguide/using-pkce-in-authorization-code.html).\n  * [Amazon Cognito User Pools API Reference Documentation](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html).\n* [OAuth 2.0 Grant Types](https://oauth.net/2/grant-types/).\n  * [OAuth 2.0 Client Credentials Grant Type](https://oauth.net/2/grant-types/client-credentials/).\n  * [OAuth 2.0 Authorization Code Grant Type](https://oauth.net/2/grant-types/authorization-code/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frgl%2Fterraform-aws-cognito-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frgl%2Fterraform-aws-cognito-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frgl%2Fterraform-aws-cognito-example/lists"}