Inicio de sesión con Unidy.

1. 1

   Registra tu web

   En la app de Unidy, la cuenta de empresa aprobada de tu compañía en Unidy abre Desarrolladores y añade una web: su nombre, su dirección web, su política de privacidad y, si quieres, un logo. Después, los datos (scopes) que la web puede pedir. Cualquier petición con otro scope se rechaza.

   Elige, una sola vez, cómo inicia sesión la gente en tu web:

   • Con servidor: recibes un client id y un secreto, que solo se muestra una vez. El servidor hace el intercambio del código.
   • En el navegador: un client id y ningún secreto. PKCE con S256 es obligatorio, y solo los orígenes de tus direcciones de retorno pueden llamar al endpoint de tokens.
   • Direcciones de retorno: hasta 10, todas https y en un mismo host. Para desarrollar en local, registra una segunda web con direcciones http://localhost.
2. 2

   Lee el documento de descubrimiento

   Toma los endpoints de ahí en vez de escribirlos a mano.

   curl https://id.unidy.com/.well-known/openid-configuration
   
   {
     "authorization_endpoint": "https://id.unidy.com/oauth2/auth",
     "token_endpoint": "https://id.unidy.com/oauth2/token",
     "userinfo_endpoint": "https://id.unidy.com/userinfo",
     "jwks_uri": "https://id.unidy.com/.well-known/jwks.json",
     …
   }

3. 3

   Envía la petición de autorización

   Genera un verificador aleatorio y guárdalo, junto con un state y un nonce aleatorios, hasta que la persona vuelva. Envía el reto SHA-256 del verificador.

   const base64url = (bytes) =>
     btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
   const random = () => base64url(crypto.getRandomValues(new Uint8Array(32)));
   
   const config = await (await fetch('https://id.unidy.com/.well-known/openid-configuration')).json();
   const verifier = random(), state = random(), nonce = random();
   const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
   
   const url = new URL(config.authorization_endpoint);
   url.search = new URLSearchParams({
     response_type: 'code',
     client_id: 'YOUR_CLIENT_ID',
     redirect_uri: 'https://shop.example/callback',
     scope: 'openid profile unidy_id email',
     state,
     nonce,
     code_challenge: base64url(new Uint8Array(digest)),
     code_challenge_method: 'S256',
   });
   location.assign(url); // antes, guarda verifier, state y nonce en sessionStorage

4. 4

   Cambia el código por tokens

   En tu página de retorno, comprueba que el state es el que enviaste, y solo una vez. Después cambia el código. Un servidor se autentica con su secreto (HTTP Basic). Una web en el navegador envía el client_id, sin secreto.

   curl -X POST https://id.unidy.com/oauth2/token \
     -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
     -d grant_type=authorization_code \
     -d code=THE_CODE \
     -d redirect_uri=https://shop.example/callback \
     -d code_verifier=THE_VERIFIER
   
   { "access_token": "…", "id_token": "…", "token_type": "bearer", "expires_in": …, "scope": "openid profile unidy_id email" }

5. 5

   Valida el ID token

   No te fíes de un ID token sin comprobarlo. Tu librería de OpenID Connect lo hace todo:

   • La firma, con la clave de jwks_uri que coincide con el kid del token.
   • iss coincide con el emisor del documento de descubrimiento.
   • aud contiene tu client id.
   • exp aún no ha pasado.
   • nonce es el que enviaste.
6. 6

   Identifica a la persona

   Usa sub como clave de la cuenta. Es privado para tu web: la misma persona tiene otro sub en cualquier otro sitio, así que nadie puede rastrearla por internet con él.

   Usa unidy_id para mostrar quién ha iniciado sesión. Es el ID de Unidy con el que la persona se presenta, y lo puede personalizar, así que no sirve como clave.

   {
     "sub": "8b1c2f…e40f",
     "aud": ["YOUR_CLIENT_ID"],
     "nonce": "…",
     "name": "Ana Ruiz",
     "unidy_id": "ana.ruiz",
     "email": "ana.compras@mail.example",
     "email_verified": false
   }

7. 7

   Crea tu propia sesión

   Busca el sub en tus registros. Unidy nunca te dice si la persona es nueva: si no tienes ninguna cuenta con ese sub, créala. Después inicia la sesión como siempre.

8. 8

   Opcional: lee los datos con el access token

   GET /api/v1/me devuelve el sub y cada dato que la persona aceptó compartir y sigue permitiendo. Tras Permitir una vez, o si la persona desconecta tu web, devuelve not_linked.

   curl https://id.unidy.com/api/v1/me \
     -H 'Authorization: Bearer ACCESS_TOKEN'
   
   { "sub": "8b1c2f…e40f", "name": "Ana Ruiz", "email": "ana.compras@mail.example", "email_verified": false }

API

Unidy.init({ clientId, redirectUri, scopes, issuer, storage })

Inicializa el SDK. Llámalo antes que nada en cada página.

Unidy.button(element, { kind, theme, lang })

Muestra el botón oficial de Continuar con Unidy.

Unidy.signIn({ scopes, prompt })

Envía a la persona a Unidy con PKCE (S256), un state y un nonce.

Unidy.handleRedirect()

Comprueba el state, cambia el código, valida el ID token y devuelve { user, kind, scopes }.

Unidy.user()

Los claims de la persona que ha iniciado sesión, o null.

Unidy.details()

Los datos que la persona aceptó compartir, desde /api/v1/me.

Unidy.signOut()

Borra los tokens y revoca el refresh token en Unidy.

Unidy.UnidyError

Todos los errores, con un código como access_denied, not_linked o invalid_token.