Aplicaciones conectadas y OAuth
La API de B1 admite OAuth 2.0 para que una aplicación de terceros pida a cada administrador de iglesia permiso para acceder a sus datos, sin que la iglesia comparta nunca una contraseña ni una clave de API. Una aplicación conectada es un token OAuth que un administrador de iglesia ha aprobado; revocarlo corta el acceso de la aplicación de terceros con un solo clic. Usa esta vía para conectores SaaS multiinquilino. Para una integración de una sola iglesia, es preferible usar Claves de API.
Antes de comenzar
- Un cliente OAuth debe estar registrado antes de que las iglesias puedan otorgarle acceso, ya sea por un administrador del servidor de B1 o por el propio cliente mediante registro dinámico
- Todos los endpoints OAuth están en el módulo Membership:
/membership/oauth/... - Los tokens de acceso son JWT: contienen los permisos del usuario filtrados por los permisos (scopes) otorgados
Conceptos
| Término | Significado |
|---|---|
| Cliente OAuth | La aplicación de terceros en sí, identificada por client_id y protegida por client_secret. Se registra una vez en B1 y se comparte entre todas las iglesias que la instalan. |
| Aplicación conectada | Un par (cliente, administrador de iglesia) específico donde el administrador ha concedido acceso al cliente. Cada aplicación conectada respaldada por un token de actualización OAuth. |
| Token de acceso | Un JWT de vida corta (≈ 7 días) que el cliente usa para las llamadas a la API. Tiene la misma forma que un JWT de usuario: Authorization: Bearer <jwt>. |
| Token de actualización | Una cadena opaca de larga duración (≈ 90 días) que el cliente usa para generar nuevos tokens de acceso. |
| Permiso (scope) | Restringe lo que puede hacer el token de acceso; consulta el catálogo de permisos. |
Flujos de concesión
B1 admite tres flujos OAuth, todos definidos por RFC 6749 y RFC 8628.
Código de autorización (aplicaciones web)
Úsalo cuando tu aplicación tiene un componente del lado del servidor y puede mantener el client_secret en privado.
-
Autorizar
POST /membership/oauth/authorize
Authorization: Bearer <user JWT>
Content-Type: application/json
{ "client_id": "...", "redirect_uri": "https://app.example.com/cb",
"response_type": "code", "scope": "people:read groups:read", "state": "xyz" }Los clientes públicos (sin
client_secret) también deben enviar"code_challenge": "..."y"code_challenge_method": "S256"(PKCE, RFC 7636). Solo se aceptaS256.Devuelve
{ "code": "...", "state": "xyz" }. El endpoint del código de autorización es intencionalmente un POST autenticado: tu aplicación obtiene el JWT de B1 del usuario (normalmente alojando un botón en la sesión de B1 del usuario) y lo envía como parte del paso de consentimiento. -
Intercambiar el código por tokens
POST /membership/oauth/token
Content-Type: application/json
{ "grant_type": "authorization_code", "code": "...",
"client_id": "...", "client_secret": "...", "redirect_uri": "..." }Si el paso de autorización envió un
code_challenge, incluye el"code_verifier": "..."correspondiente. Un cliente público envía el verificador y omiteclient_secret. El endpoint de token acepta cuerpos JSON o codificados como formulario (application/x-www-form-urlencoded).Devuelve la respuesta con los tokens:
{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 604800,
"created_at": 1715000000,
"refresh_token": "abc123…",
"scope": "people:read groups:read"
} -
Actualizar cuando el token de acceso está por vencer:
POST /membership/oauth/token
Content-Type: application/json
{ "grant_type": "refresh_token", "refresh_token": "...",
"client_id": "...", "client_secret": "..." }El token de actualización vence después de 90 días sin uso; si ya venció, el administrador de la iglesia vuelve a autorizar la aplicación.
Código de dispositivo (televisores, quioscos, CLI)
Úsalo cuando el dispositivo no tiene navegador. Definido por RFC 8628.
-
Solicitar un código de dispositivo
POST /membership/oauth/device/authorize
Content-Type: application/json
{ "client_id": "...", "scope": "content:read" }Devuelve el código que se muestra al usuario y el intervalo de sondeo:
{ "device_code": "...", "user_code": "WXYZ-1234",
"verification_uri": "https://app.b1.church/device",
"expires_in": 900, "interval": 5 } -
Muestra el
user_codey elverification_urial usuario. -
Sondea
/membership/oauth/tokencongrant_type=urn:ietf:params:oauth:grant-type:device_codey eldevice_code. Respuestas estándar:Error Significado authorization_pendingEl usuario todavía no ha aprobado; sigue sondeando al intervalo sugerido expired_tokenEl código de dispositivo superó su expires_in; vuelve a empezaraccess_deniedEl usuario rechazó la solicitud (ninguno — 200 OK) Aprobado; el cuerpo es un B1TokenResponse -
Una vez aprobado, guarda el
refresh_tokeny usa elaccess_tokenhasta que venza.
El SDK de B1 incluye B1OAuthClient.awaitDeviceToken(...), que ejecuta el bucle de sondeo por ti con una espera exponencial adecuada y conforme a RFC.
Token de actualización
Siempre está disponible como una solicitud independiente una vez que tienes un refresh_token:
POST /membership/oauth/token
{ "grant_type": "refresh_token", "refresh_token": "...", "client_id": "..." }
Se devuelven un nuevo access_token y un nuevo refresh_token. Los clientes públicos (sin client_secret) pueden omitir client_secret al actualizar, lo cual resulta útil para aplicaciones OAuth de móvil o escritorio que no pueden mantener un secreto.
Los tokens de actualización rotan, pero el anterior no se descarta de inmediato. Si un cliente nunca recibe la respuesta de actualización (por ejemplo, un televisor que perdió la alimentación o el Wi-Fi a mitad de la solicitud), puede reintentar con el refresh_token anterior durante hasta 7 días. El reintento solo funciona mientras el token de reemplazo no se haya usado todavía; el reemplazo no usado se descarta entonces y se emite un nuevo par. Una vez que el reemplazo ha sido actualizado, el token anterior devuelve invalid_grant. Revocar una conexión también revoca los tokens rotados que aún estén dentro de esa ventana de gracia, y la lista de aplicaciones conectadas muestra cada conexión una sola vez.
Forma del token
Un token de acceso es un JWT emitido por B1 idéntico al que obtendría un usuario de POST /membership/users/login: la misma notificación de permisos modular y el mismo comportamiento de checkAccess en todos los controladores, excepto que el arreglo de permisos se ha filtrado por los permisos otorgados en el momento de la emisión. Un token de acceso con permisos restringidos no puede hacer nada que una clave de API con permisos similares no pueda hacer, y no existe una "ruta OAuth" separada en ningún controlador: actionWrapper no sabe si quien presenta el token es una persona, una clave de API o un cliente OAuth.
Aplicaciones conectadas (para el usuario)
Desde el punto de vista de un administrador de iglesia, "Aplicaciones conectadas" es la lista de aplicaciones a las que se les ha concedido acceso a su iglesia. Cada fila es un par (OAuthClient, OAuthToken) activo.
En B1Admin: Configuración → Desarrollador → Aplicaciones conectadas muestra:
- El nombre del cliente
- Los permisos que aprobó el administrador
- La fecha en que se concedió el acceso
- Un botón Revocar
| Método y ruta | Autenticación | Propósito |
|---|---|---|
GET /membership/oauth/connections | JWT | Lista las conexiones activas del llamador (unidas con el nombre del cliente y los permisos) |
DELETE /membership/oauth/connections/:id | JWT | Revoca una conexión por el id de su token OAuth; el token deja de funcionar en la siguiente solicitud |
La lista excluye automáticamente los tokens vencidos.
Permisos y consentimiento
Las cadenas de permisos son el mismo catálogo que claves de API. Buenas prácticas para los clientes:
- Solicita los permisos más restringidos que funcionen. Las iglesias lo notan si pides
donations:writecuando solo necesitas leer personas. - Usa un token de actualización junto con tokens de acceso de vida corta. Los tokens de acceso de larga duración son más difíciles de revocar rápidamente.
- Muestra siempre los permisos otorgados al usuario en tu propia interfaz para que pueda verificar a qué dio su consentimiento.
Administración de clientes OAuth
Los clientes OAuth (las propias aplicaciones de terceros) se registran de forma global. Un cliente confidencial con client_secret lo crea un administrador del servidor de B1: para obtenerlo, contacta al equipo de ChurchApps para que te entregue un par client_id / client_secret y registre tus URI de redirección. Los clientes públicos, como los conectores MCP, pueden registrarse por sí mismos (más abajo).
Los URI de redirección registrados deben coincidir exactamente con el redirect_uri de la solicitud; una coincidencia parcial o por prefijo se rechaza.
| Método y ruta | Permiso | Descripción |
|---|---|---|
GET /membership/oauth/clients | Server.Admin | Lista todos los clientes OAuth |
GET /membership/oauth/clients/clientId/:clientId | — | Obtiene un cliente por su id público (secreto oculto) |
POST /membership/oauth/clients | Server.Admin | Crea o actualiza un cliente |
DELETE /membership/oauth/clients/:id | Server.Admin | Elimina un cliente |
Registro dinámico de clientes
POST /membership/oauth/register (público, RFC 7591) permite que un cliente como el conector MCP de claude.ai se registre por sí mismo. Se anuncia en el documento /.well-known/oauth-authorization-server de la API; consulta Servidor MCP → Descubrimiento OAuth.
POST /membership/oauth/register
Content-Type: application/json
{ "client_name": "My AI assistant", "redirect_uris": ["https://assistant.example.com/oauth/callback"], "scope": "people:read" }
Devuelve 201 con client_id, client_id_issued_at, client_name, redirect_uris, grant_types (authorization_code, refresh_token), response_types (code) y token_endpoint_auth_method: "none".
- Nunca se emite un secreto, así que el cliente debe usar PKCE en cada autorización.
redirect_urisdebe contener de 1 a 10 URLhttps, ohttpenlocalhost,127.0.0.1o[::1].client_namese recorta a 45 caracteres (predeterminado "AI assistant").- Limitado a 20 registros por hora por IP.
En la página de consentimiento de B1Admin, un cliente que se registró por sí mismo muestra un aviso que indica que se registró solo, que nunca puede hacer más de lo que puede hacer la cuenta de B1 del propio usuario, y que puede desconectarse en Configuración → Desarrollador → Aplicaciones conectadas.
Compatibilidad con SDK
El paquete @churchapps/integration-sdk envuelve cada flujo OAuth con funciones auxiliares tipadas: B1OAuthClient.exchangeCode(), .refresh(), .startDeviceFlow(), .pollDeviceToken() y .awaitDeviceToken(). Consulta el README del paquete y Webhooks para un ejemplo completo de extremo a extremo.