{"id":13539998,"url":"https://github.com/squidfunk/terraform-aws-cognito-auth","last_synced_at":"2025-04-02T06:32:02.313Z","repository":{"id":33272811,"uuid":"135310772","full_name":"squidfunk/terraform-aws-cognito-auth","owner":"squidfunk","description":"[UNMAINTAINED] Serverless Authentication as a Service (AaaS) provider built on top of AWS Cognito","archived":true,"fork":false,"pushed_at":"2022-01-05T13:52:34.000Z","size":19378,"stargazers_count":294,"open_issues_count":0,"forks_count":61,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-03T05:30:20.501Z","etag":null,"topics":["aaas","authentication","aws","cognito","identity-provider","spa","terraform"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/squidfunk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"squidfunk"}},"created_at":"2018-05-29T14:45:43.000Z","updated_at":"2024-03-15T16:01:44.000Z","dependencies_parsed_at":"2022-08-07T20:17:34.559Z","dependency_job_id":null,"html_url":"https://github.com/squidfunk/terraform-aws-cognito-auth","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squidfunk%2Fterraform-aws-cognito-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squidfunk%2Fterraform-aws-cognito-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squidfunk%2Fterraform-aws-cognito-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squidfunk%2Fterraform-aws-cognito-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/squidfunk","download_url":"https://codeload.github.com/squidfunk/terraform-aws-cognito-auth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246768319,"owners_count":20830647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["aaas","authentication","aws","cognito","identity-provider","spa","terraform"],"created_at":"2024-08-01T09:01:36.995Z","updated_at":"2025-04-02T06:31:57.435Z","avatar_url":"https://github.com/squidfunk.png","language":"TypeScript","funding_links":["https://github.com/sponsors/squidfunk"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003e ⚠️ __UNMAINTAINED: I'm lacking the time to keep this project updated, which is\n\u003e why this project will not receive any further updates. Use it at your own\n\u003e risk. Issues have been disabled.__\n\n[![Github Action][action-image]][action-link]\n[![Codecov][codecov-image]][codecov-link]\n[![Gitter][gitter-image]][gitter-link]\n[![GitHub][github-image]][github-link]\n\n  [action-image]: https://github.com/squidfunk/terraform-aws-cognito-auth/workflows/ci/badge.svg?branch=master\n  [action-link]: https://github.com/squidfunk/terraform-aws-cognito-auth/actions\n  [codecov-image]: https://img.shields.io/codecov/c/github/squidfunk/terraform-aws-cognito-auth/master.svg\n  [codecov-link]: https://codecov.io/gh/squidfunk/terraform-aws-cognito-auth\n  [gitter-image]: https://badges.gitter.im/squidfunk/terraform-aws-cognito-auth.svg\n  [gitter-link]: https://gitter.im/squidfunk/terraform-aws-cognito-auth\n  [github-image]: https://img.shields.io/github/release/squidfunk/terraform-aws-cognito-auth.svg\n  [github-link]: https://github.com/squidfunk/terraform-aws-cognito-auth/releases\n\n# Terraform AWS Cognito Auth\n\n\u003e Add authentication to your Single Page Application (SPA) within minutes and\n\u003e take full control of the authentication flow including customizable email\n\u003e templates and a beautiful default UI. See the [live demo][1].\n\n  [1]: #live-demo\n\nA Terraform module to setup a serverless and easily customizable Authentication\nas a Service (AaaS) provider in front of API Gateway using AWS Cognito User\nPools.\n\n## Features\n\n* Authentication using email and password or refresh token\n* Registration, password reset and verification\n* Completely customizable transactional emails\n* Optional multi-part default email templates (see [screenshots][2])\n* Optional beautiful and mobile-friendly default UI (see [screenshots][3])\n* Federated identities using Cognito Identity Pools and User Pools\n* A+ security rating on [Mozilla Observatory][4] (CSP, HSTS, etc.)\n* Excessively tested with automated unit and acceptance tests\n* Serverless, extremely scalable and [cost effective][5]\n* However, there are some [limitations][6]\n\n  [2]: #emails\n  [3]: #default-ui-1\n  [4]: https://observatory.mozilla.org/analyze/terraform-aws-cognito-auth.play.squidfunk.com\n  [5]: #cost\n  [6]: #limitations\n\n## Architecture\n\n![Architecture][7]\n\n  [7]: assets/architecture.png\n\nThis module creates a REST API using AWS API Gateway, Lambda and Cognito User\nPools to enable registration, authentication and account recovery without the\nnecessity for the implementation of complex OAuth authentication flows. It was\noriginally inspired by [LambdAuth][8] but uses User Pools in favor of Identity\nPools because exposing (even temporary) AWS credentials is a security threat.\n\nAccount registration and recovery circumvent Cognito's default verification\nlogic and emit verification codes to an SNS topic which can be hooked up to a\nLambda function handling delivery via SES using default multi-part email\ntemplates. This behavior is optional and can be customized by implementing a\ncustom Lambda function handling email delivery. Furthermore, a beautiful and\nmobile-friendly default UI can be deployed to a custom subdomain within\nyour hosted zone.\n\n  [8]: https://github.com/danilop/LambdAuth\n\n### Cost\n\nAWS Cognito is [free for up to 50.000 monthly active users][9]. After that,\npricing starts at __$ 0,0055 per monthly active user__. Additional cost will be\nattributed to AWS Lambda, API Gateway and CloudFront but it should be very\nreasonable compared to what AaaS providers like Auth0 charge. While this module\ndoes not provide all features offered by other providers, it should be quite\nsufficient for securing a Single Page Application.\n\n  [9]: https://aws.amazon.com/de/cognito/pricing/\n\n## Usage\n\nAdd the following module to your Terraform configuration and apply it:\n\n``` hcl\nmodule \"cognito-auth\" {\n  source  = \"squidfunk/cognito-auth/aws\"\n  version = \"0.4.3\"\n\n  namespace                      = \"\u003cnamespace\u003e\"\n  region                         = \"\u003cregion\u003e\"\n  cognito_identity_pool_name     = \"\u003cpool-name\u003e\"\n  cognito_identity_pool_provider = \"\u003cpool-provider\u003e\"\n\n  # Optional: Default UI\n  app_hosted_zone_id             = \"\u003chosted-zone-id\u003e\"\n  app_certificate_arn            = \"\u003ccertificate-arn\u003e\"\n  app_domain                     = \"\u003cdomain\u003e\"\n  app_origin                     = \"\u003corigin-domain\u003e\"\n\n  # Optional: Email delivery\n  ses_sender_address             = \"\u003cemail\u003e\"\n}\n```\n\nAll resources are prefixed with the value specified as `namespace`. If the S3\nbucket name (see below) is not explicitly set, it's set to the given `namespace`\nwhich means there must not already exist an S3 bucket with the same name. This\nis a common source of error.\n\nThe `cognito_identity_pool_provider` should match the domain name under which\nthe authentication provider should be deployed, i.e. it should be equal to\n`app_domain`. Also note that SES is sandboxed by default, so every email address\nneeds to be verified for delivery. Contact AWS to [exit sandboxed mode][10] for\nproduction use.\n\nAlso see the [example][11] configuration and the [live demo][1].\n\n  [10]: https://docs.aws.amazon.com/ses/latest/DeveloperGuide/request-production-access.html\n  [11]: #example\n\n## Configuration\n\nThe following variables can be configured:\n\n### Required\n\n#### `namespace`\n\n- __Description__: AWS resource namespace/prefix (lowercase alphanumeric)\n- __Default__: `none`\n\n#### `region`\n\n- __Description__: AWS region\n- __Default__: `none`\n\n#### `api_stage`\n\n- __Description__: API deployment stage\n- __Default__: `\"production\"`\n\n#### `cognito_identity_pool_name`\n\n- __Description__: Cognito identity pool name\n- __Default__: `none`\n\n#### `cognito_identity_pool_provider`\n\n- __Description__: Cognito identity pool provider\n- __Default__: `none`\n\n### Optional\n\n#### Default UI\n\n##### `app_hosted_zone_id`\n\n- __Description__: Application hosted zone identifier\n- __Implies__: `app_certificate_arn`, `app_domain` and `app_origin`\n- __Default__: `\"\"`\n\n##### `app_certificate_arn`\n\n- __Description__: Application domain certificate ARN\n- __Implies__: `app_hosted_zone_id`, `app_domain` and `app_origin`\n- __Default__: `\"\"`\n\n##### `app_domain`\n\n- __Description__: Application domain\n- __Implies__: `app_hosted_zone_id`, `app_certificate_arn` and `app_origin`\n- __Default__: `\"\"`\n\n##### `app_origin`\n\n- __Description__: Application origin domain (target domain)\n- __Implies__: `app_hosted_zone_id`, `app_certificate_arn` and `app_domain`\n- __Default__: `\"\"`\n\n##### `bucket`\n\n- __Description__: S3 bucket name to store static files\n- __Default__: `\"${var.namespace}\"` (equal to namespace)\n\n#### Email delivery\n\n##### `ses_sender_address`\n\n- __Description__: SES sender email address\n- __Default__: `\"\"`\n\n## Example\n\nLet's say we want to secure an application hosted on `admin.example.com` using\nthe default UI. First, add the following lines to your Terraform configuration\nand apply it:\n\n``` hcl\nmodule \"cognito-auth\" {\n  source  = \"squidfunk/cognito-auth/aws\"\n  version = \"0.4.3\"\n\n  namespace                      = \"example-auth\"\n  region                         = \"us-east-1\"\n  cognito_identity_pool_name     = \"Example Auth\"\n  cognito_identity_pool_provider = \"login.example.com\"\n\n  # Optional: Default UI\n  app_hosted_zone_id             = \"Z*************\"\n  app_certificate_arn            = \"arn:aws:acm:us-east-1:...\"\n  app_domain                     = \"login.example.com\"\n  app_origin                     = \"admin.example.com\"\n\n  # Optional: Email delivery\n  ses_sender_address             = \"accounts@example.com\"\n}\n```\n\nNow, when the user visits `admin.example.com/dashboard`, the initial API request\nshould detect a `401 Unauthorized` response for an invalid or expired identity\ntoken and redirect to the default UI:\n\n```\nhttps://login.example.com/?redirect=dashboard\n```\n\nAfter successful authentication, the default UI will redirect to the URL\nspecified in `app_origin` appending the path part specified in the `redirect`\nparameter and the identity token in an URI fragment:\n\n```\nhttps://admin.example.com/dashboard#token=\u003ctoken\u003e\u0026expires=\u003ctimestamp\u003e\n```\n\nThen, after parsing the URI fragment and extracting the token, the application\ncan repeat the request including the identity token as an authorization header:\n\n```\nAuthorization: Bearer \u003ctoken\u003e\n```\n\nIf the user checks the __Remember me__ checkbox during the authentication\nprocess, a refresh token which is valid for 30 days is issued and sent to the\nclient as a secure HTTP-only cookie. When the access token expires after 1 hour,\nthe client is again redirected to the default UI which will immediately perform\na password-less authentication using the refresh token.\n\nTo sign out, the application must redirect the user to the following URL:\n\n```\nhttps://login.example.com/leave\n```\n\nThis will invalidate all tokens including the refresh token stored in the\nsecure HTTP-only cookie.\n\n## Demo\n\n### Live demo\n\nA live demo of this project can be found [here][12]. Please note that emails\nare configured to remain undelivered due to security reasons. If you want to\ntry authentication, you may use the following credentials:\n\n```\nUsername: jane.doe@example.com\nPassword: depl0y\u0026D3STROY\n```\n\nThe target domain is `localhost:8000`, so you can start a local development\nserver on that port in order to receive the identity token after a successful\nauthentication attempt.\n\n  [12]: https://terraform-aws-cognito-auth.play.squidfunk.com/\n\n### Screenshots\n\n#### Default UI\n\n\u003cimg src=\"assets/screenshots/authenticate.png\" width=\"45%\" /\u003e \u003cimg src=\"assets/screenshots/register-error.png\" width=\"45%\" /\u003e \u003cimg src=\"assets/screenshots/register-success.png\" width=\"45%\" /\u003e \u003cimg src=\"assets/screenshots/reset.png\" width=\"45%\" /\u003e\n\n#### Emails\n\n\u003cimg src=\"assets/screenshots/mail-activate.png\" width=\"45%\" /\u003e \u003cimg src=\"assets/screenshots/mail-unlock.png\" width=\"45%\" /\u003e\n\n## Limitations\n\nBy default, AWS Cognito does only allow minor customizations of the whole\nauthentication flow - specifically multi-part emails are not supported; welcome\nto the 21st century. To work around these restrictions registration and password\nreset were decoupled using the Cognito Identity Service Provider admin APIs.\nVerification is implemented with custom verification codes and email delivery.\n\n## License\n\n__MIT License__\n\nCopyright (c) 2018-2019 Martin Donath\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to\ndeal in the Software without restriction, including without limitation the\nrights to use, copy, modify, merge, publish, distribute, sublicense, and/or\nsell copies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\nIN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquidfunk%2Fterraform-aws-cognito-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsquidfunk%2Fterraform-aws-cognito-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquidfunk%2Fterraform-aws-cognito-auth/lists"}