Aller au contenu

Authentification

LexOpti est un serveur d’autorisation OAuth 2.1. Votre application agit pour un membre dans une organisation : le membre choisit l’organisation pendant l’autorisation, et chaque jeton y est lié. Pour connecter un membre pas à pas, suivez construire une intégration complète.

Usage Valeur
Émetteur https://app.lexopti.com/api/auth
Métadonnées https://app.lexopti.com/.well-known/oauth-authorization-server/api/auth
Autorisation GET https://app.lexopti.com/api/auth/oauth2/authorize
Jeton POST https://app.lexopti.com/api/auth/oauth2/token
Révocation (RFC 7009) POST https://app.lexopti.com/api/auth/oauth2/revoke, avec token et token_type_hint
Ressource de l’API https://app.lexopti.com/v1

Le client d’une application web est confidentiel : il s’authentifie aux points de jeton et de révocation en HTTP Basic (client_secret_basic, identifiant et secret encodés en formulaire). Une application mobile ou de bureau est enregistrée comme application native, un client public sans secret qui envoie son client_id dans le formulaire (applications mobiles et natives).

Code d’autorisation avec PKCE (S256, toujours exigé). Demandez la ressource https://app.lexopti.com/v1 au point d’autorisation et au point de jeton. Les URI de redirection d’une application web sont des URL HTTPS exactes, sans joker ; celles d’une application native sont une adresse IP de boucle locale sur tout port, un schéma à usage privé en domaine inversé ou une URI HTTPS revendiquée (enregistrer une application native).

Type d’autorisation Paramètres au point de jeton
authorization_code code, code_verifier, redirect_uri, resource
refresh_token refresh_token, resource

La page de connexion de LexOpti propose Pas encore de compte ? Créer un compte sous son formulaire, et une adresse e-mail que LexOpti ne connaît pas y mène aussi. Le membre suit l’inscription normale de LexOpti : profession, structure, offre ou essai gratuit, paiement s’il y a lieu, puis le code reçu par e-mail. La page lui indique que si sa structure utilise déjà LexOpti, il doit demander une invitation à son responsable plutôt que créer une seconde structure.

Votre demande d’autorisation est conservée 45 minutes, dans ce navigateur seulement. Une fois l’inscription terminée, ou l’invitation acceptée, le membre la poursuit (le choix de l’organisation s’il en a plusieurs, puis le consentement) et revient sur votre redirect_uri avec le code et votre state, comme après une connexion. Rien ne change de votre côté : la même demande, le même rappel, la même vérification du state. Au-delà de 45 minutes, ou dans un autre navigateur, le compte est tout de même créé mais le membre reste dans LexOpti : il relance la connexion depuis votre logiciel.

Une application encore limitée aux bacs à sable le reste : la structure d’un nouveau membre est une organisation réelle, pour laquelle elle ne peut pas être autorisée.

Une fois votre application installée par une structure pour tous ses membres, celle-ci peut laisser votre logiciel agir pour les membres qu’elle a enrôlés sans qu’ils se connectent : le mode délégué, actif par défaut pour une application installée, que la structure demande à LexOpti de couper ou de rétablir. Votre logiciel garde alors une seule connexion, celle d’un propriétaire ou d’un administrateur, et nomme le membre qui agit sur chaque requête avec l’en-tête X-LexOpti-Acting-User: <member_id>. LexOpti exécute la requête avec le rôle de ce membre et note, sur chaque trace, que l’identité a été affirmée par votre application. L’enrôlement, les deux modes et leurs refus : enrôler vos membres.

Portée Donne
lexopti:read lire l’organisation, les clients, analyses, dossiers, alertes, événements, la consommation et les points de réception webhook
lexopti:write créer des clients, lancer des analyses, examiner des alertes, gérer les webhooks, ouvrir des sessions embarquées et des liens profonds
offline_access un jeton de rafraîchissement
openid, email l’identité du membre

Un membre en lecture seule dans l’organisation n’écrit jamais, quelles que soient les portées (readonly_member).

  • Les jetons d’accès durent 15 minutes. Rafraîchissez-les automatiquement, avant expiration ou à la réception d’un 401 : avec le SDK, accessToken est une fonction appelée une fois par opération, qui rend un jeton valide et le rafraîchit au besoin.
  • Les jetons de rafraîchissement durent 30 jours et tournent à chaque usage : chaque rafraîchissement rend un nouveau jeton de rafraîchissement, valable 30 jours à partir de là. Des rafraîchissements concurrents à moins de 10 secondes sont tolérés (la même réponse est rendue) ; rejouer plus tard un ancien jeton est traité comme un vol et révoque toute la famille : enregistrez le nouveau jeton de façon atomique.
  • Une application restée inutilisée 30 jours, son dernier jeton de rafraîchissement expiré, doit obtenir une nouvelle autorisation du membre : faites-le repasser par le parcours d’autorisation.
  • Un jeton de rafraîchissement est aussi révoqué, quelle que soit son échéance, quand l’accès prend fin (ci-dessous) : le membre quitte l’organisation ou est banni, l’organisation bloque votre application, LexOpti la désactive, le membre retire son consentement, ou un jeton rejoué a révoqué sa famille.
  • Votre secret client n’est affiché qu’une fois et il est stocké haché. Demandez sa rotation à LexOpti : le nouveau secret n’est affiché qu’une fois, et l’ancien reste valable 24 heures, le temps de déployer le nouveau sans interruption.

Un rafraîchissement au point de jeton, en HTTP Basic : enregistrez le nouveau jeton de rafraîchissement avant d’utiliser le jeton d’accès.

/** De nouveaux jetons pour un jeton de rafraîchissement : enregistrez celui qu’il répond. */
async function
function refreshTokens(refreshToken: string): Promise<{
access_token: string;
expires_in: number;
refresh_token: string;
}>

De nouveaux jetons pour un jeton de rafraîchissement : enregistrez celui qu’il répond.

refreshTokens
(
refreshToken: string
refreshToken
: string) {
const
const basic: string
basic
=
var Buffer: BufferConstructor
Buffer
.
BufferConstructor.from(string: WithImplicitCoercion<string>, encoding?: BufferEncoding): Buffer<ArrayBuffer> (+3 overloads)

Creates a new Buffer containing string. The encoding parameter identifies the character encoding to be used when converting string into bytes.

import { Buffer } from 'node:buffer';
const buf1 = Buffer.from('this is a tést');
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
console.log(buf1.toString());
// Prints: this is a tést
console.log(buf2.toString());
// Prints: this is a tést
console.log(buf1.toString('latin1'));
// Prints: this is a tést

A TypeError will be thrown if string is not a string or another type appropriate for Buffer.from() variants.

Buffer.from(string) may also use the internal Buffer pool like Buffer.allocUnsafe() does.

@since ― v5.10.0

@param ― string A string to encode.

@param ― encoding The encoding of string. Default: 'utf8'.

from
(
`${
function encodeURIComponent(uriComponent: string | number | boolean): string

Encodes a text string as a valid component of a Uniform Resource Identifier (URI).

@param ― uriComponent A value representing an unencoded URI component.

encodeURIComponent
(
const clientId: string
clientId
)}:${
function encodeURIComponent(uriComponent: string | number | boolean): string

Encodes a text string as a valid component of a Uniform Resource Identifier (URI).

@param ― uriComponent A value representing an unencoded URI component.

encodeURIComponent
(
const clientSecret: string
clientSecret
)}`
).
Buffer<ArrayBuffer>.toString(encoding?: BufferEncoding, start?: number, end?: number): string

Decodes buf to a string according to the specified character encoding inencoding. start and end may be passed to decode only a subset of buf.

If encoding is 'utf8' and a byte sequence in the input is not valid UTF-8, then each invalid byte is replaced with the replacement character U+FFFD.

The maximum length of a string instance (in UTF-16 code units) is available as

constants.MAX_STRING_LENGTH

.

import { Buffer } from 'node:buffer';
const buf1 = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf1[i] = i + 97;
}
console.log(buf1.toString('utf8'));
// Prints: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5));
// Prints: abcde
const buf2 = Buffer.from('tést');
console.log(buf2.toString('hex'));
// Prints: 74c3a97374
console.log(buf2.toString('utf8', 0, 3));
// Prints: té
console.log(buf2.toString(undefined, 0, 3));
// Prints: té

@since ― v0.1.90

@param ― encoding The character encoding to use.

@param ― start The byte offset to start decoding at.

@param ― end The byte offset to stop decoding at (not inclusive).

toString
("base64");
const
const response: Response
response
= await
function fetch(input: string | URL | Request, init?: RequestInit): Promise<Response> (+1 overload)
fetch
(
"https://app.lexopti.com/api/auth/oauth2/token",
{
RequestInit.body?: BodyInit | null | undefined

A BodyInit object or null to set request's body.

body
: new
var URLSearchParams: new (init?: string[][] | Record<string, string> | string | URLSearchParams) => URLSearchParams

The URLSearchParams interface defines utility methods to work with the query string of a URL.

MDN Reference

URLSearchParams class is a global reference for import { URLSearchParams } from 'node:url' https://nodejs.org/api/url.html#class-urlsearchparams

@since ― v10.0.0

URLSearchParams
({
grant_type: string
grant_type
: "refresh_token",
refresh_token: string
refresh_token
:
refreshToken: string
refreshToken
,
resource: string
resource
: "https://app.lexopti.com/v1",
}),
RequestInit.headers?: HeadersInit | undefined

A Headers object, an object literal, or an array of two-item arrays to set request's headers.

headers
: {
authorization: string
authorization
: `Basic ${
const basic: string
basic
}` },
RequestInit.method?: string | undefined

A string to set request's method.

method
: "POST",
}
);
if (!
const response: Response
response
.
Response.ok: boolean

The ok read-only property of the Response interface contains a Boolean stating whether the response was successful (status in the range 200-299) or not.

MDN Reference

ok
) {
// invalid_grant : le membre doit autoriser à nouveau.
throw new
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error
(`The token endpoint answered ${
const response: Response
response
.
Response.status: number

The status read-only property of the Response interface contains the HTTP status codes of the response.

MDN Reference

status
}`);
}
const
const tokens: {
access_token: string;
expires_in: number;
refresh_token: string;
}
tokens
: {
access_token: string
access_token
: string;
expires_in: number
expires_in
: number;
refresh_token: string
refresh_token
: string;
} = await
const response: Response
response
.
Body.json(): Promise<any>
json
();
return
const tokens: {
access_token: string;
expires_in: number;
refresh_token: string;
}
tokens
;
}

Quand le membre déconnecte LexOpti dans votre logiciel, révoquez ses jetons au point de révocation en HTTP Basic : d’abord le jeton de rafraîchissement, qui met fin à l’autorisation, puis le jeton d’accès. Abandonnez les jetons même si une révocation échoue.

const
const basic: string
basic
=
var Buffer: BufferConstructor
Buffer
.
BufferConstructor.from(string: WithImplicitCoercion<string>, encoding?: BufferEncoding): Buffer<ArrayBuffer> (+3 overloads)

Creates a new Buffer containing string. The encoding parameter identifies the character encoding to be used when converting string into bytes.

import { Buffer } from 'node:buffer';
const buf1 = Buffer.from('this is a tést');
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
console.log(buf1.toString());
// Prints: this is a tést
console.log(buf2.toString());
// Prints: this is a tést
console.log(buf1.toString('latin1'));
// Prints: this is a tést

A TypeError will be thrown if string is not a string or another type appropriate for Buffer.from() variants.

Buffer.from(string) may also use the internal Buffer pool like Buffer.allocUnsafe() does.

@since ― v5.10.0

@param ― string A string to encode.

@param ― encoding The encoding of string. Default: 'utf8'.

from
(
`${
function encodeURIComponent(uriComponent: string | number | boolean): string

Encodes a text string as a valid component of a Uniform Resource Identifier (URI).

@param ― uriComponent A value representing an unencoded URI component.

encodeURIComponent
(
const clientId: string
clientId
)}:${
function encodeURIComponent(uriComponent: string | number | boolean): string

Encodes a text string as a valid component of a Uniform Resource Identifier (URI).

@param ― uriComponent A value representing an unencoded URI component.

encodeURIComponent
(
const clientSecret: string
clientSecret
)}`
).
Buffer<ArrayBuffer>.toString(encoding?: BufferEncoding, start?: number, end?: number): string

Decodes buf to a string according to the specified character encoding inencoding. start and end may be passed to decode only a subset of buf.

If encoding is 'utf8' and a byte sequence in the input is not valid UTF-8, then each invalid byte is replaced with the replacement character U+FFFD.

The maximum length of a string instance (in UTF-16 code units) is available as

constants.MAX_STRING_LENGTH

.

import { Buffer } from 'node:buffer';
const buf1 = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf1[i] = i + 97;
}
console.log(buf1.toString('utf8'));
// Prints: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5));
// Prints: abcde
const buf2 = Buffer.from('tést');
console.log(buf2.toString('hex'));
// Prints: 74c3a97374
console.log(buf2.toString('utf8', 0, 3));
// Prints: té
console.log(buf2.toString(undefined, 0, 3));
// Prints: té

@since ― v0.1.90

@param ― encoding The character encoding to use.

@param ― start The byte offset to start decoding at.

@param ― end The byte offset to stop decoding at (not inclusive).

toString
("base64");
// D'abord le jeton de rafraîchissement : il met fin à l'autorisation. Puis le jeton d'accès.
for (const [
const token: string
token
,
const hint: "refresh_token" | "access_token"
hint
] of [
[
const tokens: {
access_token: string;
refresh_token: string;
}
tokens
.
refresh_token: string
refresh_token
, "refresh_token"],
[
const tokens: {
access_token: string;
refresh_token: string;
}
tokens
.
access_token: string
access_token
, "access_token"],
] as
type const = readonly [readonly [string, "refresh_token"], readonly [string, "access_token"]]
const
) {
await
function fetch(input: string | URL | Request, init?: RequestInit): Promise<Response> (+1 overload)
fetch
("https://app.lexopti.com/api/auth/oauth2/revoke", {
RequestInit.body?: BodyInit | null | undefined

A BodyInit object or null to set request's body.

body
: new
var URLSearchParams: new (init?: string[][] | Record<string, string> | string | URLSearchParams) => URLSearchParams

The URLSearchParams interface defines utility methods to work with the query string of a URL.

MDN Reference

URLSearchParams class is a global reference for import { URLSearchParams } from 'node:url' https://nodejs.org/api/url.html#class-urlsearchparams

@since ― v10.0.0

URLSearchParams
({
token: string
token
,
token_type_hint: "refresh_token" | "access_token"
token_type_hint
:
const hint: "refresh_token" | "access_token"
hint
}),
RequestInit.headers?: HeadersInit | undefined

A Headers object, an object literal, or an array of two-item arrays to set request's headers.

headers
: {
authorization: string
authorization
: `Basic ${
const basic: string
basic
}` },
RequestInit.method?: string | undefined

A string to set request's method.

method
: "POST",
});
}
// Puis abandonnez les jetons, même si une révocation a échoué.

Chaque requête revérifie que le membre appartient toujours à l’organisation, n’est pas banni, que l’organisation n’a pas bloqué votre application, que LexOpti ne l’a pas désactivée et que le consentement du membre existe encore. Si l’un d’eux manque, la requête suivante répond 401 invalid_token, quelle que soit l’expiration du jeton. Un jeton n’agit jamais au-delà du consentement actuel du membre : un consentement restreint à moins de portées restreint les jetons déjà émis.

Test Request dans la référence de l’API et l’aperçu en direct de l’atelier vous connectent avec l’application propre au portail, pour l’un de vos bacs à sable seulement, et gardent le jeton dans la mémoire de la page, jamais dans le stockage du navigateur. L’atelier ouvre l’autorisation dans une fenêtre ; quand le navigateur la bloque, quand elle est fermée sans réponse ou tarde trop, ou quand vous choisissez Ouvrir dans cet onglet, il continue dans le même onglet et vous ramène à l’atelier avec ses réglages. La référence de l’API ne peut utiliser qu’une fenêtre, sa visionneuse n’offrant pas d’autre moyen : si votre navigateur la bloque, autorisez les fenêtres surgissantes pour le portail, ou collez un jeton d’accès dans Authentication.