Inici de sessió amb Unidy.

1. 1

   Registra el teu web

   A l'app d'Unidy, el compte d'empresa aprovat de la teva empresa a Unidy obre Desenvolupadors i hi afegeix un web: el nom, l'adreça web, la política de privacitat i, si vols, un logo. Després, les dades (scopes) que el web pot demanar. Qualsevol petició amb un altre scope es rebutja.

   Tria una sola vegada com inicia la sessió de la gent:

   • Amb un servidor: reps un client id i un secret, que es mostra una sola vegada. El servidor bescanvia el codi.
   • Al navegador: un client id i cap secret. PKCE amb S256 és obligatori, i només els teus orígens de redirecció poden cridar el token endpoint.
   • Adreces de redirecció: fins a 10, totes https en un sol host. Per a la teva pròpia màquina, registra un segon web amb adreces http://localhost.
2. 2

   Llegeix el document de descobriment

   Llegeix-ne els endpoints en lloc d'escriure'ls al codi.

   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

   Envia la petició d'autorització

   Genera un verificador aleatori i guarda'l, juntament amb un state i un nonce aleatoris, fins que la persona torni. Envia el repte 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); // keep verifier, state and nonce in sessionStorage first

4. 4

   Bescanvia el codi per tokens

   A la teva pàgina de redirecció, comprova que el state coincideix amb el que has enviat, una sola vegada. Després bescanvia el codi. Un servidor s'autentica amb el seu secret (HTTP Basic). Un web al navegador envia el client_id, sense secret.

   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 l'ID token

   No et refiïs mai d'un ID token que no hagis comprovat. La teva llibreria d'OpenID Connect ho fa tot:

   • La signatura, amb la clau de jwks_uri que coincideix amb el kid del token.
   • iss és igual a l'issuer del document de descobriment.
   • aud conté el teu client id.
   • exp encara és en el futur.
   • nonce és igual al que has enviat.
6. 6

   Identifica la persona

   Identifica el compte pel sub. És privat del teu web: la mateixa persona té un sub diferent a qualsevol altre lloc, així que ningú no la pot seguir per internet amb aquest valor.

   Fes servir unidy_id per mostrar qui ha iniciat la sessió. És l'ID d'Unidy amb què es presenta la persona, i el pot personalitzar, així que no serveix com a clau.

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

7. 7

   Crea la teva pròpia sessió

   Busca el sub als teus registres. Unidy no et diu mai si la persona és nova: si no tens cap compte per a aquest sub, crea'n un. Després obre la teva sessió de sempre.

8. 8

   Opcional: llegeix les dades amb l'access token

   GET /api/v1/me respon amb el sub i cada dada que la persona ha acceptat compartir i que encara permet. Després de Permet una vegada, o si la persona desconnecta el teu web, respon not_linked.

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

API

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

Configura l'SDK. Crida-la primer a cada pàgina.

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

Dibuixa el botó oficial Continua amb Unidy.

Unidy.signIn({ scopes, prompt })

Envia la persona a Unidy amb PKCE (S256), un state i un nonce.

Unidy.handleRedirect()

Comprova el state, bescanvia el codi, valida l'ID token i es resol amb { user, kind, scopes }.

Unidy.user()

Els claims de la persona que ha iniciat la sessió, o null.

Unidy.details()

Les dades que la persona ha acceptat, de /api/v1/me.

Unidy.signOut()

Oblida els tokens i revoca el refresh token a Unidy.

Unidy.UnidyError

Cada error, amb un codi com access_denied, not_linked o invalid_token.