{"id":18772082,"url":"https://github.com/christianrich/serverless-identity-access-management-api","last_synced_at":"2025-07-02T16:38:50.517Z","repository":{"id":63722177,"uuid":"558890040","full_name":"ChristianRich/serverless-identity-access-management-api","owner":"ChristianRich","description":"User Management \u0026 Authentication API (S2S) powered by AWS Cognito \u0026 DynamoDB","archived":false,"fork":false,"pushed_at":"2022-11-24T15:14:50.000Z","size":1420,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-21T01:14:34.315Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/ChristianRich.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}},"created_at":"2022-10-28T14:27:00.000Z","updated_at":"2024-12-08T14:13:36.000Z","dependencies_parsed_at":"2022-11-24T17:52:07.804Z","dependency_job_id":null,"html_url":"https://github.com/ChristianRich/serverless-identity-access-management-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ChristianRich/serverless-identity-access-management-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristianRich%2Fserverless-identity-access-management-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristianRich%2Fserverless-identity-access-management-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristianRich%2Fserverless-identity-access-management-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristianRich%2Fserverless-identity-access-management-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChristianRich","download_url":"https://codeload.github.com/ChristianRich/serverless-identity-access-management-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChristianRich%2Fserverless-identity-access-management-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260787332,"owners_count":23063093,"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":[],"created_at":"2024-11-07T19:27:42.324Z","updated_at":"2025-06-19T16:35:05.354Z","avatar_url":"https://github.com/ChristianRich.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serverless User Management \u0026 Authentication API\n\nOne-click deployment for secure user management, user registration, authentication and management of user profile data.\n\n## AWS resources\n\n- IAMs\n- API Gateway\n- Lambda\n- Cognito\n- DynamoDB\n- DynamoDB Streams\n- S3 (static assets)\n\n## Features\n\n- User management (DynamoDB)\n  - New user registration / sign-up\n  - Account activation\n  - Managing arbitrary user profile data via CRUD interface\n  - Automatically deploy static assets to a public S3 bucket (user avatar icons and badges (see `/assets`)\n- Auth server (Cognito)\n  - Authorization using credentials and access token flow\n  - Authentication using ID tokens\n  - 3 default Cognito user groups `USER`, `MODERATOR` and `ADMIN` (new registrations default to `USER`)\n\n## What's not included\n\n- Activation email flow\n- Password reset / forgot password / email flow\n- Social media login (supported by Cognito but out of scope for this project)\n\nFor email sending, this could be handled in a separate Lambda function listening for events (EventBridge) or use built-in email features in Cognito.\n\n## Prerequisites\n\n- AWS account with sufficient permissions\n- AWS Cognito User Pool and client (client name required for `serverless.yml`)\n- API key in AWS Secrets Manager e.g. `dev/user-api/api-key`\n- AWS CLI for localhost deployments\n\n## Required setup\n\nYou _must_ perform the following steps before running `sls deploy`:\n\n- Create API key in Secrets Manager and add key name to `serverless.yaml` \u003e `custom.apiKeys[0].value`\n- Create a Cognito User Pool and client and add the client name to `serverless.yaml` \u003e `custom.cognitoClientName`\n\n## Install dependencies\n\n```\nyarn\n```\n\n## Deploy\n\nSpin up the stack, and copy static assets in S3 bucket:\n\n```\nsls deploy\n```\n\n## Seed (TOODs)\n\nCreate 100 tests users\n\n```\nyarn seed:user\n```\n\n## Route table\n\n| Method   | Path                                     | Usage                                                                                                                                                   | Route type | ACL          |\n| :------- | :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------- | :----------- |\n| `GET`    | `/public/user/me`                        | Return user profile data for a valid access token. Useful for rendering a user's account page while letting Cognito implicitly handle the authorization | Public     | Bearer token |\n| `POST`   | `/auth/login`                            | Exchange credentials for an access token                                                                                                                | S2S        | API key      |\n| `GET`    | `/auth/token/{tokenType}/verify/{token}` | Verify token. Types = `access` or `id` (derived from Cognito)                                                                                           | S2S        | API key      |\n| `POST`   | `/user`                                  | Register new user                                                                                                                                       | S2S        | API key      |\n| `GET`    | `/user/id`                               | Get user by ID                                                                                                                                          |\n| `DELETE` | `/user/id`                               | Delete user by ID (hard delete)                                                                                                                         | S2S        | API key      |\n| `GET`    | `/user/name/{name}`                      | Get user by name (GSI)                                                                                                                                  | S2S        | API key      |\n| `GET`    | `/user/email/{email}`                    | Get user by email (GSI)                                                                                                                                 | S2S        | API key      |\n| `GET`    | `/user/handle/{handle}`                  | Get user by handle e.g `@SomePerson` (GSI)                                                                                                              | S2S        | API key      |\n| `GET`    | `/user/activate/{activationCode}`        | Activate user (changes status to `UserStatus.CONFIRMED` (GSI)                                                                                           | S2S        | API key      |\n| `PATCH`  | `/user/{id}/status/{status}`             | Update user status                                                                                                                                      | S2S        | API key      |\n| `PUT`    | `/user/{id}/data/update`                 | Fully update arbitrary user data blob (replace)                                                                                                         | S2S        | API key      |\n| `PATCH`  | `/user/{id}/data/update`                 | Partially update arbitrary user data blob (merge)                                                                                                       | S2S        | API key      |\n| `POST`   | `/user/{id}/badge/{name}`                | Issue badge to a user e.g `CONVERSATION_STARTER`                                                                                                        | S2S        | API key      |\n| `DELETE` | `/user/{id}/badge/{name}`                | Revoke user badge                                                                                                                                       | S2S        | API key      |\n\n## DynamoDB StreamEvents\n\nWhen new users are added to the Users table a stream event is dispatched which you can use to trigger an email sender Lambda function. Out of scope for this project - we're not building monoliths but decoupled micro-services :-)\n\n## User model\n\n```json\n{\n  \"id\": \"56e905d1-f721-4592-ad98-24fa0390c3ee\",\n  \"name\": \"clovis.wiegand\",\n  \"handle\": \"@ClovisWiegand\",\n  \"createdAt\": \"2022-11-24T13:41:37.634Z\",\n  \"lastLoginAt\": \"2022-11-24T13:42:36.188Z\",\n  \"email\": \"kassandra44@yahoo.com\",\n  \"role\": \"USER\",\n  \"status\": \"UNCONFIRMED\",\n  \"profile\": {\n    \"profileData\": {\n      \"lang\": \"en_us\",\n      \"avatarUrl\": \"https://s3.ap-southeast-2.amazonaws.com/dev.xxxxx/avatars/x256/01.png\",\n      \"currency\": \"USD\"\n    },\n    \"badges\": [\n      {\n        \"name\": \"NEW_MEMBER\",\n        \"iconUrl\": \"https://s3.ap-southeast-2.amazonaws.com/dev.xxxxx/badges/new-member.svg\"\n      }\n    ],\n    \"data\": {\n      \"unstructured\": \"data\",\n      \"title\": \"Profit-focused solution-oriented matrix\"\n    }\n  },\n  \"$devTest\": {\n    \"activationCode\": \"HfqbvY3046gpc7R0eGSMQ\"\n  }\n}\n```\n\n## Solutions architecture\n\nTBA\n\n## User table\n\nUser table sample view\n\n![Dynobase](./docs/images/dynobase.png)\n\n## TODO\n\n- Unit tests\n- Include Postman collection in `/docs/postman`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristianrich%2Fserverless-identity-access-management-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristianrich%2Fserverless-identity-access-management-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristianrich%2Fserverless-identity-access-management-api/lists"}