Saltar al contenido principal

Autenticación Stellar para Cuentas de Contrato (SEP-45)

Descripción general​

SEP-45 (Stellar Web Authentication for Contract Accounts) permite a las aplicaciones de billeteras inteligentes crear sesiones autenticadas con anchors de Stellar demostrando el control sobre una cuenta de contrato (C...). Una vez autenticadas, las billeteras reciben un JSON Web Token (JWT) que usan en solicitudes posteriores a los servicios estandarizados del anchor.

Para la especificación completa, consulta SEP-0045: Stellar Web Authentication for Contract Accounts.

La Anchor Platform implementa SEP-45 con soporte para:

  • Flujo de Challenge/Response: GET /sep45/auth para solicitar entradas de autorización, POST /sep45/auth para validar y recibir un JWT
  • Autenticación de Cuenta de Contrato: Soporte para cuentas de contrato (C...) usando entradas de autorización Soroban
  • Simulación de Transacciones: Simulación automática de transacciones para verificar entradas de autorización
  • Múltiples Dominios Principales: Soporte para múltiples dominios y patrones comodín
información

SEP-45 vs SEP-10: SEP-45 no reemplaza a SEP-10. SEP-45 admite cuentas de contrato (C...), mientras que SEP-10 admite cuentas clásicas (G...) y cuentas muxed (M...). Los servicios que deseen admitir todos los tipos de cuentas deben implementar ambos SEPs.

Flujo Típico de Autenticación​

  1. El Cliente solicita un desafío único al Servidor
  2. El Cliente verifica y firma el desafío
  3. El Cliente envía el desafío firmado al Servidor
  4. El Servidor verifica el desafío y responde con un token de sesión JWT

Se proporciona una implementación del contrato SEP-45 en el repositorio Anchor Platform. Una instancia de este contrato está desplegada en CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX en testnet.

Activar SEP-45​

SEP-45 requiere integración con Stellar RPC para simular transacciones. Anchor Platform puede conectarse al servidor Stellar RPC que elijas. Puedes usar un proveedor público de Stellar RPC o ejecutar el tuyo propio. Una lista de proveedores públicos se encuentra aquí.

Para habilitar SEP-45, configura las siguientes variables de entorno en tu archivo dev.env.

# dev.env
STELLAR_NETWORK_TYPE=rpc
STELLAR_NETWORK_RPC_URL=https://soroban-testnet.stellar.org
SEP45_ENABLED=true
SEP45_HOME_DOMAINS=localhost:8080
SEP45_WEB_AUTH_CONTRACT_ID="CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX"
SECRET_SEP10_SIGNING_SEED="a Stellar private key"
SECRET_SEP45_JWT_SECRET="a secret encryption key"

Configuración requerida (si está habilitada)​

VariablePredeterminadoDescripción
STELLAR_NETWORK_TYPERequeridoDebe establecerse en rpc para SEP-45. Esto habilita el modo RPC para Anchor Platform.
STELLAR_NETWORK_RPC_URLRequeridoLa URL del servidor Stellar RPC utilizado para simulate transacciones. Puedes usar un proveedor público o ejecutar el tuyo propio. Puedes encontrar una lista de proveedores públicos aquí.
SEP45_ENABLEDfalseEstablece en true para habilitar la autenticación SEP-45
SEP45_HOME_DOMAINSRequeridoLista de dominios principales (separados por comas). Admite patrones comodín como *.stellar.org. El home_domain debe coincidir con el host donde se sirve tu archivo stellar.toml.
SEP45_WEB_AUTH_CONTRACT_IDRequeridoEl ID del contrato del contrato SEP-45. Este contrato debe implementar la función web_auth_verify como se describe en la especificación SEP-45.
SECRET_SEP10_SIGNING_SEEDRequeridoLa clave privada correspondiente a la SIGNING_KEY en tu archivo stellar.toml. SEP-45 usa la misma clave de firma que SEP-10. Se usa para firmar los desafíos de autenticación.
SECRET_SEP45_JWT_SECRETRequeridoLa clave de cifrado utilizada para firmar y verificar los tokens JWT emitidos a billeteras autenticadas.
important
  • Requisito RPC: SEP-45 requiere Stellar RPC para simulate transacciones. Debes establecer STELLAR_NETWORK_TYPE=rpc y proporcionar una STELLAR_NETWORK_RPC_URL válida.
  • ID del contrato: El SEP45_WEB_AUTH_CONTRACT_ID debe coincidir con el contrato desplegado en la dirección especificada en el campo WEB_AUTH_CONTRACT_ID de tu archivo stellar.toml.
  • Clave de firma: La SIGNING_KEY en tu archivo stellar.toml debe ser la clave pública derivada de SECRET_SEP10_SIGNING_SEED.

Configuración opcional​

# dev.env
# Optional: Specify web_auth_domain (default: first home_domain if only one is specified)
SEP45_WEB_AUTH_DOMAIN=localhost:8080

# Optional: Challenge timeout in seconds (default: 900)
SEP45_AUTH_TIMEOUT=900

# Optional: JWT token timeout in seconds (default: 86400 = 24 hours)
SEP45_JWT_TIMEOUT=86400
VariablePredeterminadoDescripción
SEP45_WEB_AUTH_DOMAINPrimer home_domain si se especifica solo uno, de lo contrario vacíoLa propiedad web_auth_domain utilizada en las respuestas SEP-45. Requerido si tienes múltiples home_domains o usas patrones comodín. Debe coincidir con el host del servidor SEP.
SEP45_AUTH_TIMEOUT900Tiempo en segundos que un desafío permanece válido. Los clientes deben firmar y enviar las entradas de autorización dentro de este período.
SEP45_JWT_TIMEOUT86400Tiempo en segundos que un token JWT emitido permanece válido. Después de la caducidad, los clientes deben autenticarse nuevamente.
consejo

Múltiples dominios principales: Si especificas múltiples home_domains (por ejemplo, ap.stellar.org,*.sdp.stellar.org), también debes establecer SEP45_WEB_AUTH_DOMAIN para indicar qué dominio aloja el endpoint de autenticación.

Configurar stellar.toml​

Actualiza tu archivo stellar.toml para anunciar soporte para SEP-45. Las billeteras descubren tu endpoint de autenticación a través de este archivo.

# dev.stellar.toml

ACCOUNTS = ["add your public keys for your distribution accounts here"]
SIGNING_KEY = "add your signing key here (public key from SECRET_SEP10_SIGNING_SEED)"
WEB_AUTH_FOR_CONTRACTS_ENDPOINT = "http://localhost:8080/sep45/auth"
WEB_AUTH_CONTRACT_ID = "CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX"

Estos campos deben coincidir con las opciones de configuración establecidas en la sección Habilitar SEP-45 arriba.

WEB_AUTH_FOR_CONTRACTS_ENDPOINT - La URL donde se ejecuta el servicio de autenticación. Esta es la URL que los clientes usarán para autenticarse con el anchor. El endpoint debe admitir:

  • GET <WEB_AUTH_FOR_CONTRACTS_ENDPOINT> - Solicitar entradas de autorización
  • POST <WEB_AUTH_FOR_CONTRACTS_ENDPOINT> - Intercambiar entradas de autorización firmadas por JWT de sesión

WEB_AUTH_CONTRACT_ID - El ID del contrato del contrato SEP-45. Este es el contrato que se usará para construir el desafío. El contrato debe implementar la función web_auth_verify como se describe en la especificación SEP-45. Esto debe coincidir con SEP45_WEB_AUTH_CONTRACT_ID.

important
  • SIGNING_KEY: Debe ser la clave pública derivada de SECRET_SEP10_SIGNING_SEED
  • WEB_AUTH_FOR_CONTRACTS_ENDPOINT: Usa https:// en producción. La ruta /sep45/auth es el endpoint estándar de SEP-45.
  • Coincidencia de host: El host en WEB_AUTH_FOR_CONTRACTS_ENDPOINT debe coincidir con uno de tus SEP45_HOME_DOMAINS (o con SEP45_WEB_AUTH_DOMAIN si se especifica).