Se connecter avec Octal Group

Permettez à vos utilisateurs de se connecter à votre site ou à votre application avec leur compte Octal Group, en un clic, sans créer de nouveau mot de passe.

Comment ça marche

Le service suit les standards OAuth 2.0 (code d’autorisation avec PKCE) et OpenID Connect : toute bibliothèque compatible fonctionne, en indiquant simplement l’adresse de découverte.

  1. L’utilisateur clique sur le bouton : il arrive sur la page de connexion d’Octal Group.
  2. Il se connecte (s’il ne l’est pas déjà) et accepte de partager les informations demandées.
  3. Il revient sur votre adresse de retour avec un code à usage unique, valable 10 minutes.
  4. Votre serveur échange ce code contre un jeton d’identité signé et des jetons d’accès.

Votre application ne voit jamais le mot de passe de l’utilisateur, qui peut retirer l’accès à tout moment depuis son compte.

1. Créer votre application

Il vous faut un compte Octal Group : la console développeurs n’est accessible qu’une fois connecté. Si vous n’en avez pas, créez un compte gratuit ; sinon, connectez-vous et vous arriverez directement sur la console.

Dans la console développeurs, créez une application avec son nom (affiché aux utilisateurs), son site et ses adresses de retour exactes. Vous obtenez :

  • un identifiant client (og_…), public ;
  • pour un site avec serveur, un secret client (ogs_…), affiché une seule fois, à garder sur votre serveur.

Les adresses de retour doivent utiliser https:// (http://localhost est accepté pour le développement). Les applications mobiles peuvent utiliser un schéma privé, par exemple cm.exemple.app:/oauth.

2. Ajouter le bouton

Le plus simple : chargez le kit officiel et placez le bouton, il gère pour vous PKCE, state et nonce.

<!-- 1. Le kit officiel -->
<script src="https://workspaces.mail8g.com/sdk/octal-signin.js" defer></script>

<!-- 2. Le bouton, là où vous voulez l'afficher -->
<div class="octal-signin"
     data-client-id="og_votre_identifiant_client"
     data-redirect-uri="https://www.exemple.cm/auth/octal/retour"
     data-theme="light"></div>

Ou en JavaScript, pour choisir l’apparence et traiter le retour :

OctalGroup.init({
  clientId: 'og_votre_identifiant_client',
  redirectUri: 'https://www.exemple.cm/auth/octal/retour',
  scope: 'openid profile email',
});

// Bouton clair, sombre ou neutre ; en pilule ou rectangulaire
OctalGroup.renderButton('#connexion-octal', { theme: 'dark', shape: 'pill', text: 'continue' });

// Sur la page de retour : vérifie "state" et transmet le code à votre serveur
const result = await OctalGroup.handleRedirect();
if (result) {
  await fetch('/auth/octal/session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(result), // { code, codeVerifier, redirectUri, nonce }
  });
}

Options de renderButton :

  • theme : light, dark ou neutral ;
  • shape : pill ou rect ;
  • size : large ou medium ;
  • text : signin (« Se connecter avec Octal Group »), continue ou signup ;
  • width (en pixels) et onClick.

Vous préférez votre propre intégration ? Téléchargez le bouton officiel en SVG :

Sans le kit, redirigez l’utilisateur vers l’adresse d’autorisation :

https://workspaces.mail8g.com/oauth/authorize
  ?client_id=og_votre_identifiant_client
  &redirect_uri=https%3A%2F%2Fwww.exemple.cm%2Fauth%2Foctal%2Fretour
  &response_type=code
  &scope=openid%20profile%20email
  &state=VALEUR_ALEATOIRE
  &nonce=AUTRE_VALEUR_ALEATOIRE
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256

3. Échanger le code (serveur)

Votre serveur échange le code, puis vérifie le jeton d’identité avec les clés publiques. Exemple en Node.js avec Express et la bibliothèque jose :

import express from 'express';
import { createRemoteJWKSet, jwtVerify } from 'jose';

const ISSUER = 'https://workspaces.mail8g.com';
const CLIENT_ID = process.env.OCTAL_CLIENT_ID;
const CLIENT_SECRET = process.env.OCTAL_CLIENT_SECRET; // jamais côté navigateur
const JWKS = createRemoteJWKSet(new URL(`${ISSUER}/oauth/jwks`));

const app = express();
app.use(express.json());

app.post('/auth/octal/session', async (req, res) => {
  const { code, codeVerifier, redirectUri, nonce } = req.body;

  // 1. Échange du code contre les jetons
  const response = await fetch(`${ISSUER}/oauth/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: 'Basic ' + Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64'),
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: redirectUri,
      code_verifier: codeVerifier,
    }),
  });
  const tokens = await response.json();
  if (!response.ok) return res.status(401).json(tokens); // { error, error_description }

  // 2. Vérification du jeton d'identité (signature RS256, émetteur, destinataire, nonce)
  const { payload } = await jwtVerify(tokens.id_token, JWKS, { issuer: ISSUER, audience: CLIENT_ID });
  if (payload.nonce !== nonce) return res.status(401).json({ error: 'invalid_nonce' });

  // 3. payload.sub identifie le compte Octal Group de façon stable : rattachez-le à votre utilisateur
  // payload.email, payload.name, payload.picture selon les autorisations accordées
  req.session.user = { octalId: payload.sub, email: payload.email, name: payload.name, picture: payload.picture };
  res.json({ ok: true });
});

Le secret peut aussi être envoyé dans le corps de la requête (client_id et client_secret). Le champ sub est l’identifiant stable du compte : utilisez-le plutôt que l’adresse e-mail pour reconnaître vos utilisateurs.

Applications sans serveur

Pour une application mobile ou une page web sans serveur, créez une application de type « mobile ou page web seule » : elle n’a pas de secret et PKCE est obligatoire. Le kit peut échanger le code directement :

// Application sans serveur (type « mobile ou page web seule », sans secret)
const tokens = await OctalGroup.handleRedirect({ exchange: true });
if (tokens) {
  const profile = await OctalGroup.userInfo(tokens.access_token);
  console.log(profile.sub, profile.name, profile.email, profile.picture);
}

Jetons et identité

Autorisation (scope)Ce que l’utilisateur voitInformations
openidVous identifiersub
profileVotre nom et votre photo de profilname, given_name, family_name, picture
emailVotre adresse e-mailemail, email_verified
  • Jeton d’identité (id_token) : JWT signé en RS256, valable 1 heure, avec iss, aud, nonce et at_hash.
  • Jeton d’accès (oga_…) : valable 1 heure, pour /oauth/userinfo.
  • Jeton de renouvellement (ogr_…) : valable 90 jours et à usage unique. Chaque renouvellement en fournit un nouveau.
curl -X POST https://workspaces.mail8g.com/oauth/token \
  -u "og_votre_identifiant_client:ogs_votre_secret" \
  -d grant_type=refresh_token \
  -d refresh_token=ogr_…

Les erreurs suivent OAuth 2.0 : { "error": "invalid_grant", "error_description": "…" }. Si l’utilisateur refuse, il revient sur votre adresse avec error=access_denied. Chaque retour porte aussi iss, à comparer avec l’émetteur attendu.

Points d’accès

Découverte OpenIDhttps://workspaces.mail8g.com/.well-known/openid-configuration
Autorisationhttps://workspaces.mail8g.com/oauth/authorize
Jetonshttps://workspaces.mail8g.com/oauth/token
Informations du comptehttps://workspaces.mail8g.com/oauth/userinfo
Clés publiques (JWKS)https://workspaces.mail8g.com/oauth/jwks
Révocationhttps://workspaces.mail8g.com/oauth/revoke

Les points d’accès des jetons, des informations du compte, des clés et de la révocation acceptent les appels depuis n’importe quel site (CORS), sans cookie.

Règles d’utilisation du bouton

  • Utilisez le bouton officiel ou ses fichiers SVG, sans en changer les couleurs, les proportions ni le logo.
  • Laissez un espace libre autour du bouton et une hauteur d’au moins 36 pixels.
  • Donnez-lui la même importance que les autres moyens de connexion (Google, Facebook, Apple…) quand vous en proposez plusieurs.
  • Ne présentez pas votre application comme un produit d’Octal Group : son nom doit être le vôtre.
  • Publiez une politique de confidentialité et indiquez-la dans la console : elle s’affiche sur l’écran de consentement.

Octal Group peut suspendre une application qui ne respecte pas ces règles ou qui abuse des données de ses utilisateurs.