Identiteitsverificatie

Met identiteitsverificatie kun je ingelogde gebruikers in de Eloquent-chatwidget veilig identificeren. Wanneer een gebruiker op je website is geauthenticeerd, kun je Eloquent een ondertekende JWT doorgeven zodat de agent weet wie de gebruiker is en een meer gepersonaliseerde supportervaring kan bieden.

In Eloquent wordt identiteitsverificatie afgehandeld via de identify-integratie. Je server maakt een ondertekende JWT, je frontend geeft die token door aan de Eloquent-widget en Eloquent verifieert de token voordat het gesprek aan een agentprofiel wordt gekoppeld.

Wanneer identiteitsverificatie te gebruiken

Personaliseer de chatervaring

Gebruik identiteitsverificatie wanneer je wilt dat de agent ingelogde gebruikers herkent en reageert met gebruikersspecifieke context.

• Begroet gebruikers bij naam of met accountgegevens
• Begrijp het abonnement, de rol of het plan van de gebruiker
• Bied support op basis van geverifieerde profielinformatie
• Koppel gesprekken in de loop van de tijd aan dezelfde bekende gebruiker

Gebruik geverifieerde gebruikerscontext

De geverifieerde JWT-claims worden als systeemcontext aan de agent toegevoegd. Hierdoor kan de agent tijdens het beantwoorden van de gebruiker betrouwbare identiteitsinformatie gebruiken.

• Gebruikers-ID (vereist)
• E-mailadres (aanbevolen)
• Naam
• Plan- of abonnementsniveau
• Alle andere aangepaste claims die je in de JWT opneemt

Houd agentprofielen up-to-date

Elke geldige identiteitstoken maakt of werkt een Eloquent-agentprofiel bij voor de opgegeven user_id. Dit betekent dat gebruikersinformatie actueel kan blijven zonder het profiel elders handmatig bij te werken.

Implementatiehandleiding

Vereisten

• Het Eloquent-embedscript is op je website geïnstalleerd.
• De identify-functie is ingeschakeld voor je bedrijf of agent.
• Je hebt toegang tot de integratie-instellingen van de agent in het Eloquent-dashboard.

Haal je JWT-secret op

1. Open het Eloquent-dashboard.
2. Selecteer de agent die je wilt configureren.
3. Ga naar Integrations -> Identity Verification.
4. Genereer een JWT-secret.
5. Sla de secret veilig op je server op, bijvoorbeeld in een omgevingsvariabele.

De JWT-secret wordt alleen getoond wanneer deze wordt gegenereerd. Houd hem privé en stel hem nooit bloot in frontendcode.

JWT-identiteitsverificatie

JWT-overzicht

Eloquent gebruikt een JSON Web Token om te verifiëren dat de huidige websitebezoeker een echte geauthenticeerde gebruiker uit je eigen applicatie is. De JWT wordt op je server ondertekend met de secret uit het Eloquent-dashboard.

Wanneer Eloquent de token ontvangt, verifieert het de handtekening met de geconfigureerde secret. Als de token geldig is, maakt of werkt Eloquent het agentprofiel voor die gebruiker bij en koppelt het de geverifieerde identiteit aan het chatverzoek.

JWT-payload

De JWT-payload moet een user_id bevatten.

Vereiste claims:

• user_id: een stabiele unieke identificator voor de gebruiker in je systeem

Optionele claims:

• email: het e-mailadres van de gebruiker (aanbevolen)
• name: de naam van de gebruiker
• plan: het plan of abonnementsniveau van de gebruiker
• role: de rol van de gebruiker in je applicatie
• Alle andere aangepaste attributen die je beschikbaar wilt maken voor de agent

Eloquent slaat email rechtstreeks op in het agentprofiel wanneer dit wordt meegegeven. Andere aangepaste claims worden opgeslagen als profielclaims.

Genereer de JWT op je server

JWT's moeten server-side worden gegenereerd. Genereer ze niet in de browser, omdat je daarmee je Eloquent JWT-secret zou blootstellen.

import jwt from "jsonwebtoken";
const secret = process.env.ELOQUENT_JWT_SECRET;
const token = jwt.sign(
  {
    user_id: user.id,
    email: user.email,
    name: user.name,
    plan: user.plan,
    role: user.role,
  },
  secret,
  {
    expiresIn: "1h",
    algorithm: "HS256",
  }
);

Geef de token terug aan je frontend

Je applicatie moet een geauthenticeerd endpoint beschikbaar stellen dat een token retourneert voor de momenteel ingelogde gebruiker.

app.post("/api/eloquent-token", async (req, res) => {
  const user = await getCurrentUser(req);
  if (!user) {
    return res.status(401).json({
      message: "Unauthorized",
    });
  }
  const token = jwt.sign(
    {
      user_id: user.id,
      email: user.email,
      name: user.name,
      plan: user.plan,
    },
    process.env.ELOQUENT_JWT_SECRET,
    {
      expiresIn: "1h",
      algorithm: "HS256",
    }
  );
  return res.json({ token });
});

Identificeer de gebruiker in de frontend

Nadat je frontend de ondertekende JWT heeft ontvangen, geef je deze door aan de Eloquent-widget met window.eloquent("identify", { token }).

async function identifyEloquentUser() {
    const response = await fetch("/api/eloquent-token", {
      method: "POST",
      credentials: "include",
    });
    if (!response.ok) {
      return;
    }
    const data = await response.json();
    window.eloquent("identify", {
      token: data.token,
    });
  }
  identifyEloquentUser();
}

Roep identify aan nadat het Eloquent-embedscript is geladen en, indien mogelijk, voordat de gebruiker een chat start.

Volledig voorbeeld

Stap 1: Gebruiker logt in

Authenticeer de gebruiker met je bestaande inlogflow. Na het inloggen kan je backend een Eloquent-identiteitstoken voor die gebruiker aanmaken.

app.post("/api/login", async (req, res) => {
  const { email, password } = req.body;
  const user = await authenticateUser(email, password);
  if (!user) {
    return res.status(401).json({
      message: "Invalid credentials",
    });
  }
  const token = jwt.sign(
    {
      user_id: user.id,
      email: user.email,
      name: user.name,
      plan: user.plan,
      support_tier: user.supportTier,
    },
    process.env.ELOQUENT_JWT_SECRET,
    {
      expiresIn: "1h",
      algorithm: "HS256",
    }
  );
  return res.json({
    user: {
      id: user.id,
      email: user.email,
      name: user.name,
    },
    eloquentToken: token,
  });
});

Stap 2: Geef de token door aan Eloquent

async function loginUser() {
  const response = await fetch("/api/login", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    credentials: "include",
    body: JSON.stringify({
      email: "[email protected]",
      password: "password",
    }),
  });
  if (!response.ok) {
    return;
  }
  const data = await response.json();
  window.eloquent("identify", {
    token: data.eloquentToken,
  });
}

Stap 3: Eloquent verifieert de gebruiker

Wanneer de gebruiker een chatbericht verstuurt, neemt Eloquent de identiteitstoken op in het chatverzoek. De backend verifieert de JWT met de geconfigureerde secret.

Als de token geldig is, zal Eloquent:

• Het agentprofiel aanmaken of bijwerken voor de opgegeven user_id
• De email-claim opslaan wanneer deze wordt meegegeven
• Aanvullende claims opslaan als profielclaims
• Het profiel aan het gesprek koppelen
• De geverifieerde identiteitsgegevens toevoegen als systeemcontext voor de agent

Beveiligingsbest practices

• Genereer JWT's alleen op je server.
• Sla de Eloquent JWT-secret op in een omgevingsvariabele.
• Stel de JWT-secret nooit bloot in frontend-JavaScript.
• Gebruik kortlevende tokens, bijvoorbeeld 1h.
• Gebruik een stabiele interne gebruikers-ID voor user_id.
• Vermijd het gebruik van e-mails als user_id, omdat e-mails kunnen veranderen.
• Neem alleen claims op die nuttig zijn voor support of personalisatie.
• Neem geen wachtwoorden, betalingsgegevens, toegangstokens of andere zeer gevoelige data op.

Gedragsnotities

• De token moet zijn ondertekend met HS256.
• De JWT moet user_id bevatten.
• De email-claim is optioneel.
• Aanvullende claims worden ondersteund.
• Ongeldige, verlopen of ontbrekende tokens worden voor identiteitsdoeleinden genegeerd.
• Standaard JWT-timingclaims zoals iat, exp en nbf worden niet opgeslagen als profielclaims.

Problemen oplossen

Gebruiker is niet geïdentificeerd

• Controleer of de agent een JWT-secret geconfigureerd heeft.
• Bevestig dat de frontend window.eloquent("identify", { token }) aanroept.
• Bevestig dat de token vóór of tijdens de chatsessie wordt verzonden.

JWT-verificatie mislukt

• Bevestig dat de token is ondertekend met HS256.
• Bevestig dat de server hetzelfde secret gebruikt dat in Eloquent is gegenereerd.
• Bevestig dat de token niet is verlopen.
• Bevestig dat de JWT-payload een string user_id bevat.

Profielgegevens ontbreken

• Bevestig dat de JWT de claims bevat die je verwacht.
• Gebruik email voor het e-mailveld van het profiel.
• Gebruik extra top-level JWT-claims voor aangepaste profielclaims.
• Onthoud dat iat, exp en nbf niet als profielclaims worden opgeslagen.