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>/callbackpara 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 parclientId 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.
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.
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
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.
Paso 3: Maneja el callback de redirección
Después de que el usuario se autentica, Rhombus redirige a turedirectUri 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.
Paso 4: Intercambia el código por un access token
Llama aPOST 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.
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-tokenx-auth-access-token: <accessToken>
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 campoexpires_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 hacerhombus 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>:
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.
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-tokencon tu API key de partner - Apunta a una organización cliente específica agregando su UUID en el header
x-auth-orgen cada llamada
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
state no coincide en el callback
state no coincide en el callback
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.El intercambio de tokens devuelve HTTP 400 o una respuesta con `error`
El intercambio de tokens devuelve HTTP 400 o una respuesta con `error`
Causas comunes:
redirect_urino coincide: elredirect_urien el cuerpo del intercambio de tokens debe coincidir exactamente (incluyendo esquema, host, puerto y ruta) con elredirect_urique enviaste en el Paso 2 y la URI registrada con tu aplicación OAuth.codeexpirado: los códigos de autorización son de corta duración (segundos, no minutos). Intercámbialos inmediatamente en el callback.code_verifierno genera el hash decode_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 tuclientId/clientSecretdeben enviarse mediante HTTP Basic auth o en el cuerpo del formulario (client_secret_post). La solicitud de token no usa un headerx-auth-scheme.
Las llamadas a la API devuelven 401 con un access token válido
Las llamadas a la API devuelven 401 con un access token válido
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.La redirección termina en la página de inicio de sesión de la consola otra vez sin código
La redirección termina en la página de inicio de sesión de la consola otra vez sin código
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