Desarrolladores
Integra con estándares. Descubre, no adivines.
Todo empieza en el documento de discovery. Usa PKCE, deja la política en el emisor y verifica las firmas con JWKS.
- Descubrir
- Autorizar
- Probar
- Verificar
- Consentir
- Emitir
- Sesión
- Revocar
Discovery: la fuente de los endpoints.
No escribas rutas a mano cuando el emisor las publica. Extracto con un emisor sintético; el documento real también lista scopes y claims.
Scopes estándar
openidprofileemailaddressorganizationrolerolesphoneoffline_accessClaims
subnameemailemail_verifiedaddressrolepermissiondepartmentorganizationphone_numberphone_number_verifiedEl perfil 4us-v1 añade los alcances heredados de clientes 4US existentes.
{
"issuer": "https://auth.example.com",
"authorization_endpoint": "https://auth.example.com/connect/authorize",
"token_endpoint": "https://auth.example.com/connect/token",
"userinfo_endpoint": "https://auth.example.com/connect/userinfo",
"end_session_endpoint": "https://auth.example.com/connect/endsession",
"introspection_endpoint": "https://auth.example.com/connect/introspect",
"revocation_endpoint": "https://auth.example.com/connect/revocation",
"device_authorization_endpoint": "https://auth.example.com/connect/deviceauthorization",
"jwks_uri": "https://auth.example.com/.well-known/jwks.json",
"response_types_supported": ["code"],
"grant_types_supported": [
"authorization_code",
"client_credentials",
"refresh_token",
"urn:ietf:params:oauth:grant-type:device_code"
],
"subject_types_supported": ["public"],
"id_token_signing_alg_values_supported": ["ES256"],
"code_challenge_methods_supported": ["S256"],
"compatibility_profile": "4us-v1"
}Referencia de endpoints.
| Método | Ruta | Acceso | Uso |
|---|---|---|---|
| GET | /.well-known/openid-configuration | Público | Discovery |
| GET | /.well-known/jwks.json | Público, caché 300 s | Llaves públicas ES256 |
| GET, POST | /connect/authorize | Sesión del navegador | Código + PKCE; consentimiento con CSRF |
| POST | /connect/token | Autenticación del cliente; 60/min por IP | Intercambio, client credentials, refresh, device |
| GET | /connect/userinfo | Bearer | Claims según scopes |
| POST | /connect/introspect | HTTP Basic | Estado de un token |
| POST | /connect/revocation | HTTP Basic | Revoca un token (y su familia) |
| POST | /connect/deviceauthorization | Autenticación del cliente | Inicio de device code |
| GET | /connect/endsession | Público | Cierre con redirect exacto |
| GET | /health/live, /health/ready | Público | Vida y preparación |
La API de administración (/api/admin/v1) es para la consola y operadores con permisos; su documento OpenAPI no se publica en producción.
Ejemplos con APIs reales.
TypeScript, React, HTTP y cURL. Valores sintéticos: no funcionan contra ningún servidor.
Los paquetes @auth4us/* son internos del repositorio de AUTH4US y aún no se publican en npm.
import { createAuth4US } from "@auth4us/core";
const client = createAuth4US({
issuer: "https://auth.example.com",
clientId: "portal-demo",
redirectUri: "https://portal.example.com/auth/callback",
scopes: ["openid", "profile", "email"],
});
await client.login({ method: "passkey" });
await client.handleCallback(window.location.href);
// La política la decide el emisor; el cliente solo pregunta.
client.hasPermission("users.read");Cliente público: código de autorización + PKCE. Sin secreto de cliente en el navegador.
import { Auth4USProvider, RequireAuth, PermissionGate } from "@auth4us/react";
export function Root() {
return (
<Auth4USProvider config={config}>
<RequireAuth>
<PermissionGate permission="users.read" fallback={<SinAcceso />}>
<Directorio />
</PermissionGate>
</RequireAuth>
</Auth4USProvider>
);
}@auth4us/react no importa el paquete visual: usa tu propia interfaz si prefieres.
GET /connect/authorize?response_type=code
&client_id=portal-demo
&redirect_uri=https%3A%2F%2Fportal.example.com%2Fauth%2Fcallback
&scope=openid%20profile%20email
&code_challenge=<S256 del verificador>
&code_challenge_method=S256
&state=<aleatorio>
Host: auth.example.comresponse_type solo admite code; el método plain de PKCE está deshabilitado.
# Descubre los endpoints en lugar de escribirlos a mano
curl -s https://auth.example.com/.well-known/openid-configuration
# Llaves públicas para verificar firmas ES256
curl -s https://auth.example.com/.well-known/jwks.jsonDiscovery y JWKS son públicos. JWKS se sirve con Cache-Control: public, max-age=300.
Estados del cliente, para animar con verdad.
El cliente expone estos estados. La escena visual solo muestra éxito cuando el estado es authenticated o un paso fue confirmado.
unknownanonymousstartingredirectingwaiting_userverifyingauthenticatedprofile_incompletemfa_requiredsession_expirederrorVeámoslo con tus aplicaciones.
Una demostración con datos sintéticos: tus flujos, tus métodos de entrada y tu modelo de tenants.