Autenticación

El SDK de Retorna maneja automáticamente la autenticación usando OAuth2 y firmas digitales RSA para mayor seguridad.

Autenticación Automática

El SDK gestiona automáticamente:

• ✅ Obtención de tokens de acceso OAuth2
• ✅ Renovación automática de tokens expirados
• ✅ Reintentos en caso de errores 401/403
• ✅ Firmas digitales RSA para cada solicitud

No necesitas manejar tokens manualmente. El SDK lo hace por ti.

Flujo de Autenticación

1. Inicialización: Al crear el RetornaClient, el SDK valida tus credenciales
2. Primera Solicitud: Si no hay token, el SDK obtiene uno automáticamente
3. Solicitudes Subsecuentes: El SDK usa el token existente
4. Renovación: Si el token expira, el SDK obtiene uno nuevo automáticamente
5. Firmas: Cada solicitud se firma digitalmente con tu llave privada RSA

Credenciales Requeridas

Necesitas tres credenciales para autenticarte:

1. Client ID

Identificador único de tu aplicación/cliente.

.clientId("tu-client-id")

2. Client Secret

Secreto compartido para autenticación OAuth2.

.clientSecret("tu-client-secret")

3. Private Key (PEM)

Llave privada RSA en formato PEM para firmas digitales.

.privateKey("-----BEGIN PRIVATE KEY-----\n" +
            "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...\n" +
            "-----END PRIVATE KEY-----")

Formato Requerido: La llave debe incluir los headers -----BEGIN PRIVATE KEY----- y -----END PRIVATE KEY-----.

Token Inicial Opcional

Si ya tienes un token de acceso válido, puedes proporcionarlo al crear el cliente:

RetornaClient client = RetornaClient.create(
    RetornaClientOptions.builder()
        .environment(Environment.DEVELOP)
        .clientId("tu-client-id")
        .clientSecret("tu-client-secret")
        .privateKey("tu-private-key")
        .initialAccessToken("tu-token-existente")
        .build()
);

El SDK usará este token hasta que expire, momento en el cual obtendrá uno nuevo automáticamente.

Firmas Digitales

Cada solicitud HTTP se firma digitalmente usando tu llave privada RSA. Esto proporciona:

• Autenticidad: Verifica que la solicitud viene de ti
• Integridad: Asegura que la solicitud no ha sido modificada
• No repudio: Prueba de que la solicitud fue enviada por ti

El SDK maneja esto automáticamente. No necesitas hacer nada adicional.

Manejo de Errores de Autenticación

El SDK maneja automáticamente los siguientes errores:

401 Unauthorized

Si recibes un 401, el SDK:

1. Intenta obtener un nuevo token
2. Reintenta la solicitud original
3. Si falla nuevamente, lanza una excepción

403 Forbidden

Si recibes un 403, el SDK:

1. Verifica las credenciales
2. Intenta renovar el token
3. Si persiste, lanza una excepción

Credenciales Inválidas

Si las credenciales son inválidas, recibirás una excepción al intentar hacer la primera solicitud:

try {
    BalanceResponse balance = client.account.getBalance();
} catch (RuntimeException e) {
    // Error de autenticación
    System.err.println("Error: " + e.getMessage());
}

Seguridad de Credenciales

✅ Buenas Prácticas

1. Variables de Entorno: Usa variables de entorno para credenciales
2. No Committear: Nunca commitees credenciales en el código
3. Rotación: Rota tus credenciales regularmente
4. Permisos Mínimos: Usa credenciales con permisos mínimos necesarios

❌ Evitar

1. Hardcodeo: No hardcodees credenciales en el código
2. Logs: No loguees credenciales
3. Archivos Públicos: No guardes credenciales en archivos públicos
4. Compartir: No compartas credenciales por canales inseguros

Ejemplo Completo

import com.retorna.sdk.config.Environment;
import com.retorna.sdk.config.LoggingLevel;
import com.retorna.sdk.core.RetornaClient;
import com.retorna.sdk.core.RetornaClientOptions;
import com.retorna.sdk.account.BalanceResponse;

public class AuthExample {
    public static void main(String[] args) {
        // Crear cliente con autenticación automática
        RetornaClient client = RetornaClient.create(
            RetornaClientOptions.builder()
                .environment(Environment.DEVELOP)
                .loggingLevel(LoggingLevel.INFO)
                .clientId(System.getenv("RETORNA_CLIENT_ID"))
                .clientSecret(System.getenv("RETORNA_CLIENT_SECRET"))
                .privateKey(System.getenv("RETORNA_PRIVATE_KEY"))
                .build()
        );
        
        try {
            // El SDK maneja automáticamente la autenticación
            BalanceResponse balance = client.account.getBalance();
            System.out.println("Balance: " + balance.getTotalBalance());
        } catch (RuntimeException e) {
            System.err.println("Error de autenticación: " + e.getMessage());
        }
    }
}

Debugging de Autenticación

Para debuggear problemas de autenticación, activa el logging en nivel DEBUG:

.loggingLevel(LoggingLevel.DEBUG)

Esto mostrará:

• Intentos de autenticación
• Tokens obtenidos (sin mostrar el valor completo por seguridad)
• Errores de autenticación
• Reintentos automáticos

Siguiente Paso

Ahora que entiendes la autenticación, consulta las Guías de Uso para aprender a usar las diferentes funcionalidades del SDK.