Autenticacion y credenciales

Autenticacion y credenciales

ms-recargas maneja dos planos de autenticacion distintos:

1. autenticacion de entrada al microservicio
2. credenciales tecnicas de salida hacia Claro SPR

El dashboard y n8n nunca llaman directo al XML de Claro; siempre entran por HTTP JSON al modulo.

Autenticacion de entrada a ms-recargas

Esquema	Header	Uso
Bearer JWT	Authorization: Bearer <token>	Dashboard interno
ServiceKey	x-service-key: <key>	n8n y llamadas internas

Bearer JWT

El AuthGuard extrae el token, llama a POST /api/internal/users/validate_token en ms-auth, cachea la respuesta en Redis por 60 segundos y adjunta request.user = { id, email, permissions[] }.

El PermissionsGuard aplica autorizacion por permisos y exige que todos los permisos declarados por el endpoint existan en request.user.permissions.

Para recargas se usan principalmente:

• create_recargas
• view_recargas

Action token para recarga manual

La recarga manual requiere un segundo factor de autorizacion por accion. Ademas del JWT normal, el frontend debe enviar X-Action-Token.

Flujo resumido:

1. POST /api/v1/auth/issue-action-otp con purpose=RECHARGE.
2. ms-auth envia un codigo de 6 digitos al correo del operador.
3. POST /api/v1/auth/verify-action-otp devuelve un action_token con vida corta.
4. POST /api/v1/recargas/recharge consume ese token una sola vez.

Reglas relevantes:

• action_otp_token: TTL de 2 minutos.
• OTP numerico: TTL de 60 segundos en Redis.
• action_token: TTL de 2 minutos.
• El jti del token se quema via SET NX EX para impedir replay.

ServiceKey

El ServiceKeyGuard compara el header x-service-key con la variable SERVICE_KEY. Este esquema se usa para el webhook de n8n y para integraciones internas sin contexto de usuario.

Es el mismo patron operativo usado en ms-auth, ms-mba y ms-blog.

Matriz de acceso por endpoint

Endpoint	Auth requerida	Permiso
POST /api/v1/recargas/recharge	Bearer JWT + X-Action-Token	create_recargas
POST /api/v1/recargas/webhook/invoice-recharge	ServiceKey	No aplica
GET /api/v1/recargas/transactions	Bearer JWT	view_recargas
GET /api/v1/recargas/transactions/:id	Bearer JWT	view_recargas
POST /api/v1/recargas/query-recharge	Bearer JWT	view_recargas
GET /api/v1/recargas/inventory	Bearer JWT	view_recargas

Reglas de proteccion complementarias

Control	Aplica a	Resultado al fallar
ActionTokenGuard	POST /recargas/recharge	401
ThrottlerGuard grupo recharge (5/60s)	POST /recargas/recharge	429
DailyRechargeLimitGuard	POST /recargas/recharge	429

Los usuarios con permiso unlimited_recargas omiten el limite diario.

Credenciales tecnicas hacia Claro

Cada request XML enviado al SPR debe incluir estas credenciales de integracion:

Campo	Descripcion	Valor de desarrollo
USERID	Usuario tecnico con el cual se accede al servicio.	PRUEBAREC
PASSWORD	Credencial asignada al USERID.	5566
TOKEN	Codigo de seguridad entregado por Claro. El ente invocador debe enviarlo para su validacion.	PRUEBACOMPANI
COMPANYID	Identificador de la compania o proveedor que consume el servicio.	PRUEBACOMPANI
CONSUMERID	Identificador del consumidor o punto final integrador.	PRUEBAREC_001
USERNAME	Usuario asignado a la persona que realiza la transaccion. Aplica cuando la transaccion se envia desde una aplicacion manipulada por una persona.	PRUEBAREC
TERMINAL	Identificador unico del dispositivo tecnologico desde el cual se envia la transaccion (IP o nombre).	10.35.2.78

Estas credenciales viven como variables de entorno del servicio. No viajan desde el dashboard ni desde n8n.

Variables de entorno relevantes

Variable	Uso
SERVICE_KEY	Llave del webhook y consumo interno
CLARO_SPR_URL	Endpoint del SPR
CLARO_MOCK_MODE	Activa ClaroMockService
CLARO_USERID / CLARO_PASSWORD / CLARO_TOKEN	Credenciales directas de Claro
CLARO_COMPANYID / CLARO_CONSUMERID / CLARO_USERNAME	Identidad de la entidad integradora
CLARO_TERMINAL	Terminal autorizado en Claro
CLARO_CHANNEL_ID / CLARO_MEDIA_ID / CLARO_MEDIADETAIL_ID	Metadatos del canal MOVILPOS
CLARO_LATITUDE / CLARO_LONGITUDE / CLARO_AZIMUTH / CLARO_CELLID	Geolocalizacion del POS
CLARO_PROVINCE / CLARO_PARISH / CLARO_EXTERNAL_STOCK	Contexto territorial y stock declarado
CLARO_AUTH_URL / CLARO_CLIENT_CREDENTIALS / CLARO_AUDIENCE	OAuth2 cuando Claro habilite ese flujo
CLARO_TOKEN_CACHE_PREFIX / CLARO_TOKEN_REFRESH_MARGIN_SECONDS	Cache del token de Claro en Redis
NOTIFICATION_EMAIL_DEFAULT	Destino por defecto para rechazos del webhook

Variables nuevas del flujo OTP

Servicio	Variable	Uso
ms-auth	JWT_ACTION_OTP_EXPIRATION	Expiracion del JWT action-otp
ms-auth	JWT_ACTION_TOKEN_EXPIRATION	Expiracion del JWT action
ms-auth	ACTION_OTP_TTL_SECONDS	Vida del codigo OTP en Redis
ms-recargas	RECARGAS_DAILY_LIMIT	Limite diario por usuario
ms-recargas	NOTIFICATION_EMAIL_DEFAULT	Buzon de operaciones por defecto

Ejemplo de credenciales dentro del XML

<umsprot version="1">
  <exec_req function="sre_movilposd_76186">
    <data name="USERID">PRUEBAREC</data>
    <data name="PASSWORD">5566</data>
    <data name="TOKEN">PRUEBACOMPANI</data>
    <data name="COMPANYID">PRUEBACOMPANI</data>
    <data name="CONSUMERID">PRUEBAREC_001</data>
    <data name="USERNAME">PRUEBAREC</data>
    <data name="TERMINAL">10.35.2.78</data>
  </exec_req>
</umsprot>

Validacion de IP en el SPR

Ademas de las credenciales, la IP desde la cual se invoca el servicio debe estar registrada en la configuracion del SPR. Si la IP no esta validada, Claro responde con faultCode=350:

<env:Fault>
  <faultcode>350</faultcode>
  <faultstring>El id_requerimiento es nulo debido a que el xml recibido
  en el body del request no corresponde a ningun formato configurado
  para la ip del llamante: 10.35.2.31</faultstring>
</env:Fault>

ms-recargas debe tratar este caso como unavailable, devolver 502 y registrar una alerta operacional claro.ip_rejected.

Regla importante de separacion

• El dashboard autentica usuarios.
• n8n autentica sistemas.
• ms-recargas autentica la salida a Claro.

Eso permite cambiar credenciales de Claro sin tocar el frontend ni el workflow de n8n.

Recomendaciones

1. No expongas SERVICE_KEY, PASSWORD ni TOKEN en logs, commits o respuestas HTTP.
2. Valida que la IP saliente este registrada en Claro antes de pruebas reales.
3. Manten separado el control de permisos del dashboard y la autenticacion tecnica del webhook.
4. Si cambias credenciales de Claro, vuelve a probar recarga, consulta e inventario.