Skip to main content
Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, contáctenos.

Descripción general

Rhombus soporta OAuth 2.0 con PKCE para que puedas crear aplicaciones que inicien sesión con las credenciales existentes de Rhombus. Cuando un usuario hace clic en Iniciar sesión con Rhombus en tu aplicación, es redirigido a la Consola de Rhombus para autenticarse, y luego es devuelto a tu URI de redirección con un código de autorización de corta duración. Intercambias ese código por un access token y llamas a la API de Rhombus en nombre del usuario. Este es el mismo flujo utilizado por el Rhombus CLI oficial: rhombus login es una implementación de referencia funcional en Go que puedes leer de principio a fin. Usa esta guía para construir:
  • Herramientas CLI que se autentican mediante inicio de sesión por navegador (como el propio Rhombus CLI)
  • Aplicaciones web que permiten a los usuarios de Rhombus iniciar sesión en tu servicio
  • Paneles de administración e integraciones internas para clientes que gestionan muchas organizaciones de Rhombus
  • Aplicaciones de escritorio usando una redirección por loopback local
Lo que esta guía no es. Esta guía es para desarrolladores externos que crean aplicaciones que inician sesión a usuarios de Rhombus. Si eres un cliente de Rhombus que intenta configurar SAML SSO para tus empleados (Okta, Azure AD, Google Workspace) o SCIM para el aprovisionamiento de usuarios, consulta Aprovisionamiento SAML SSO y SCIM en su lugar: esa es una superficie distinta del flujo OAuth descrito aquí.

Cómo funciona el flujo

La superficie OAuth de Rhombus abarca tres hosts. Esta es una fuente común de confusión: tu aplicación se comunica con los tres en distintas etapas del flujo.

Antes de comenzar

Antes de comenzar, asegúrate de tener:
  • Una cuenta de Rhombus con una API key (generada en la Consola de Rhombus en Settings → API Management)
  • Una URI de redirección que tu aplicación controle: una URL HTTPS pública en producción, o http://localhost:<port>/callback para aplicaciones CLI y de escritorio
  • Familiaridad básica con el flujo de código de autorización OAuth 2.0 y PKCE (RFC 7636)

Paso 1: Registra tu aplicación

Antes de poder iniciar un flujo OAuth, Rhombus necesita conocer tu aplicación. El registro te entrega un par clientId y clientSecret. Hay dos rutas para obtener un clientId, dependiendo de la etapa de tu desarrollo:

Prototipado y desarrollo

Llama a la API submitApplication directamente con tu API key existente. Es la ruta más rápida hacia un flujo funcional en localhost. Autoservicio, inmediato.

Producción y distribución

Las aplicaciones que se entregarán a clientes o aceptarán inicios de sesión de usuarios fuera de tu propia organización deben ser revisadas por Rhombus. Contacta a tu representante de Rhombus o publica en la Comunidad de Desarrolladores para iniciar la revisión.
Las aplicaciones OAuth de producción requieren revisión de Rhombus. Puedes auto-registrar un clientId con la llamada a la API mostrada abajo para desarrollo local y pruebas, pero no distribuyas aplicaciones a usuarios finales con un clientId auto-registrado: Rhombus puede aplicar limitación de tasa o revocar el uso en producción no revisado. Inicia una revisión tan pronto como tu prototipo funcione.

Registrarse con la API

POST /api/oauth/submitApplication devuelve un clientId y clientSecret nuevos. Almacena el clientSecret de forma segura: no se puede recuperar más tarde.
Ejemplo de respuesta:
Hay endpoints adicionales disponibles para gestionar aplicaciones registradas: getAllApplicationsForOrg, getApplicationByClientId, updateApplication y deleteApplication. Consulta la Referencia de la API bajo la etiqueta OAuth.

Paso 2: Construye la URL de autorización

Rhombus usa PKCE (Proof Key for Code Exchange) para protegerse contra la interceptación de códigos de autorización. Para cada intento de inicio de sesión, genera:
  • Un code verifier: una cadena aleatoria URL-safe de 43 a 128 caracteres
  • Un code challenge: el hash SHA-256 del verifier, codificado en base64url (sin padding)
  • Un parámetro state: un valor aleatorio impredecible utilizado para prevenir CSRF
Conserva el codeVerifier y el state junto con la sesión del usuario (o, para herramientas CLI, en memoria del proceso) hasta que llegue el callback. Necesitarás ambos.
El endpoint de autorización usa los nombres de parámetros estándar de OAuth 2.0: client_id, redirect_uri, response_type=code, state, code_challenge y code_challenge_method=S256. Solo se admite S256 como método de challenge. (Por compatibilidad, la consola también acepta las formas abreviadas redirect y challenge, pero prefiere los nombres estándar mostrados arriba.)
Redirige el navegador del usuario a la URL que construiste. El usuario iniciará sesión en Rhombus y aprobará tu aplicación.

Paso 3: Maneja el callback de redirección

Después de que el usuario se autentica, Rhombus redirige a tu redirectUri con parámetros de consulta: En caso de éxito, el callback incluye: En caso de fallo, el callback incluye error (p. ej., access_denied) y error_description (detalle legible para humanos) en lugar de code.
Verifica siempre que el parámetro state coincida con lo que enviaste. Una falta de coincidencia indica un posible ataque CSRF: aborta el flujo.

Paso 4: Intercambia el código por un access token

Llama a POST https://auth-web.rhombussystems.com/oauth/token con el código de autorización y tu verifier PKCE. Esta es una solicitud de token OAuth 2.0 estándar: envía los parámetros codificados en formulario (application/x-www-form-urlencoded), no como JSON, y autentica tu cliente con su clientId/clientSecret, ya sea mediante HTTP Basic auth (client_secret_basic) o en el cuerpo de la solicitud (client_secret_post, mostrado abajo). Este es un host distinto del de la API principal: el endpoint /oauth/token reside en auth-web.rhombussystems.com.
Ejemplo de respuesta:

Paso 5: Llama a la API de Rhombus

Usa el access token con dos headers en cada llamada a la API de Rhombus:
  • x-auth-scheme: api-oauth-token
  • x-auth-access-token: <accessToken>
Esto es distinto del esquema estándar de API key (api-token + x-auth-apikey): los access tokens OAuth utilizan su propio identificador de esquema para que Rhombus pueda aplicar autorización específica de OAuth.
Si esta llamada devuelve una lista de usuarios, tu flujo OAuth funciona de extremo a extremo. El usuario se autenticó, tienes un access token y estás llamando a la API en su nombre.

Tiempo de vida del access token

El campo expires_in en la respuesta de tokens te indica cuánto tiempo (en segundos) es válido el access token (típicamente una hora). Cuando expira, la API de Rhombus devolverá un error de autenticación. Para acceso de larga duración —servicios en segundo plano, daemons, trabajos programados o cualquier cliente que no pueda volver a solicitar al usuario— emite una API key duradera usando el access token OAuth (consulta la siguiente sección) en lugar de intentar mantener una sesión OAuth refrescada. Este es el patrón que utiliza el Rhombus CLI.
Se devuelve un refresh_token junto con el access token. Puedes intercambiarlo por un nuevo access token llamando al mismo endpoint /oauth/token con grant_type=refresh_token y refresh_token=<token> (junto con la autenticación de tu cliente). Para acceso de larga duración y no interactivo —servicios en segundo plano, daemons, trabajos programados— prefiere emitir una API key duradera (consulta abajo) en lugar de mantener una sesión OAuth refrescada. Este es el patrón que utiliza el Rhombus CLI.

Emite una API key de larga duración

Una vez que un usuario ha iniciado sesión con OAuth, puedes intercambiar el access token de corta duración por una API key permanente. Esto es lo que hace rhombus login para que el CLI pueda continuar realizando llamadas a la API después de que la sesión del navegador termine. Llama a POST /api/integrations/org/submitApiTokenApplication con x-auth-scheme: api-oauth-token y x-auth-access-token: <accessToken>:
A partir de ese punto, usa la API key con los headers estándar x-auth-scheme: api-token + x-auth-apikey: no se requieren más llamadas OAuth. El CLI también soporta una variante basada en certificado (mTLS) de este flujo para implementaciones con mayor seguridad; consulta cmd/login.go para la implementación completa.
Trata las API keys emitidas como contraseñas. Son de larga duración y otorgan los mismos permisos que el usuario que las creó. Almacénalas cifradas en reposo, nunca en el control de versiones, y rota o elimina las claves no utilizadas.

Trabajar con cuentas partner

“Iniciar sesión con Rhombus” emite tokens OAuth con alcance de usuario: actúan dentro de la organización a la que pertenece el usuario. El flujo OAuth no distingue las cuentas partner, y el callback no te indica si el usuario es partner. Para escenarios partner/MSP —donde necesitas actuar sobre varias organizaciones de clientes— usa la API Partner en lugar de OAuth. Se basa en una API key con alcance de partner:
  • Envía x-auth-scheme: partner-api-token con tu API key de partner
  • Apunta a una organización cliente específica agregando su UUID en el header x-auth-org en cada llamada
Consulta Llamadas a la API Partner para el patrón completo.

Implementación de referencia

El Rhombus CLI es una referencia de producción para todo lo de esta guía. cmd/login.go recorre todo el flujo de extremo a extremo: generación de PKCE, servidor de callback local, construcción de la URL de autorización, intercambio de tokens, emisión de API key con mTLS y persistencia de credenciales. Si algo en tu implementación no funciona, compara tu comportamiento contra el CLI: es el ejemplo canónico.

Solución de problemas

Tu callback recibió un valor de state distinto al que enviaste. Verifica que estás conservando el state que generaste en el Paso 2 junto con la sesión del usuario (o en memoria para herramientas CLI) y comparándolo en el callback. Una falta de coincidencia persistente puede indicar un intento de CSRF: aborta el flujo en lugar de reintentar silenciosamente.
Causas comunes:
  • redirect_uri no coincide: el redirect_uri en el cuerpo del intercambio de tokens debe coincidir exactamente (incluyendo esquema, host, puerto y ruta) con el redirect_uri que enviaste en el Paso 2 y la URI registrada con tu aplicación OAuth.
  • code expirado: los códigos de autorización son de corta duración (segundos, no minutos). Intercámbialos inmediatamente en el callback.
  • code_verifier no genera el hash de code_challenge: verifica que estás usando SHA-256 y codificación base64url sin padding = tanto en la generación del challenge como en la transmisión del verifier.
  • Tipo de contenido o autenticación de cliente incorrectos: el endpoint de tokens espera application/x-www-form-urlencoded (no JSON), y tu clientId/clientSecret deben enviarse mediante HTTP Basic auth o en el cuerpo del formulario (client_secret_post). La solicitud de token no usa un header x-auth-scheme.
Revisa los headers. Los access tokens OAuth usan x-auth-scheme: api-oauth-token y x-auth-access-token: <token>. Usar x-auth-apikey (el header de API key) con un access token OAuth fallará: son esquemas distintos con nombres de header distintos.
El client_id que estás enviando puede no ser reconocido. Verifica que estás usando el clientId devuelto por submitApplication, no el UUID de aplicación de una respuesta diferente. Si rotaste aplicaciones, el clientId antiguo ya no es válido.

Próximos pasos

Rhombus CLI

Lee cómo el CLI oficial usa este flujo de extremo a extremo

Referencia de la API

Navega todos los endpoints disponibles una vez que tengas un access token

Límites de tasa

Comprende los límites de solicitudes antes de lanzar

Comunidad de desarrolladores

Solicita revisión de OAuth de producción y haz preguntas
Última modificación el 8 de julio de 2026