Skip to content

user_emails.md

Latest commit

 

History

History
190 lines (144 loc) · 5.63 KB

user_emails.md

File metadata and controls

190 lines (144 loc) · 5.63 KB

User Emails Operations

This document describes the NATS subject for retrieving user email addresses.

User Emails Retrieval

To retrieve user email addresses (both primary and alternate emails), send a NATS request to the following subject:

Subject: lfx.auth-service.user_emails.read
Pattern: Request/Reply

The service supports a hybrid approach for user email retrieval, accepting multiple input types and automatically determining the appropriate lookup strategy based on the input format.

Hybrid Input Support

The service intelligently handles different input types:

  1. JWT Tokens (Auth0) or Authelia Tokens (Authelia)
  2. Subject Identifiers (canonical user IDs)
  3. Usernames

Request Payload

The request payload can be any of the following formats (no JSON wrapping required):

JWT Token (Auth0):

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Subject Identifier:

auth0|123456789

Username:

john.doe

Lookup Strategy

The service automatically determines the lookup strategy based on input format:

  • Token Strategy: If input is a JWT/Authelia token, validates the token and extracts the subject identifier
  • Canonical Lookup: If input contains | (pipe character) or is a UUID, treats as subject identifier for direct lookup
  • Username Search: If input doesn't match above patterns, treats as username for search lookup

Reply

The service returns a structured reply with user email information:

Success Reply:

{
  "success": true,
  "data": {
    "primary_email": "john.doe@example.com",
    "alternate_emails": [
      {
        "email": "john.doe@personal.com",
        "verified": true
      },
      {
        "email": "j.doe@company.com",
        "verified": false
      }
    ]
  }
}

Success Reply (No Alternate Emails):

{
  "success": true,
  "data": {
    "primary_email": "john.doe@example.com",
    "alternate_emails": []
  }
}

Error Reply (User Not Found):

{
  "success": false,
  "error": "user not found"
}

Error Reply (Invalid Token):

{
  "success": false,
  "error": "invalid token"
}

Response Fields

  • primary_email (string): The user's primary email address registered with the identity provider
  • alternate_emails (array): List of alternate email addresses linked to the user account
    • email (string): The alternate email address
    • verified (boolean): Whether the alternate email has been verified

Example using NATS CLI

# Retrieve user emails using JWT token
nats request lfx.auth-service.user_emails.read "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

# Retrieve user emails using subject identifier
nats request lfx.auth-service.user_emails.read "auth0|123456789"

# Retrieve user emails using username
nats request lfx.auth-service.user_emails.read "john.doe"

Example Response Processing

# Get and format the response
nats request lfx.auth-service.user_emails.read "john.doe" | jq '.'

# Extract only the primary email
nats request lfx.auth-service.user_emails.read "john.doe" | jq -r '.data.primary_email'

# List all verified alternate emails
nats request lfx.auth-service.user_emails.read "john.doe" | jq -r '.data.alternate_emails[] | select(.verified == true) | .email'

# Count total email addresses (primary + alternates)
nats request lfx.auth-service.user_emails.read "john.doe" | jq '.data.alternate_emails | length + 1'

Important Notes:

  • The service automatically detects input type and applies the appropriate lookup strategy
  • JWT tokens are validated for signature and expiration before extracting subject information
  • The target identity provider is determined by the USER_REPOSITORY_TYPE environment variable
  • Primary email is always present if the user exists
  • Alternate emails array may be empty if the user has not linked any additional email addresses
  • Only verified alternate emails should be considered as confirmed user identities
  • For detailed Auth0-specific behavior and limitations, see: ../internal/infrastructure/auth0/README.md
  • For detailed Authelia-specific behavior and SUB management, see: ../internal/infrastructure/authelia/README.md

Use Cases

Identity Verification

When you need to verify if a user owns a specific email address:

# Get all user emails
nats request lfx.auth-service.user_emails.read "john.doe"

Email Communication

When you need to send notifications to all verified user email addresses:

# Extract all verified emails (primary + verified alternates)
nats request lfx.auth-service.user_emails.read "john.doe" | \
  jq -r '(.data.primary_email, (.data.alternate_emails[] | select(.verified == true) | .email))'

Account Recovery

When displaying email options for account recovery:

# Show all verified email addresses for recovery selection
nats request lfx.auth-service.user_emails.read "auth0|123456789" | \
  jq '.data.alternate_emails[] | select(.verified == true)'

Email Uniqueness Check

To check if an email is already associated with a user account, use the email lookup subjects:

  • lfx.auth-service.email_to_username - Get username from email
  • lfx.auth-service.email_to_sub - Get user ID from email

See email_lookups.md for more details on these subjects.

Related Subjects