ProxyNinja.md

Documentation Technique - Intégration Client Proxy Ninja

Introduction

Proxy Ninja est un service managé d'identité respectant les standards modernes d'authentification et d'autorisation. Il prend en charge plusieurs protocoles, notamment OIDC (OpenID Connect), SAML2, et CAS3.

Cette documentation fournit un guide pour l'intégration de Proxy Ninja dans des applications développées en PHP, Node.js, et ASP.NET.

Flow d'authentification pour une ressource au GAR.

Les flow vers les autres IDP sont très similaires.

Les flèches représentes le parcours du client. Les flèches pleines : clics du client Les flèches en pointillé : les redirections

sequenceDiagram

    Mediacentre->>Landing Page: Clic  landing page d'une ressource. 
    Landing Page-->>Proxy Ninja: Paramètrage demande d'identité
    Proxy Ninja-->>GAR: Authentification pour la ressource
    GAR-->>+Proxy Ninja: Jeton d'authentification
    Note left of Proxy Ninja: Session créée
    Proxy Ninja-->>Ressource: Redirection
    Ressource-->>Proxy Ninja: Création session
    Proxy Ninja-->>-Ressource: Authentifié
    Note left of Ressource: L'utilisateur a accès a la ressource

Loading

Nous vous fournirons les informations suivantes

• Accès à un compte Proxy Ninja.
• Les endpoints d'authentification et de récupération des tokens :
  • Préproduction : https://preprod-proxy.gar.ninja/realms/<EDITEUR>/
  • Production : https://proxy.gar.ninja/realms/<EDITEUR>/
  • Fichier de configuration OIDC : https://proxy.gar.ninja/realms/<EDITEUR>/.well-known/openid-configuration
• Une client_id et un client_secret.
• Une bibliothèque adaptée au protocole sélectionné (OIDC recommandé).

Nous avons besoin des informations suivantes (pour prod et preprod) :

• Url de login
• Url de logout backchannel (OIDC ou CAS)

Fonctionnalités

Attributs de l'établissement scolaire

Les informations de l'établissement scolaire de l'utilisateur (lorsqu'ils peuvent être déterminés) peuvent être ajouté (sur demande)

---

1. Implémentation en PHP

Installation de la bibliothèque

composer require jumbojett/openid-connect-php

Exemple d'intégration

require 'vendor/autoload.php';
use Jumbojett\OpenIDConnectClient;

$oidc = new OpenIDConnectClient(
    'https://proxy.gar.ninja/realms/<EDITEUR>/',
    'votre-client-id',
    'votre-client-secret'
);

$oidc->authenticate();
$userInfo = $oidc->requestUserInfo();

echo 'Utilisateur connecté : ' . $userInfo->name;

---

2. Implémentation en Node.js

Installation de la bibliothèque

npm install keycloak-connect

Exemple d'intégration

const express = require('express');
const session = require('express-session');
const Keycloak = require('keycloak-connect');

const app = express();
const memoryStore = new session.MemoryStore();

app.use(session({
  secret: 'mySecret',
  resave: false,
  saveUninitialized: true,
  store: memoryStore
}));

const keycloak = new Keycloak({ store: memoryStore }, {
  clientId: 'votre-client-id',
  bearerOnly: true,
  serverUrl: 'https://proxy.gar.ninja',
  realm: '<EDITEUR>',
  credentials: {
    secret: 'votre-client-secret'
  }
});

app.use(keycloak.middleware());

app.get('/secure', keycloak.protect(), (req, res) => {
  res.json({ message: 'Accès sécurisé accordé' });
});

app.listen(3000, () => {
  console.log('Serveur démarré sur http://localhost:3000');
});

---

3. Implémentation en ASP.NET (C#)

Installation de la bibliothèque

dotnet add package Keycloak.AuthServices.Sdk

Exemple d'intégration

using Keycloak.AuthServices.Sdk;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKeycloakAuthentication(builder.Configuration, options =>
{
    options.Realm = "<EDITEUR>";
    options.AuthServerUrl = "https://proxy.gar.ninja";
    options.ClientId = "votre-client-id";
    options.ClientSecret = "votre-client-secret";
    options.RequireHttpsMetadata = true;
});

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

---

4. Le logout

POST /backchannel_logout HTTP/1.1
  Host: rp.example.org
  Content-Type: application/x-www-form-urlencoded

  logout_token=eyJhbGci ... .eyJpc3Mi ... .T3BlbklE ..

Le Back-Channel Logout permet à Proxy Ninja d’informer un client qu’une session utilisateur doit être terminée. À la réception d’une requête de déconnexion, le client doit :

1. Décoder et valider le Logout Token.
2. Extraire et utiliser les claims sub (identifiant utilisateur) et/ou sid (identifiant de session) pour identifier la session à fermer.
3. Mettre fin à la session correspondante côté client (invalidation des cookies, suppression des tokens, etc.).

Pour une validation complète du Logout Token selon le standard OIDC, voir la documentation officielle :
OpenID Connect Back-Channel Logout

Bonnes Pratiques

1. Stockage sécurisé des tokens : Évitez de stocker les tokens en clair, utilisez des sessions sécurisées ou des cookies protégés.
2. Renouvellement automatique : Implémentez un mécanisme pour rafraîchir le token avant son expiration.
3. Utilisation d’un middleware : c'est recommandé, c'est plus rapide qu'un développement spécifique
4. Le Logout : lorsqu'il se propage à votre ressource, il doit se faire en quelques secondes maximum. Vous ne pouvez pas attendre l'expiration d'un token.

---

Nous contacter

Le plus simple est d'écrire à @eric dans le channel sur le Slack garninja