Turinga! Connect

Estado actual de la plataforma

Las siguientes funciones forman parte de la implementación actual de Turinga! Connect:

Flujo de autenticación

La contraseña del usuario nunca abandona Turinga!. Tu aplicación solamente recibe credenciales OAuth y los datos correspondientes a los scopes autorizados.

Registrar una aplicación

Registra tu aplicación desde el portal de desarrolladores:

Tu aplicación obtiene:

• client_id: identificador público de la aplicación.
• client_secret: credencial privada de aplicaciones confidenciales.

Las aplicaciones nuevas pueden permanecer en estado pending hasta completar su revisión.

PKCE S256

Turinga! Connect requiere PKCE con S256 para todas las autorizaciones.

1. Generar code_verifier

$verifier = rtrim(
    strtr(base64_encode(random_bytes(64)), '+/', '-_'),
    '='
);

2. Generar code_challenge

$challenge = rtrim(
    strtr(
        base64_encode(hash('sha256', $verifier, true)),
        '+/',
        '-_'
    ),
    '='
);

El code_verifier debe mantenerse temporalmente del lado servidor de tu aplicación y utilizarse cuando intercambies el Authorization Code.

Authorization Endpoint

Ejemplo

https://connect.turinga.net/oauth/authorize.php
?response_type=code
&client_id=tur_xxxxx
&redirect_uri=https%3A%2F%2Fejemplo.com%2Fauth%2Fcallback.php
&scope=openid%20profile
&state=STATE_ALEATORIO
&code_challenge=CHALLENGE
&code_challenge_method=S256

Respuesta correcta

https://ejemplo.com/auth/callback.php
?code=tac_xxxxx
&state=STATE_ALEATORIO

Token Endpoint

Intercambia el Authorization Code por Access Token y Refresh Token.

grant_type=authorization_code
client_id=tur_xxxxx
client_secret=tcs_xxxxx
code=tac_xxxxx
redirect_uri=https://ejemplo.com/auth/callback.php
code_verifier=VERIFIER_ORIGINAL

Content-Type:

application/x-www-form-urlencoded

Respuesta

{
  "access_token": "tka_xxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tkr_xxxxx",
  "scope": "openid profile"
}

Refresh Token Rotation

Cuando el Access Token expire, utiliza el Refresh Token para obtener una nueva pareja de tokens.

grant_type=refresh_token
client_id=tur_xxxxx
client_secret=tcs_xxxxx
refresh_token=tkr_xxxxx

Respuesta

{
  "access_token": "tka_NUEVO",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tkr_NUEVO",
  "scope": "openid profile"
}

Detección de reutilización

Si un Refresh Token que ya fue utilizado aparece nuevamente, Turinga! Connect puede interpretar la situación como una posible filtración de credenciales.

En ese caso puede:

• marcar la reutilización del token;
• revocar toda la familia de Refresh Tokens;
• revocar Access Tokens relacionados con esa aplicación y usuario.

UserInfo

Envía el Access Token mediante el header:

Authorization: Bearer tka_xxxxx
Accept: application/json

Ejemplo de respuesta

{
  "sub": "1",
  "id": 1,
  "nick": "Usuario",
  "profile_url": "https://turinga.net/perfil/Usuario",
  "avatar": "https://...",
  "role": "Desarrollador"
}

Los datos devueltos dependen de los scopes otorgados.

Revocación de tokens

Una aplicación puede invalidar voluntariamente un Access Token o un Refresh Token.

Revocar Access Token

client_id=tur_xxxxx
client_secret=tcs_xxxxx
token=tka_xxxxx
token_type_hint=access_token

Revocar Refresh Token

client_id=tur_xxxxx
client_secret=tcs_xxxxx
token=tkr_xxxxx
token_type_hint=refresh_token

Los valores reconocidos de token_type_hint son:

• access_token
• refresh_token

Comportamiento

Al revocar un Access Token solamente se invalida ese token.

Al revocar un Refresh Token, Turinga! Connect puede revocar:

• la familia completa de Refresh Tokens;
• los Access Tokens activos pertenecientes a esa aplicación y usuario.

Respuesta

Una revocación procesada correctamente responde:

HTTP/1.1 200 OK

La respuesta puede no contener cuerpo.

Scopes

Una aplicación solamente puede solicitar scopes previamente habilitados para ella.

Rate limits

Turinga! Connect aplica límites de solicitudes en endpoints sensibles para reducir abuso, enumeración de tokens y ataques automatizados.

UserInfo

Token Revocation

HTTP 429

Cuando una aplicación supera un límite puede recibir:

HTTP/1.1 429 Too Many Requests
Retry-After: 42

y una respuesta similar a:

{
  "error": "slow_down",
  "error_description": "Demasiadas solicitudes."
}

Errores OAuth

Los endpoints pueden responder errores estructurados:

{
  "error": "invalid_grant",
  "error_description": "Authorization Code inválido o expirado."
}

Recomendaciones de seguridad

• Utiliza HTTPS.
• Genera state criptográficamente aleatorio para cada autorización.
• Valida siempre state en el callback.
• Utiliza PKCE S256.
• No reutilices Authorization Codes.
• Guarda el Client Secret únicamente del lado servidor.
• Nunca incluyas el Client Secret en JavaScript público.
• No envíes Access Tokens ni Refresh Tokens mediante URLs.
• No escribas tokens completos en logs.
• Guarda Refresh Tokens en almacenamiento protegido.
• Sustituye inmediatamente un Refresh Token después de rotarlo.
• Respeta HTTP 429 y Retry-After.
• No utilices el Access Token como cookie de sesión de tu propia aplicación.
• Después de obtener UserInfo, crea tu propia sesión segura.

Ejemplo completo en PHP

Iniciar autorización

<?php
session_start();

$clientId = 'TU_CLIENT_ID';
$redirectUri = 'https://ejemplo.com/auth/turinga/callback.php';

function b64url(string $value): string {
    return rtrim(
        strtr(base64_encode($value), '+/', '-_'),
        '='
    );
}

$state = b64url(random_bytes(32));
$verifier = b64url(random_bytes(64));

$challenge = b64url(
    hash('sha256', $verifier, true)
);

$_SESSION['turinga_oauth'] = [
    'state' => $state,
    'verifier' => $verifier,
    'created_at' => time()
];

$params = [
    'response_type' => 'code',
    'client_id' => $clientId,
    'redirect_uri' => $redirectUri,
    'scope' => 'openid profile',
    'state' => $state,
    'code_challenge' => $challenge,
    'code_challenge_method' => 'S256'
];

header(
    'Location: https://connect.turinga.net/oauth/authorize.php?'.
    http_build_query(
        $params,
        '',
        '&',
        PHP_QUERY_RFC3986
    )
);

exit;

Callback

<?php
session_start();

$clientId = 'TU_CLIENT_ID';
$clientSecret = 'TU_CLIENT_SECRET';

$redirectUri =
    'https://ejemplo.com/auth/turinga/callback.php';

$code = (string)($_GET['code'] ?? '');
$state = (string)($_GET['state'] ?? '');

$oauth = $_SESSION['turinga_oauth'] ?? null;

unset($_SESSION['turinga_oauth']);

if (
    !is_array($oauth) ||
    empty($oauth['state']) ||
    !hash_equals(
        (string)$oauth['state'],
        $state
    )
) {
    exit('State inválido');
}

if (
    empty($oauth['created_at']) ||
    time() - (int)$oauth['created_at'] > 600
) {
    exit('Autorización expirada');
}

$ch = curl_init(
    'https://api.turinga.net/oauth/token.php'
);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'grant_type' => 'authorization_code',
        'client_id' => $clientId,
        'client_secret' => $clientSecret,
        'code' => $code,
        'redirect_uri' => $redirectUri,
        'code_verifier' => $oauth['verifier']
    ], '', '&', PHP_QUERY_RFC3986)
]);

$response = curl_exec($ch);

curl_close($ch);

$tokens = json_decode(
    (string)$response,
    true
);

if (
    !is_array($tokens) ||
    empty($tokens['access_token'])
) {
    exit('No fue posible obtener Access Token');
}

$accessToken =
    (string)$tokens['access_token'];

$refreshToken =
    (string)($tokens['refresh_token'] ?? '');

$ch = curl_init(
    'https://api.turinga.net/v1/userinfo.php'
);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.$accessToken,
        'Accept: application/json'
    ]
]);

$response = curl_exec($ch);

curl_close($ch);

$user = json_decode(
    (string)$response,
    true
);

if (
    !is_array($user) ||
    empty($user['sub'])
) {
    exit('No fue posible obtener el usuario');
}

/*
|--------------------------------------------------------------------------
| Crea la sesión de TU aplicación
|--------------------------------------------------------------------------
*/

session_regenerate_id(true);

$_SESSION['user_id'] =
    (string)$user['sub'];

$_SESSION['nick'] =
    (string)$user['nick'];

/*
|--------------------------------------------------------------------------
| IMPORTANTE
|--------------------------------------------------------------------------
|
| Si necesitas sesiones prolongadas, guarda $refreshToken de manera segura
| del lado servidor.
|--------------------------------------------------------------------------
*/

Renovar tokens

$ch = curl_init(
    'https://api.turinga.net/oauth/token.php'
);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'grant_type' => 'refresh_token',
        'client_id' => $clientId,
        'client_secret' => $clientSecret,
        'refresh_token' => $refreshToken
    ], '', '&', PHP_QUERY_RFC3986)
]);

$response = curl_exec($ch);

curl_close($ch);

$newTokens = json_decode(
    (string)$response,
    true
);

if (!empty($newTokens['refresh_token'])) {

    /*
     * Sustituye inmediatamente el Refresh Token anterior.
     */

    $refreshToken =
        $newTokens['refresh_token'];
}

Revocar un Refresh Token

$ch = curl_init(
    'https://api.turinga.net/oauth/revoke.php'
);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'client_id' => $clientId,
        'client_secret' => $clientSecret,
        'token' => $refreshToken,
        'token_type_hint' => 'refresh_token'
    ], '', '&', PHP_QUERY_RFC3986)
]);

curl_exec($ch);

curl_close($ch);