Från produkterna

För den som driftar: en produkt öppnar dokumentationen inloggad som kunden, eller visar en sida inbäddad.

En produkt kan öppna dokumentationen på två sätt:

Med en länk som öppnar dokumentationen i webbläsaren, inloggad som kunden. Läsaren behöver inget mejl och inget lösenord.
Inbäddad: en sida, eller en del av en sida, visas i en ram inne i produkten. Där visas det som alla får läsa, och i sajter där det är påslaget också det kunden får läsa.

Båda är avstängda från början. Den som driftar installationen slår på dem. Kundens AI-klient kan också läsa, i sajter där det är påslaget (se AI-klient för kunder).

Länken från produkten

Vad det är

Varje kund (en organisation) har ett eget konto, kundkontot. En produkt som vet kundens nyckel gör en länk när användaren klickar. Länken loggar in kundkontot och öppnar rätt sida. Den gäller i två minuter och bara en gång, och den syns inte i webbläsarens adressfält efteråt.

Kundkontot läser samma sajter som kundens e-postdomäner i domänregistret (se Åtkomst, punkten Domänregistret). Det kan inte redigera något.

Så slår du på det

Sätt product_access: {enabled: true} i user/config/plugins/mail-auth.yaml på servern.
Skapa kunden, från webbroten (public/):
```
php bin/plugin mail-auth customer add kund-ab --domain example.com
```
Kommandot skriver ut kundens nyckel en gång. Lämna den till den som driftar produkten, på ett säkert sätt. Den visas aldrig igen.
Se till att domänen står för rätt sajter i domänregistret, och att de sajterna har Domänregistret under Vem som får läsa sajten.

Nycklar och spärr

Vad	Kommando
Ny nyckel; den gamla gäller 7 dagar till	`php bin/plugin mail-auth customer rotate kund-ab`
Ny nyckel; den gamla slutar gälla direkt	`php bin/plugin mail-auth customer rotate kund-ab --now`
Spärra en nyckel direkt	`php bin/plugin mail-auth customer revoke-key kund-ab k1`
Stäng av kunden (alla inloggade loggas ut)	`php bin/plugin mail-auth customer disable kund-ab`
Slå på kunden igen	`php bin/plugin mail-auth customer enable kund-ab`
Lista kunder och nycklar (aldrig själva nyckeln)	`php bin/plugin mail-auth customer list`

En läckt nyckel: spärra den, eller byt med --now. Den som hade nyckeln kunde logga in som hela kunden.
Felaktiga länkar från samma adress spärras en stund efter 20 försök.
Loggen (logs/grav.log) har en rad för varje inloggning och varje avslag, utan nycklar.
Hälsokontrollen säger till om en nyckel inte har använts på länge eller borde ha spärrats.

För den som bygger produkten

Hur länken räknas fram står i pluginet mail-auth, i dess README.md → The link (for whoever builds a product). Nyckeln ska ligga i produktens konfiguration på servern, aldrig i webbläsaren.

AI-klient för kunder

Vad det är

En kund kan koppla sin AI-klient till dokumentationen, till exempel för att låta den söka svar om produkten. Klienten loggar in som kundkontot. Den får bara läsa: söka, lista sidor och läsa sidor. Vad kunden gör står i AI-klient.

Per sajt, av från början. Du väljer vilka sajter en kunds klient får läsa. Klienten ser ändå bara det kundkontot får läsa.
Kunden börjar i produkten. Kunden öppnar dokumentationen med produktens länk, och tillåter sedan klienten i samma webbläsare.
Bunden till nyckeln. Spärrar du nyckeln eller stänger av kunden, slutar klienten fungera vid nästa anrop. Byter du nyckel med överlapp, slutar den när den gamla nyckeln slutar gälla.
Skälet: kundens organisation delar ett konto, och klienter hämtar mycket. Därför bara läsning, bara valda sajter och en lägre spärr.

Så slår du på det

Länken från produkten och AI-klienter (se AI-klient, För den som driftar) måste vara påslagna. Sedan, för varje sajt:

Öppna sajtens Admin: /<sajt>/admin, eller /admin för grundsajten.
Välj Plugins, Mail Auth.
Slå på AI clients of customers in this site och spara.

Inställningen gäller bara den sajten. En annan sajt ärver den aldrig, inte heller från grundsajten.
Calls a minute for a customer's AI client är spärren för en kunds anslutning, 30 anrop i minuten från början. Den kan bara sänka spärren för alla, aldrig höja den.
Loggen får en rad när en kund kopplar in en klient: kunden, nyckelns id och sajten.

Inbäddning

Vad som visas

Produkten visar sidan med adressen <sidan>?embed=1 i en ram (iframe). En del av sidan: lägg till &section=<rubrikens id>. Id:t är det som står efter # när du klickar på rubriken i innehållsförteckningen.

Bara sidan: ingen meny, ingen sidfot och inga knappar för att redigera.
Länkar till andra sidor öppnas i ramen. Länkar till andra webbplatser och till filer öppnas i en ny flik.
Utan inloggning visas bara det som alla får läsa. En skyddad sida visar i stället en knapp, Öppna dokumentationen, som öppnar sidan i en ny flik där läsaren kan logga in. Vill produkten visa skyddade sidor i ramen, se Skyddade sidor i ramen.

Vilka produkter som får visa sidorna

Webbläsaren visar sidorna bara i ramar på de adresser som står i listan. Listan gäller hela installationen; en sajt kan inte lägga till något själv.

Öppna grundsajtens Admin: Themes, temat, fliken Embed mode.
Slå på Embed mode.
Skriv produkternas adresser i Origins that may frame the embed view, med kommatecken emellan: https://app.example.com, https://*.example.org. Bara schema, värd och eventuellt port, ingen sökväg. *. tar med alla underdomäner.
Spara.

Utan listan får ingen annan webbplats visa sidorna i en ram.
Är det avstängt ändras ingenting: sidorna skickar inga nya headers, och ?embed=1 är en vanlig sida.
Hälsokontrollen säger till om listan är tom eller har en adress som inte går att använda.

Skyddade sidor i ramen

Vad: ramen visar också de sidor kunden får läsa, med bilder och filer. Samma sidor som kundkontot läser med länken ovan.

Hur det går till: produkten öppnar ramen med sin länk, gjord för ramen. Ramen får då en egen kaka som bara gäller i den produktens ram. Kakan loggar inte in någon i dokumentationen. Den kan bara visa sidor i ramen, aldrig ändra något.

När ramen visar knappen i stället:

sajten har inte slagit på det;
kunden är avstängd, eller nyckeln är spärrad eller har slutat gälla. Det gäller direkt, också i en ram som redan är öppen;
ingen har använt ramen på en stund (samma tid som en inloggning), eller det har gått 8 timmar. Produkten öppnar ramen igen med en ny länk;
webbläsaren tar inte emot kakan. Safari med strikta inställningar gör det inte.

Filer på en skyddad sida öppnas i ramen, inte i en ny flik. I en ny flik finns inte kakan.

Så slår du på det: länken från produkten och inbäddningen (ovan) måste vara påslagna. Sedan, för varje sajt:

Öppna sajtens Admin: /<sajt>/admin, eller /admin för grundsajten.
Välj Plugins, Mail Auth.
Slå på Protected pages in the products' frames och spara.

Inställningen gäller bara den sajten. En annan sajt ärver den aldrig, inte heller från grundsajten.
Loggen får en rad varje gång en ram får en kaka, och när en kaka slutar gälla för att kunden eller nyckeln är spärrad.
För den som bygger produkten: länken för ramen står i pluginets README.md → Embedded pages.