Entrar con la cuenta de la empresa

Una empresa cliente quiere que sus empleados compren en la tienda con la cuenta corporativa, la de Microsoft 365 (Entra ID). Keycloak hace de intermediario (identity broker): la contraseña nunca pasa por la tienda. Aquí un segundo realm hace de Entra ID, para que puedas probarlo todo en tu máquina.

1. Keycloak como intermediario

2. La «empresa» de prueba

cd tienda/pasos/paso-11/infra && docker compose down -v
cd ../../paso-12/infra && docker compose up -d

El paso importa dos realms en el mismo Keycloak: tienda y corporativo, que hace el papel de Entra ID. Que sea el mismo servidor no cambia nada: tienda solo lo conoce por sus URLs, como conocería a Microsoft.

En la empresa, la tienda es una aplicación registrada: el client tienda-broker. Su redirect URI es el endpoint de broker de Keycloak, /realms/tienda/broker/<alias>/endpoint, y un mapper añade los grupos al ID token. En Entra ID sería un App registration con esa misma URL.

{
  "clientId": "tienda-broker",
  "name": "Tienda Go (vía Keycloak tienda)",
  "description": "El realm tienda entra aquí como una aplicación más, igual que haría con Entra ID",
  "enabled": true,
  "protocol": "openid-connect",
  "publicClient": false,
  "secret": "tienda-broker-secret",
  "standardFlowEnabled": true,
  "directAccessGrantsEnabled": false,
  "serviceAccountsEnabled": false,
  "redirectUris": [
    "http://localhost:8080/realms/tienda/broker/corporativo/endpoint"
  ],
  "attributes": {
    "pkce.code.challenge.method": "S256",
    "post.logout.redirect.uris": "http://localhost:8080/realms/tienda/broker/corporativo/endpoint/logout_response",
    "backchannel.logout.session.required": "true"
  },
  "protocolMappers": [
    {
      "name": "groups",
      "protocol": "openid-connect",
      "protocolMapper": "oidc-group-membership-mapper",
      "config": {
        "claim.name": "groups",
        "full.path": "false",
        "id.token.claim": "true",
        "access.token.claim": "true",
        "userinfo.token.claim": "true"
      }
    }
  ]
}

3. El proveedor de identidad en el realm tienda

En la consola: Identity providers → OpenID Connect v1.0. Con la Discovery endpoint de la empresa, Keycloak rellena las URLs solo. En el realm del paso queda así:

{
  "alias": "corporativo",
  "displayName": "Cuenta de la empresa",
  "providerId": "oidc",
  "enabled": true,
  "trustEmail": true,
  "storeToken": false,
  "firstBrokerLoginFlowAlias": "first broker login",
  "config": {
    "issuer": "http://localhost:8080/realms/corporativo",
    "authorizationUrl": "http://localhost:8080/realms/corporativo/protocol/openid-connect/auth",
    "tokenUrl": "http://localhost:8080/realms/corporativo/protocol/openid-connect/token",
    "userInfoUrl": "http://localhost:8080/realms/corporativo/protocol/openid-connect/userinfo",
    "logoutUrl": "http://localhost:8080/realms/corporativo/protocol/openid-connect/logout",
    "jwksUrl": "http://localhost:8080/realms/corporativo/protocol/openid-connect/certs",
    "useJwksUrl": "true",
    "validateSignature": "true",
    "clientId": "tienda-broker",
    "clientSecret": "tienda-broker-secret",
    "clientAuthMethod": "client_secret_basic",
    "defaultScope": "openid profile email",
    "pkceEnabled": "true",
    "pkceMethod": "S256",
    "syncMode": "FORCE",
    "backchannelSupported": "true"
  }
}

Mappers: quién es y qué puede hacer

{
  "name": "admins → admin",
  "identityProviderAlias": "corporativo",
  "identityProviderMapper": "oidc-role-idp-mapper",
  "config": {
    "syncMode": "FORCE",
    "claim": "groups",
    "claim.value": "tienda-admins",
    "role": "admin"
  }
}

Como en la lección 11, los nombres de los grupos de la empresa no se convierten en roles por sí solos: cada mapper traduce uno. Quien no esté en ningún grupo entra, pero sin cliente no puede comprar (en el ejercicio 2 lo dejas directamente fuera).

4. El cambio en Go: kc_idp_hint

Sin tocar nada, la página de login de Keycloak ya ofrece el botón «Sign in with Cuenta de la empresa». Pero es mejor que tienda-web tenga su propio botón y mande al usuario directamente a su empresa, sin pasar por una pantalla de usuario y contraseña que no va a usar. Para eso existe kc_idp_hint, un parámetro de la petición de autorización:

// handleLogin inicia el flujo: genera state, nonce y code_verifier y
// redirige el navegador a Keycloak. Con ?idp=alias (uno de los permitidos),
// Keycloak salta su página de login y va directo a ese proveedor de identidad.
func (a *Auth) handleLogin(w http.ResponseWriter, r *http.Request) {
	state := rand.Text()
	nonce := rand.Text()
	verifier := oauth2.GenerateVerifier()

	a.mu.Lock()
	a.dropExpiredLocked()
	a.pending[state] = pendingLogin{
		nonce:     nonce,
		verifier:  verifier,
		returnTo:  safeReturnTo(r.URL.Query().Get("next")),
		expiresAt: time.Now().Add(pendingTTL),
	}
	a.mu.Unlock()

	// Guardamos el state también en una cookie: así solo ESTE navegador
	// puede completar este login (protección contra login CSRF).
	http.SetCookie(w, &http.Cookie{
		Name:     stateCookie,
		Value:    state,
		Path:     "/callback",
		MaxAge:   int(pendingTTL.Seconds()),
		HttpOnly: true,
		SameSite: http.SameSiteLaxMode,
	})

	opts := []oauth2.AuthCodeOption{oidc.Nonce(nonce), oauth2.S256ChallengeOption(verifier)}
	if idp := r.URL.Query().Get("idp"); idp != "" && slices.Contains(a.idps, idp) {
		opts = append(opts, oauth2.SetAuthURLParam("kc_idp_hint", idp))
	}
	authURL := a.oauth.AuthCodeURL(state, opts...)
	http.Redirect(w, r, authURL, http.StatusFound)
}

La lista de proveedores permitidos (OIDC_IDP_HINTS, por defecto corporativo) evita que alguien construya enlaces /login?idp=… hacia proveedores que no quieres ofrecer desde esta app. En la plantilla basta un enlace:

<a class="btn ghost" href="/login?idp=corporativo">Cuenta de la empresa</a>
<a class="btn" href="/login">Entrar</a>

5. Probarlo

Arranca api, web y facturacion del paso 12 y pulsa «Cuenta de la empresa». Entra como lucia / Lucia-Empresa-2026! y compra algo. Su access token (salida real):

{
  "iss": "http://localhost:8080/realms/tienda",
  "sub": "be2dd43b-106e-4966-bf72-604e4be0499a",
  "preferred_username": "lucia@empresa.test",
  "name": "Lucía Marín",
  "email": "lucia@empresa.test",
  "email_verified": true,
  "realm_access": { "roles": ["cliente", "offline_access", "uma_authorization", "default-roles-tienda"] },
  "aud": ["facturacion", "api-pedidos", "account"]
}

El emisor es tienda, no la empresa: tus servicios siguen confiando en un único Keycloak. El sub es el de la cuenta local que Keycloak creó en el primer login, enlazada a la de la empresa:

Entra ahora como jorge: ve Admin, porque está en tienda-admins. api-pedidos no ha cambiado ni una línea.

admin-tool: de dónde viene cada cuenta

La columna ORIGEN de la lección 11 solo miraba federationLink, que usan los directorios LDAP. Las cuentas creadas por un proveedor de identidad no lo tienen: su vínculo está en federated identities. Users ahora lo consulta para las cuentas que parecían locales:

if info.Origin == "local" {
	// Las cuentas creadas por un proveedor de identidad (lección 12) no
	// tienen federationLink: su vínculo está en federated-identity.
	links, err := a.kc.GetUserFederatedIdentities(ctx, a.token, a.realm, info.ID)
	if err != nil {
		return nil, explain(err)
	}
	if len(links) > 0 {
		info.Origin = gocloak.PString(links[0].IdentityProvider)
	}
}

go run ./cmd/admin usuarios
# USUARIO             ORIGEN       NOMBRE         EMAIL               ACTIVO  ROLES          GRUPOS
# ana                 local        Ana Cliente    ana@tienda.test     true    cliente
# carlos              local        Carlos Admin   carlos@tienda.test  true    admin,cliente
# diego               AD           Diego Soporte  diego@tienda.local  true    admin,cliente
# jorge@empresa.test  corporativo  Jorge Paz      jorge@empresa.test  true    admin,cliente
# lucia@empresa.test  corporativo  Lucía Marín    lucia@empresa.test  true    cliente
# sofia               AD           Sofia Ventas   sofia@tienda.local  true    cliente

Las cuentas de la empresa solo aparecen después de su primer login: a diferencia de un directorio LDAP, un proveedor OIDC no se puede «sincronizar» por adelantado.

6. Quién manda (probado)

7. Con Entra ID de verdad

1. En Entra ID, App registrations → New registration, con redirect URI (Web) https://tu-keycloak/realms/tienda/broker/entra/endpoint (entra es el alias que le darás). Crea un client secret.
2. En Keycloak, un proveedor OpenID Connect con la Discovery endpoint https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration, el Application (client) ID y el secreto.
3. Los grupos llegan como GUID. El claim groups de Entra ID lleva por defecto los ID de objeto de los grupos, no sus nombres, y si un usuario está en más de 200 grupos no llega (en su lugar viene un claim de «overage»). Por eso suele ser mejor definir App roles en el App registration: llegan en el claim roles con el nombre que les pongas, y el mapper Claim to Role queda igual que aquí, con roles en lugar de groups.
4. Revisa qué claim trae el correo en tu tenant (email no siempre viene; preferred_username suele ser el UPN) y ajusta el mapper de usuario.

Para tu código Go, nada de esto cambia: el botón sigue enviando kc_idp_hint=entra y los tokens los sigue emitiendo tu Keycloak.

Ejercicios

The ID token issued by the identity provider does not match the configured essential claim. Please contact your administrator.

Errores comunes