espuser/

directory
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 23, 2026 License: Apache-2.0

README ¶

Espressif user management

A comprehensive, secure, and scalable user management system that can be integrated with any Espressif product. It is designed to be used across regions and AWS accounts.

Table of Contents

Inputs from user

  • Default admin user email (can be changed later)

Resources

User
  • Cognito User Pool
  • A default root admin user
  • APIs:
    • User
      • Signup (Can there be a link for verification?)
      • Login (email/phone + password OR OTP based or SRP)
      • Forgot and change password
      • Update profile: locale, name, email, phone number, picture, preferences, custom data (can be set by each product)
      • Get user
      • MFA: enable, disable (TODO: required?)
      • Signout
      • Export/Email data
      • Delete account
      • Link accounts
      • Get active sessions, revoke session (session_id, created_at, last_used, ip_address, user_agent, current)
      • Publish events to be consumed by webhooks

TODO: Custom OAuth? TODO: Scope

Admin
  • Cognito User Pool
  • Cognito User Pool Clients for dashboard and admin cli - TODO: configurable?
  • Cognito User Pool Domain - TODO: required?
  • A default admin user
  • APIs:
    • Own account
      • Same as User
      • Change admin user
    • User accounts
      • User management CRUD (including search by tags, email, phone number, name, active users, created_at, ) (Includes cloud to cloud auth)
      • RBAC for admins
      • Admin editable custom data and tags per user
      • User session logs
      • Purge inactive users
      • User groups?
      • Aanlytics (active users, new users)
    • Configuration
      • Cognito domain CRUD for both pools (TODO: Required for admin pool?)
      • App clients CRUD for both pools (Clients for apps, dashboard, CLI, alexa and gva - TODO: configurable?)
      • Identity providers CRUD for user pool (Providers for google, apple, github, amazon, facebook, any other oidc provider)
      • Email/SMS templates CRUD
      • Email/SMS service logs
      • SES mail sender CRUD
    • Bulk user accounts
      • Import users with password
      • Bulk updates
      • Gradual migration: user validation and creation against an existing system

TODO: Sub admin

Privacy and security

  • PKCE for OAuth
  • Password policy
  • Data encryption
  • Data retention
  • Token expiration and rotation

Flags

Keep flags for notify, etc.

Outputs

  • API gateway URL
  • Admin Cognito OAuth ARN and URL
  • Admin Cognito user pool client Id and secret
  • User Cognito OAuth ARN and URL
  • User Cognito user pool client Id and secret

Directories ¶

Path Synopsis
Package auth - Admin authentication service for admin users
Package auth - Admin authentication service for admin users
Package clients is the ESP User OAuth-client service over espuser-oauth-clients: create, list, patch, delete, enforcing the client write-invariants.
Package clients is the ESP User OAuth-client service over espuser-oauth-clients: create, list, patch, delete, enforcing the client write-invariants.
db
admin_config_db
Table espuser-admin-config (PK config_name, SK subtype): admin-selected key-value config.
Table espuser-admin-config (PK config_name, SK subtype): admin-selected key-value config.
auth_flows_db
Table espuser-auth-flows (PK flow_id): the TTL'd browser authorization-code flow record, from /oauth2/authorize through OTP login to the issued code (resolved by the by-code GSI at token exchange).
Table espuser-auth-flows (PK flow_id): the TTL'd browser authorization-code flow record, from /oauth2/authorize through OTP login to the issued code (resolved by the by-code GSI at token exchange).
identity_providers_db
Table espuser-identity-providers: the upstream providers the federation broker may delegate to.
Table espuser-identity-providers: the upstream providers the federation broker may delegate to.
oauth_clients_db
Table espuser-oauth-clients (PK client_id, no SK): the registered OAuth/OIDC client registry.
Table espuser-oauth-clients (PK client_id, no SK): the registered OAuth/OIDC client registry.
refresh_tokens_db
Table espuser-refresh-tokens (PK user_id, SK client_id#family_id): one row per login family holding the current rotation counter.
Table espuser-refresh-tokens (PK user_id, SK client_id#family_id): one row per login family holding the current rotation counter.
handlers
authorize command
GET /oauth2/authorize (validate -> LOGIN flow record -> 302 to the login page with a flow_id cookie) and the served login UI.
GET /oauth2/authorize (validate -> LOGIN flow record -> 302 to the login page with a flow_id cookie) and the served login UI.
clients command
publish_discovery command
Command publish_discovery builds the static OIDC/OAuth discovery documents and uploads them to S3, once, at deploy.
Command publish_discovery builds the static OIDC/OAuth discovery documents and uploads them to S3, once, at deploy.
revoke command
token command
user_auth command
Command user_auth serves the native /v1/user/auth/* password APIs.
Command user_auth serves the native /v1/user/auth/* password APIs.
user_common command
userinfo command
Package idp runs the upstream leg of a brokered login, with ESP User as a confidential client of an upstream IdP. It is deliberately independent of the client's downstream leg — see the "why brokered, not pass-through" argument in espuser/docs/en/specs/federation.md.
Package idp runs the upstream leg of a brokered login, with ESP User as a confidential client of an upstream IdP. It is deliberately independent of the client's downstream leg — see the "why brokered, not pass-through" argument in espuser/docs/en/specs/federation.md.
Package legacyauth serves the native /v1/user/auth/* password APIs.
Package legacyauth serves the native /v1/user/auth/* password APIs.
Package refreshtoken is the ESP User refresh-token service: it owns the token lifecycle — mint a family on login, rotate-on-use with reuse=theft detection, and revoke — over the espuser-refresh-tokens store.
Package refreshtoken is the ESP User refresh-token service: it owns the token lifecycle — mint a family on login, rotate-on-use with reuse=theft detection, and revoke — over the espuser-refresh-tokens store.
Package scope is the single source of truth for ESP User's OAuth/OIDC scope values and space-delimited membership tests (RFC 6749 §3.3).
Package scope is the single source of truth for ESP User's OAuth/OIDC scope values and space-delimited membership tests (RFC 6749 §3.3).
Package sender resolves which SES identity the IdP sends mail from.
Package sender resolves which SES identity the IdP sends mail from.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL