Saltar al contenido principal

OAuth de Steam y OAuth de Telegram con Casdoor: Añadir inicios de sesión sociales no estándar a través de OIDC

· 11 min de lectura
Yang Luo
Yang Luo
Casdoor Maintainer

No existe "OAuth de Steam": Steam inicia sesión a los usuarios con OpenID 2.0 y le proporciona un SteamID de 64 bits, nada más. El clásico Login Widget de Telegram tampoco es OAuth: entrega a su página un conjunto de campos de usuario más un hash HMAC-SHA256 que usted verifica con su token de bot. Telegram ahora también ejecuta un proveedor real de OpenID Connect en oauth.telegram.org. Si coloca Casdoor entre su aplicación y estos proveedores, Casdoor realiza las verificaciones específicas del protocolo y su aplicación solo habla OpenID Connect con Casdoor, de la misma manera que lo haría con Google o GitHub.

Los proveedores de un vistazo​

ProveedorProtocoloQué identifica al usuario¿Correo electrónico disponible?Tipo de proveedor de Casdoor
SteamOpenID 2.0 en https://steamcommunity.com/openid/login, además de la Steam Web API para el perfilSteamID64, tomado de la ID reclamada https://steamcommunity.com/openid/id/<steamid>NoSteam
Telegram (Login Widget)Datos del widget firmados, HMAC-SHA256 con clave derivada del SHA-256 del token del botid de usuario de TelegramNoTelegram
Telegram (OpenID Connect)Flujo de código de autorización OIDC con PKCE en https://oauth.telegram.orgClaim sub del token de IDSin claim de correo electrónico; teléfono con el scope phoneCustom
X (Twitter)Código de autorización OAuth 2.0 con PKCEID de usuario de X desde /2/users/meNo con los scopes predeterminados de CasdoorTwitter
FacebookCódigo de autorización OAuth 2.0ID de usuario con alcance de la appSolo si el perfil tiene un correo electrónico principal válidoFacebook

El resto de esta publicación explica qué devuelve realmente cada protocolo y qué hace Casdoor con ello.

Steam: OpenID 2.0, sin OAuth​

Las páginas de desarrolladores de Steam describen Steam como un proveedor de OpenID: su sitio envía al usuario a Steam, y Steam devuelve una ID reclamada del formato https://steamcommunity.com/openid/id/<steamid>. El número al final es el SteamID de 64 bits del usuario. No hay código de autorización, ni token de acceso, ni scopes, ni correo electrónico: ni la respuesta de OpenID ni el perfil de la Web API contienen uno.

Por eso las búsquedas de "steam oauth" no llevan a ninguna parte útil: el protocolo es OpenID 2.0, el predecesor de OpenID Connect, por lo que una librería cliente de OAuth 2.0 u OIDC no puede hablar directamente con Steam.

Lo que Casdoor hace para un inicio de sesión con Steam:

  1. La página de inicio de sesión de Casdoor construye una solicitud checkid_setup de OpenID 2.0 a https://steamcommunity.com/openid/login, con openid.realm establecido en el origen de Casdoor y openid.return_to establecido en la página /callback de Casdoor.
  2. Cuando Steam redirige de vuelta, Casdoor vuelve a enviar los campos firmados a Steam con openid.mode=check_authentication. Solo si Steam responde is_valid:true continúa. También verifica que openid.claimed_id coincida con el patrón steamcommunity.com/openid/id/<digits> y extrae el SteamID de ella.
  3. Con la clave de la Steam Web API que introduce como Client secret del proveedor, Casdoor llama a ISteamUser/GetPlayerSummaries para obtener el nombre de usuario y el avatar.

El usuario resultante de Casdoor tiene el SteamID64 como nombre de usuario, el nombre de perfil de Steam como nombre para mostrar y el avatar de Steam. El campo de correo electrónico permanece vacío. Casdoor elimina deliberadamente el texto de marcador de posición que la biblioteca subyacente coloca allí. Si su aplicación necesita una dirección de correo electrónico, recójala después del registro.

La configuración toma dos minutos: registre una clave API Web para su dominio de Casdoor en la página de claves de Steam, cree un proveedor de tipo Steam y pegue la clave como secreto de cliente. La guía del proveedor de Steam tiene los pasos.

Telegram: el Widget de inicio de sesión y su verificación HMAC​

El inicio de sesión clásico de Telegram es un widget de JavaScript. Usted crea un bot con @BotFather, vincula su dominio a él con /setdomain, e incrusta el widget. Cuando el usuario confirma en Telegram, el widget o bien redirige a la URL en data-auth-url o llama a una función de JavaScript, pasando id, first_name, last_name, username, photo_url, auth_date y hash.

Nada en esa carga útil es un token. Cualquiera puede escribir esos campos en una URL, por lo que el servidor debe verificar el hash. La verificación documentada de Telegram funciona así:

data_check_string = all received fields except hash,
                    as key=value, sorted by key, joined with "\n"
secret_key        = SHA256(bot_token)
valid             = hex(HMAC_SHA256(data_check_string, secret_key)) == hash

Telegram también le indica que verifique auth_date para que no se puedan reproducir datos antiguos, pero deja la ventana de tiempo a su criterio.

En Casdoor, el tipo de proveedor Telegram toma el nombre de usuario del bot (sin @) como Client ID y el token del bot como Client secret. Cuando un usuario hace clic en el botón de Telegram, Casdoor abre su propia página /telegram-login, que carga telegram-widget.js desde telegram.org con el nombre de usuario de su bot y apunta data-auth-url de vuelta al /callback de Casdoor. El callback recopila los campos y el backend de Casdoor entonces:

  • reconstruye la cadena de verificación de datos desde cada campo excepto hash, la ordena y compara el HMAC-SHA256 contra hash usando SHA256(bot token) como clave;
  • rechaza los datos si auth_date tiene más de 24 horas de antigüedad;
  • usa el id numérico de Telegram como identidad, el username como nombre de usuario, el nombre y apellido como nombre para mostrar, y photo_url como avatar.

Los nombres de usuario de Telegram son opcionales. Cuando un usuario no tiene uno, Casdoor genera telegram_<id>, que permanece igual en cada inicio de sesión. El widget nunca envía una dirección de correo electrónico ni un número de teléfono, por lo que un usuario solo de Telegram en Casdoor no tiene ninguno. Consulte la guía del proveedor de Telegram para los pasos de BotFather.

Telegram ahora ofrece OpenID Connect también​

La página "Log In With Telegram" de Telegram ahora documenta un flujo estándar de OpenID Connect, y la documentación antigua del widget iframe se ha movido a una página de archivo. Los hechos de la documentación de Telegram:

  • Documento de descubrimiento: https://oauth.telegram.org/.well-known/openid-configuration. Endpoint de autorización https://oauth.telegram.org/auth, endpoint de token https://oauth.telegram.org/token, claves en https://oauth.telegram.org/.well-known/jwks.json.
  • En @BotFather, abra la configuración del Login Widget de su bot, registre las URLs permitidas (orígenes y URI de redirección exactas), y obtenga un ID de cliente y un secreto de cliente.
  • Flujo de código de autorización, PKCE con S256 recomendado. La solicitud de token usa autenticación HTTP Basic con el ID de cliente y el secreto.
  • Ámbitos (Scopes): openid es obligatorio; profile añade el nombre, preferred_username y picture; phone añade phone_number con el consentimiento del usuario. No hay reclamo de correo electrónico.
  • No hay endpoint UserInfo. Todos los datos del usuario están en el token de ID, cuyo iss es https://oauth.telegram.org y cuyo aud es el ID de su bot.

Puede conectar este flujo con un proveedor OAuth personalizado de Casdoor. Establezca Auth URL y Token URL a los endpoints anteriores, establezca Scope a openid profile (añada phone si lo necesita), active Enable PKCE, y deje UserInfo URL vacío. Registre https://<your-casdoor-host>/callback de Casdoor como una URL permitida en BotFather. Sin una URL de UserInfo, Casdoor toma al usuario del token de ID en la respuesta del token: requiere sub, rechaza un token expirado, y verifica que aud contenga el ID de cliente. Sin un mapeo de usuario, sub se convierte en el ID de usuario, preferred_username en el nombre de usuario, name en el nombre para mostrar y picture en el avatar, y phone_number rellena el teléfono. La página de inicio de sesión de Casdoor reconoce un proveedor personalizado cuya URL de autenticación apunta a oauth.telegram.org y mantiene corto el state de OAuth para ello.

Tenga en cuenta que un usuario de Telegram que inicia sesión mediante el widget y la misma persona que inicia sesión mediante OIDC no son automáticamente el mismo usuario de Casdoor. La identidad del widget es el id numérico, mientras que la identidad de OIDC es sub, y los propios ejemplos de Telegram muestran valores diferentes para ambos. Elija un método por aplicación.

X (Twitter) y Facebook​

Estos dos son OAuth 2.0 ordinarios, pero cada uno tiene un detalle que vale la pena conocer.

X requiere un desafío PKCE en su URL de autorización OAuth 2.0. El tipo Twitter de Casdoor genera un nuevo verificador de código para cada inicio de sesión, envía el desafío S256, y pasa el verificador en el intercambio de token, por lo que no hay nada que configurar más allá del ID de cliente y el secreto. Casdoor solicita los ámbitos users.read tweet.read y lee al usuario desde /2/users/me, lo que da el ID de usuario, el alias (handle) y el nombre para mostrar. No solicita un campo de correo electrónico, así que planifique para usuarios de X sin dirección de correo electrónico. La guía del proveedor de Twitter cubre la configuración de la aplicación.

Facebook devuelve un ID de usuario con ámbito de aplicación: la misma persona tiene un ID diferente en cada aplicación de Facebook, por lo que cambiar a una nueva aplicación de Facebook significa que sus usuarios no coincidirán con sus registros antiguos a menos que los vincule por correo electrónico. Casdoor solicita email,public_profile y lee id, name, picture y email de la Graph API. Facebook omite email cuando el perfil no tiene una dirección válida. Consulte la guía del proveedor de Facebook.

Cómo ve todo esto su aplicación: OIDC simple​

Su aplicación nunca se comunica con Steam, Telegram, X o Facebook. Es un cliente OIDC de Casdoor, configurado una sola vez con el emisor de Casdoor, https://<your-casdoor-host>/.well-known/openid-configuration. Añade los proveedores sociales a la aplicación de Casdoor en su pestaña Providers, y sus botones aparecen en la página de inicio de sesión de Casdoor.

Después de cualquiera de estos inicios de sesión, Casdoor busca o crea un usuario de Casdoor y finaliza el flujo normal de código de autorización con su aplicación. El token ID que recibe su aplicación está firmado por Casdoor, y su sub es el ID del usuario de Casdoor, no el SteamID ni el ID de Telegram. Por lo tanto, su aplicación no necesita ninguna biblioteca OpenID 2.0, ningún código HMAC, ninguna peculiaridad de PKCE por proveedor, ni ningún caso especial para usuarios sin correo electrónico. El ID original del proveedor se almacena en el usuario de Casdoor, por ejemplo, en el campo steam o telegram, si alguna vez lo necesita.

Hay algunas cosas que debe tener en cuenta:

  • Vinculación de cuentas. Casdoor vincula un inicio de sesión social a un usuario existente mediante correo electrónico verificado, teléfono verificado o nombre de usuario, en el orden establecido por la regla de vinculación de la aplicación. Steam y el widget basado en Telegram no proporcionan ni correo electrónico ni teléfono, por lo que crean un usuario separado a menos que el usuario vincule el proveedor desde una cuenta que ya haya iniciado sesión. Consulte cómo Casdoor vincula cuentas.
  • Campos adicionales de perfil. Los proveedores que pasan datos brutos, como el tipo Steam basado en Goth y los proveedores personalizados, pueden rellenar más campos de usuario mediante asignación de usuario.
  • El lado del cliente. Cualquier biblioteca estándar funciona con Casdoor. Conectar un cliente OIDC estándar enumera los endpoints, y la publicación SSO con Spring Boot y OIDC muestra una aplicación completa.

Referencias​