s.hajizadeh/esg
1
0
Fork 0
forked from Shared/esg
Code Pull Requests Activity
Files
ead2e301e5e1abbe3d1f36f0edf5bee94518d5de
esg/docs/ENVIRONMENT_CONFIGURATION.md
s.hajizadeh 996a4fcda7 initial commit
2026-06-09 14:07:37 +03:30

12 KiB
Raw Blame History

Environment Configuration Guide

This guide explains all environment variables used in the ESG Inquiry Gateway system.

Table of Contents

Application Settings

Basic Configuration

PORT=8085                    # HTTP server port
NODE_ENV=development         # Environment: development, production, test

OpenTelemetry (Optional)

OTEL_EXPORTER_OTLP_ENDPOINT=http://192.168.10.10:4318
OTEL_SERVICE_NAME=esg
OTEL_NODE_RESOURCE_DETECTORS=env,host,os

Database Configuration

MongoDB

MONGODB_URI=mongodb://localhost:27017/inquiry-gateway

Authentication & Security

API Authentication

API_KEY=your-secure-api-key-here              # API key for external clients
JWT_SECRET=change-me-use-long-random-string   # JWT signing secret
JWT_REFRESH_SECRET=change-me-refresh-secret   # JWT refresh token secret
JWT_ACCESS_EXPIRES_IN=15m                     # Access token lifetime
JWT_REFRESH_EXPIRES_IN=7d                     # Refresh token lifetime
JWT_ENABLED=true                              # Enable/disable JWT auth
BCRYPT_SALT_ROUNDS=12                         # Password hashing rounds

Rate Limiting

THROTTLE_TTL=60      # Time window in seconds
THROTTLE_LIMIT=100   # Max requests per window

Provider Configuration

Understanding Provider Architecture

The system has two types of components:

  1. Providers (Inquiry Handlers): HAMTA, MOALLEM, TEJARATNOU
  2. Authentication Services: AMITIS (used by HAMTA and MOALLEM)

AMITIS Authentication Service

AMITIS is not a provider - it's an authentication service that provides tokens for HAMTA and MOALLEM.

# AMITIS Configuration
AMITIS_BASE_URL=https://auth.services.centinsur.ir
AMITIS_LOGIN_PATH=/api/security/login
AMITIS_REFRESH_PATH=/api/security/RefreshToken
AMITIS_TOKEN_TIME_ZONE=Asia/Tehran
AMITIS_TIMEOUT=10000
AMITIS_ENABLED=true

Token Management:

  • Tokens refresh every 20 minutes
  • Tokens expire daily at 23:59:59 (Tehran time)
  • Automatic refresh with fallback to re-login

Provider Structure

Each provider has:

  • Global settings: ENABLED, TIMEOUT, MAX_RETRIES
  • Per-inquiry settings: URL, USERNAME, PASSWORD, AUTH_METHOD

Format: PROVIDER_INQUIRY_FIELD

Example:

HAMTA_REAL_ESTATE_URL=https://apigw.services.centinsur.ir/amlakeskanservice/amlakeskan/inquiry
HAMTA_REAL_ESTATE_USERNAME=AmlakEskanHamta
HAMTA_REAL_ESTATE_PASSWORD=r#Tk5!4bj
HAMTA_REAL_ESTATE_AUTH_METHOD=AMITIS

Authentication Methods

Each inquiry can use different authentication:

  • AMITIS: Token-based auth via AMITIS service
  • SOAP: Direct SOAP authentication (credentials in XML)
  • OAUTH2: OAuth2 flow (TejaratNou)
  • NONE: No authentication required

HAMTA Provider

# Global Settings
HAMTA_ENABLED=true
HAMTA_TIMEOUT=10000
HAMTA_MAX_RETRIES=3

# Person Inquiry (AMITIS auth)
HAMTA_PERSON_URL=https://api.hamta.example.com/api/inquiry/person
HAMTA_PERSON_USERNAME=pa6476
HAMTA_PERSON_PASSWORD=ciiws@sabt92
HAMTA_PERSON_AUTH_METHOD=AMITIS

# Real Estate Inquiry (AMITIS auth)
HAMTA_REAL_ESTATE_URL=https://apigw.services.centinsur.ir/amlakeskanservice/amlakeskan/inquiry
HAMTA_REAL_ESTATE_USERNAME=AmlakEskanHamta
HAMTA_REAL_ESTATE_PASSWORD=r#Tk5!4bj
HAMTA_REAL_ESTATE_AUTH_METHOD=AMITIS

# Shahkar Inquiry (SOAP auth - no AMITIS)
HAMTA_SHAHKAR_URL=http://reinsure.centinsur.ir/shahkarinqOut
HAMTA_SHAHKAR_USERNAME=Hamta.Shahkar
HAMTA_SHAHKAR_PASSWORD=Y^WzP!8R5Tz
HAMTA_SHAHKAR_AUTH_METHOD=SOAP

# Sheba/Sayah Inquiry (AMITIS auth)
HAMTA_SHEBA_URL=https://api.hamta.example.com/api/inquiry/sheba
HAMTA_SHEBA_USERNAME=Hamta.sayah
HAMTA_SHEBA_PASSWORD=J$z07$bg
HAMTA_SHEBA_AUTH_METHOD=AMITIS

# Postal Code Inquiry (AMITIS auth)
HAMTA_POSTAL_CODE_URL=https://api.hamta.example.com/api/inquiry/postalCode
HAMTA_POSTAL_CODE_USERNAME=
HAMTA_POSTAL_CODE_PASSWORD=
HAMTA_POSTAL_CODE_AUTH_METHOD=AMITIS

# Legal Person Inquiry (AMITIS auth)
HAMTA_LEGAL_PERSON_URL=https://api.hamta.example.com/api/inquiry/legalPerson
HAMTA_LEGAL_PERSON_USERNAME=SabtAsnadHamta
HAMTA_LEGAL_PERSON_PASSWORD=HSY1f6?e@kSJ
HAMTA_LEGAL_PERSON_AUTH_METHOD=AMITIS

MOALLEM Provider

# Global Settings
MOALLEM_ENABLED=true
MOALLEM_TIMEOUT=10000
MOALLEM_MAX_RETRIES=2

# Person Inquiry (SOAP auth)
MOALLEM_PERSON_URL=http://reinsure.centinsur.ir/SabtV3Out
MOALLEM_PERSON_USERNAME=mo9635
MOALLEM_PERSON_PASSWORD=ciiws@sabt92
MOALLEM_PERSON_AUTH_METHOD=SOAP

# Postal Code Inquiry (AMITIS auth)
MOALLEM_POSTAL_CODE_URL=https://postalcode.services.centinsur.ir/api/cisb
MOALLEM_POSTAL_CODE_USERNAME=moallem.post
MOALLEM_POSTAL_CODE_PASSWORD=tBUCLGfVJH
MOALLEM_POSTAL_CODE_AUTH_METHOD=AMITIS

# Real Estate Inquiry (AMITIS auth)
MOALLEM_REAL_ESTATE_URL=https://api.moallem.example.com/api/inquiry/realEstate
MOALLEM_REAL_ESTATE_USERNAME=AmlakEskanMoalem
MOALLEM_REAL_ESTATE_PASSWORD=AEM@123456
MOALLEM_REAL_ESTATE_AUTH_METHOD=AMITIS

# Shahkar Inquiry (SOAP auth)
MOALLEM_SHAHKAR_URL=http://reinsure.centinsur.ir/shahkarinqOut
MOALLEM_SHAHKAR_USERNAME=ShkrMoalem1286
MOALLEM_SHAHKAR_PASSWORD=cuYYELt9
MOALLEM_SHAHKAR_AUTH_METHOD=SOAP

# Sheba/Sayah Inquiry (AMITIS auth)
MOALLEM_SHEBA_URL=https://sayah.services.centinsur.ir/api/Cisb/TatbighServiceAsync
MOALLEM_SHEBA_USERNAME=moallem.sayah
MOALLEM_SHEBA_PASSWORD=BUCLGfVJH7
MOALLEM_SHEBA_AUTH_METHOD=AMITIS

# Legal Person Inquiry (SOAP auth)
MOALLEM_LEGAL_PERSON_URL=http://reinsure.centinsur.ir/SabtV3Out
MOALLEM_LEGAL_PERSON_USERNAME=
MOALLEM_LEGAL_PERSON_PASSWORD=
MOALLEM_LEGAL_PERSON_AUTH_METHOD=SOAP

TEJARATNOU Provider

# Global Settings
TEJARATNOU_ENABLED=true
TEJARATNOU_TIMEOUT=15000
TEJARATNOU_MAX_RETRIES=2

# OAuth2 Authentication
TEJARATNOU_AUTH_URL=https://accounts.tejaratnoins.ir
TEJARATNOU_CLIENT_ID=api-gateway
TEJARATNOU_CLIENT_SECRET=hkld@ork123T
TEJARATNOU_USERNAME=thirdparty-silcogroup
TEJARATNOU_PASSWORD=FDHG87sdf787l764iuo

# Person Inquiry
TEJARATNOU_PERSON_URL=https://gateway.tejaratnoins.ir/api/inquiry/person
TEJARATNOU_PERSON_AUTH_METHOD=OAUTH2

Inquiry Routing

Routing determines which provider handles each inquiry type and whether to use fallbacks.

Format

{INQUIRY_TYPE}_DEFAULT_PROVIDER=PROVIDER_NAME
{INQUIRY_TYPE}_FALLBACK_ENABLED=true|false
{INQUIRY_TYPE}_FALLBACK_PROVIDERS=PROVIDER1,PROVIDER2

Available Inquiry Types

  • PERSON - Person/Civil registration inquiry
  • REAL_ESTATE - Real estate/property inquiry
  • SHAHKAR - Mobile number verification
  • POSTAL_CODE - Postal code lookup
  • SHEBA - Bank account verification
  • LEGAL_PERSON - Legal entity inquiry
  • CAR_PLATE - Vehicle plate inquiry

Example Configurations

Person Inquiry (Single Provider)

PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=false
PERSON_FALLBACK_PROVIDERS=

Behavior: Only TEJARATNOU is used. If it fails, request fails.

Person Inquiry (With Fallback)

PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=HAMTA,MOALLEM

Behavior:

  1. Try TEJARATNOU first
  2. If fails, try HAMTA
  3. If fails, try MOALLEM
  4. If all fail, return error

Real Estate Inquiry

REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=false
REAL_ESTATE_FALLBACK_PROVIDERS=

Shahkar Inquiry

SHAHKAR_DEFAULT_PROVIDER=MOALLEM
SHAHKAR_FALLBACK_ENABLED=false
SHAHKAR_FALLBACK_PROVIDERS=

Provider Behavior Examples

Scenario 1: All Providers Enabled

HAMTA_ENABLED=true
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=false

Result: Only TEJARATNOU is used for person inquiries, even though others are enabled.

Scenario 2: Default Provider Disabled

HAMTA_ENABLED=false
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

PERSON_DEFAULT_PROVIDER=HAMTA
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=TEJARATNOU,MOALLEM

Result:

  • HAMTA is skipped (disabled)
  • TEJARATNOU is tried first (first enabled fallback)
  • MOALLEM is tried if TEJARATNOU fails

Scenario 3: No Providers Available

HAMTA_ENABLED=false
MOALLEM_ENABLED=false
TEJARATNOU_ENABLED=false

PERSON_DEFAULT_PROVIDER=TEJARATNOU

Result: API returns error:

{
  "success": false,
  "provider": "GATEWAY",
  "message": "No enabled providers configured for PERSON",
  "error": {
    "code": "NO_PROVIDERS",
    "message": "No enabled providers configured for PERSON"
  }
}

Scenario 4: All Providers Fail

HAMTA_ENABLED=true
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=HAMTA,MOALLEM

Result: If all three providers fail, API returns:

{
  "success": false,
  "provider": "GATEWAY",
  "message": "TEJARATNOU failed: timeout; HAMTA failed: auth error; MOALLEM failed: network error",
  "error": {
    "code": "ALL_PROVIDERS_FAILED",
    "message": "Combined error messages from all providers"
  }
}

Production Recommendations

High Availability Setup

# Enable all providers
HAMTA_ENABLED=true
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

# Use fallbacks for critical inquiries
PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=HAMTA,MOALLEM

REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=true
REAL_ESTATE_FALLBACK_PROVIDERS=MOALLEM

Performance-Optimized Setup

# Enable only primary providers
HAMTA_ENABLED=true
MOALLEM_ENABLED=false
TEJARATNOU_ENABLED=true

# No fallbacks for faster response
PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=false

REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=false

Cost-Optimized Setup

# Enable only necessary providers
HAMTA_ENABLED=true
MOALLEM_ENABLED=false
TEJARATNOU_ENABLED=false

# Single provider per inquiry type
PERSON_DEFAULT_PROVIDER=HAMTA
PERSON_FALLBACK_ENABLED=false

REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=false

Security Best Practices

  1. Never commit .env to git - Use .env.example as template
  2. Rotate credentials regularly - Update passwords every 90 days
  3. Use strong secrets - Generate random strings for JWT secrets
  4. Limit API key distribution - One key per client application
  5. Enable rate limiting - Protect against abuse
  6. Monitor failed authentications - Alert on repeated failures
  7. Use HTTPS in production - Never send credentials over HTTP

Troubleshooting

Provider Not Working

  1. Check if provider is enabled: {PROVIDER}_ENABLED=true
  2. Verify credentials are correct
  3. Check if inquiry type is configured for that provider
  4. Verify network connectivity to provider URL
  5. Check logs for authentication errors

No Providers Available Error

  1. Verify at least one provider is enabled
  2. Check {INQUIRY}_DEFAULT_PROVIDER is set correctly
  3. Ensure the default provider supports the inquiry type
  4. Verify provider credentials are configured

Authentication Failures

  1. Check AMITIS service is enabled and reachable
  2. Verify credentials in {PROVIDER}_{INQUIRY}_USERNAME/PASSWORD
  3. Check if tokens are expiring (should auto-refresh)
  4. Verify system time is correct (affects token expiration)

Performance Issues

  1. Reduce MAX_RETRIES for faster failures
  2. Decrease TIMEOUT values
  3. Disable fallbacks if not needed
  4. Enable only required providers
  5. Check network latency to provider services

Migration from Old Format

Old Format (Deprecated)

AMITIS_HAMTA_PERSON_USERNAME=pa6476
AMITIS_HAMTA_PERSON_PASSWORD=ciiws@sabt92

New Format (Current)

HAMTA_PERSON_USERNAME=pa6476
HAMTA_PERSON_PASSWORD=ciiws@sabt92
HAMTA_PERSON_AUTH_METHOD=AMITIS

Key Changes:

  • Removed AMITIS_ prefix from provider credentials
  • Added AUTH_METHOD to specify authentication type
  • Added per-inquiry URL configuration
  • AMITIS is now a separate authentication service, not a provider
View Git Blame Copy Permalink