Tokens OAuth

Los endpoints POST /auth/token y POST /oauth2/token son equivalentes: reciben el mismo formulario application/x-www-form-urlencoded y devuelven la misma respuesta. Aceptan dos grants:

Grant	`grant_type`	Cuándo usarlo
Password grant	`password`	La integración conoce el usuario y la contraseña.
Token exchange	`urn:ietf:params:oauth:grant-type:token-exchange`	La integración ya tiene un JWT emitido por un proveedor aceptado por el entorno.

Nota

El token exchange sigue OAuth 2.0 y OAuth 2.1. El password grant forma parte de OAuth 2.0, pero no de OAuth 2.1, y puede estar deshabilitado en el entorno. Para seguir OAuth 2.1, pida al administrador del servicio que deshabilite el password grant en los métodos de autenticación de la API y use el token exchange o el Single Sign-On. Vea Compatibilidad con OAuth 2.1.

Password grant

read -r -p 'Usuario: ' API_USER
read -r -s -p 'Contraseña: ' API_PASSWORD; printf '\n'

curl -i \
  --data-urlencode 'grant_type=password' \
  --data-urlencode "username=$API_USER" \
  --data-urlencode "password=$API_PASSWORD" \
  "$API_BASE/oauth2/token"

Además de validar la contraseña, el password grant aplica al usuario las reglas de acceso del entorno.

Token exchange

El token exchange intercambia un JWT de origen por un token de acceso de la API. El único subject_token_type aceptado es urn:ietf:params:oauth:token-type:jwt.

Indique también qué proveedor configurado en el entorno debe validar el JWT. Hay dos formas:

read -r -s -p 'JWT de origen: ' SUBJECT_TOKEN; printf '\n'

curl -i \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data-urlencode "subject_token=$SUBJECT_TOKEN" \
  --data-urlencode 'provider=proveedor-jwt' \
  "$API_BASE/auth/token"

read -r -s -p 'JWT de origen: ' SUBJECT_TOKEN; printf '\n'

curl -i \
  -H 'X-STCPDIRECTLINK-JWT-ISSUER: proveedor-jwt' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data-urlencode "subject_token=$SUBJECT_TOKEN" \
  "$API_BASE/oauth2/token"

Reglas del proveedor:

el valor es el identificador del proveedor registrado por el administrador y no necesita ser igual a la claim iss del JWT;
si se envían el campo provider y la cabecera, prevalece el campo provider;
la cabecera X-STCPDIRECTLINK-JWT-ISSUER solo se usa en el token exchange y no autentica las rutas protegidas.

Token de suplantación

Las integraciones técnicas que necesitan una credencial de larga duración pueden usar un token de suplantación (impersonation) en lugar de obtener un token en cada ejecución.

El token lo genera el administrador del entorno en la interfaz de supervisión de Riversoft® STCP DirectLink, para un usuario técnico.
Contiene un identificador de sesión registrado para el usuario. En cada llamada, la API verifica ese identificador; cuando el token se reemplaza, el anterior deja de aceptarse.
Úselo como token Bearer en las rutas protegidas: Authorization: Bearer <token>.

Atención

Trate el token de suplantación como una credencial privilegiada: guárdelo en un almacén de secretos, registre el responsable, la vigencia y el alcance, defina su rotación y no lo reutilice entre entornos. No sustituye el inicio de sesión interactivo.

Respuesta

Los dos grants devuelven el mismo formato, con Cache-Control: no-store:

{
  "access_token": "<token>",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "https://api.ejemplo.com/directlink/v2"
}

Campo	Descripción
`access_token`	Token que se envía en la cabecera `Authorization: Bearer` de las rutas protegidas.
`issued_token_type`	Tipo del token emitido: token de acceso OAuth.
`token_type`	Forma de presentación del token: `Bearer`.
`expires_in`	Validez del token, en segundos. Depende de la configuración del entorno; `3600` es solo un ejemplo.
`scope`	URI de la API configurada en el entorno. No representa una lista de permisos.

Use el token como se muestra en Sesión y cierre de sesión.

Errores

Cuando el grant o el token de origen no se acepta, la API responde 400 con un cuerpo en formato OAuth:

{
  "error": 400,
  "error_description": "<motivo>",
  "error_uri": "<uri-de-la-api>"
}

El campo error es numérico e identifica la condición informada por la validación. Consulte Códigos y eventos.

Inicio de sesión local y MFA Single Sign-On