Saltar a contenido

MCP con la cuenta de la empresa#

Además de las credenciales de servicio, el servidor MCP de Empowerment Center acepta los tokens OAuth del proveedor de identidad de la organización, el mismo del inicio de sesión único. El usuario configura el asistente solo con la dirección del servidor y, la primera vez, entra con su cuenta de la empresa: no hay ningún secreto que copiar ni que caduque.

Antes de empezar#

  • El servidor MCP tiene que estar activado (véase Servidor MCP).
  • La instalación tiene que tener configurado el inicio de sesión único con un proveedor OIDC (o SAML con un emisor OIDC aparte). Véase el capítulo de seguridad.
  • ECENTER_PUBLIC_URL tiene que estar configurada: con OAuth es obligatoria y sin ella el backend no arranca.
  • Los usuarios necesitan, como siempre, Acceso por API y MCP y Acceso a Empowerment Center, y una cuenta habilitada en ECenter con el mismo login que da el proveedor.

Este modo solo existe en el servidor MCP. La API de consulta solo acepta credenciales de servicio.

Cómo funciona#

ECenter actúa como servidor de recursos de la especificación de autorización de MCP: no emite tokens ni registra clientes.

  1. El asistente llama a /api/mcp sin token.
  2. ECenter responde 401 con la cabecera WWW-Authenticate: Bearer resource_metadata="https://ecenter.example.org/.well-known/oauth-protected-resource/api/mcp", scope="ecenter.mcp".
  3. El asistente lee esos metadatos, que dicen qué proveedor emite los tokens y qué ámbito pedir.
  4. El asistente abre la página de entrada del proveedor (flujo de código con PKCE) y el usuario entra con su cuenta de la empresa.
  5. El asistente llama otra vez con el token de acceso. ECenter comprueba la firma con las claves del proveedor, el emisor, las fechas, la audiencia (que el token sea para este servidor), el cliente, el ámbito ecenter.mcp y el login.
  6. Entra el usuario de ECenter con ese login, con todos sus privilegios, por el canal MCP y con la referencia oauth:<client_id>.

El recurso es siempre ECENTER_PUBLIC_URL + /api/mcp. Un token emitido para otro recurso no se acepta.

Configurar ECenter#

ecenter.security.bearer:
  public-url: https://ecenter.example.org      # obligatoria: el recurso es esta + /api/mcp
  oauth:
    sso-provider: empresa                      # el registro SSO (spring.security.oauth2.client.registration.empresa)
    issuer-uri:                                # si el emisor de los tokens no es el del SSO
    audiences: []                              # por defecto, el recurso
    scopes: [ecenter.mcp]                      # los que tiene que traer el token
    scopes-supported: []                       # los que se anuncian, si se piden con otro nombre
    allowed-clients: []                        # client_id admitidos; vacío, cualquiera
    clock-skew: 30s
Propiedad Qué es
sso-provider El nombre del registro del inicio de sesión único. De él salen el emisor y el atributo del login (login-attribute, por defecto preferred_username).
issuer-uri El emisor de los tokens, si no es el del registro (Entra ID con tokens v1, o un inicio de sesión SAML).
audiences Las audiencias que se aceptan. Por defecto, el recurso.
scopes Los ámbitos que tiene que traer el token, en scope o scp.
scopes-supported Lo que se anuncia en los metadatos, si el proveedor pide el ámbito con otro nombre.
allowed-clients Los client_id de los asistentes admitidos. Recomendable en Entra ID.
clock-skew El desfase de reloj admitido.

Una configuración a medias no arranca: un sso-provider que no es ningún registro, public-url vacía, o audiences, allowed-clients, issuer-uri o scopes-supported sin sso-provider.

El proxy tiene que mandar al backend /.well-known/oauth-protected-resource/ además de /api/. La imagen del frontal ya lo hace. Compruébelo:

curl -i https://ecenter.example.org/.well-known/oauth-protected-resource/api/mcp

Debe responder 200 con resource, authorization_servers, scopes_supported y bearer_methods_supported. Sin OAuth configurado, 404.

Con esto, la tarjeta Conectar un asistente (MCP) de Credenciales de servicio ofrece Con la cuenta de la empresa y un fragmento de configuración solo con la dirección.

Atención

El login tiene que salir de un dato que el usuario no pueda cambiar. Si el proveedor deja editar el correo y el login es el correo, un usuario podría hacerse pasar por otro. Use el mismo dato inmutable del inicio de sesión único y del aprovisionamiento por SCIM.

Guía para Keycloak#

Keycloak no admite el parámetro resource (RFC 8707): la audiencia la pone un client scope con un Audience mapper.

  1. Use el realm del inicio de sesión único de ECenter.
  2. En Client scopes › Create client scope, cree ecenter.mcp: tipo None, protocolo OpenID Connect, Include in token scope activado. Si quiere pantalla de consentimiento, active Display on consent screen con un texto como «Consultar Empowerment Center con sus permisos».
  3. En ese client scope, Mappers › By configuration › Audience: Included Custom Audience con el recurso exacto (https://ecenter.example.org/api/mcp), Add to access token activado y Add to ID token desactivado.
  4. Cree el cliente del asistente (Clients › Create client): OpenID Connect, Client authentication desactivado (público), solo Standard flow, las Valid redirect URIs del asistente, Web origins + si el asistente corre en el navegador y, en Advanced, Proof Key for Code Exchange Code Challenge Method S256. En su pestaña Client scopes, añada ecenter.mcp como Optional o Default.
  5. Compruebe el login: por defecto es preferred_username, que tiene que coincidir con el login de ECenter.
  6. En ECenter, ecenter.security.bearer.oauth.sso-provider con el nombre del registro, y public-url.

ECenter no registra clientes: cree a mano el cliente de cada asistente y dele su client ID. Keycloak admite también el registro dinámico de clientes y, en experimental, los Client ID Metadata Documents; úselos si su organización los permite.

Guía para Microsoft Entra ID#

Entra ID no admite el parámetro resource en su punto v2, ni el registro dinámico: el ámbito se pide con el identificador de la API y cada asistente se registra a mano.

  1. La API (App registrations; puede ser la misma aplicación del inicio de sesión único): Expose an API › Application ID URI (api://<id de la aplicación>) › Add a scope ecenter.mcp, con consentimiento de administradores y usuarios. En el Manifest, requestedAccessTokenVersion: 2, para que el emisor sea el mismo del inicio de sesión.
  2. El cliente del asistente: otra App registration pública con sus Redirect URIs; en API permissions, My APIs › la de ECenter › Delegated ecenter.mcp, con Grant admin consent. Dé su client ID al asistente.

  3. ECenter:

    ecenter.security.bearer:
  public-url: https://ecenter.example.org
  oauth:
    sso-provider: empresa                                        # el registro OIDC de Entra ID (…/v2.0)
    audiences: [<id de la aplicación de la API>]                  # el aud de un token v2 es el id, no la URL
    scopes: [ecenter.mcp]                                        # como llega en scp
    scopes-supported: [api://<id de la aplicación>/ecenter.mcp]  # como lo pide el asistente
    allowed-clients: [<client ID del asistente>]

En un token v2, preferred_username es el UPN. Si el login de ECenter es otro dato, añádalo como optional claim del token de acceso y nómbrelo en el login-attribute del inicio de sesión único. Con tokens v1, el emisor es https://sts.windows.net/<tenant>/ (póngalo en issuer-uri), la audiencia es el Application ID URI y el cliente va en appid.

Errores#

HTTP code Cuándo Qué hacer
401 CREDENTIAL_REQUIRED Sin token. Lleva resource_metadata para que el asistente descubra dónde pedirlo. Normal en la primera llamada.
401 INVALID_CREDENTIAL El token no vale: firma, emisor, caducidad, audiencia, cliente no admitido o sin cuenta habilitada con ese login. No dice cuál. Mire el motivo en la auditoría (abajo).
403 INSUFFICIENT_SCOPE Todo vale menos el ámbito. El asistente tiene que volver a autorizar pidiendo ecenter.mcp.
503 IDENTITY_PROVIDER_UNAVAILABLE No se pueden leer las claves del proveedor. Lleva Retry-After. Compruebe que el backend llega al proveedor. Una clave recién rotada entra al reintentar, en 30 s como mucho.

En la auditoría, los accesos aparecen como «Entró con la cuenta de la empresa desde el cliente '…' por el servidor MCP», y los rechazos con su motivo: el token es de otro emisor, para otro recurso, ha caducado, el cliente no está admitido, le falta el ámbito o no hay una cuenta habilitada con el login del token.

Un error frecuente con Keycloak es quitar ecenter.mcp del ámbito que pide el asistente: el token llega sin la audiencia de ECenter (la pone ese client scope) y se rechaza como «para otro recurso».

Véase también#