Download the PHP package yowedjamal/bjpass-backend-sdk without Composer

BjPass Backend SDK - Package Laravel

Un package Laravel complet pour l'authentification OAuth2/OIDC avec BjPass, fournissant une intégration clé en main pour votre application backend.

🚀 Installation

1. Installation via Composer

2. Publication de la configuration

3. Configuration des variables d'environnement

Ajoutez ces variables dans votre fichier .env :

4. Publication des routes (optionnel)

📋 Configuration

Le package est configuré via le fichier config/bjpass.php. Voici les principales options :

Configuration OIDC

• base_url : URL de base du provider OIDC
• auth_server : Serveur d'authentification à utiliser
• client_id : Identifiant client OAuth2
• client_secret : Secret client OAuth2
• redirect_uri : URI de redirection après authentification
• scope : Scopes OAuth2 demandés

Configuration de sécurité

• jwks_cache_ttl : Durée de vie du cache JWKS (en secondes)
• auth_session_max_age : Durée maximale de la session d'authentification
• max_token_age : Âge maximal des tokens acceptés
• revoke_tokens_on_logout : Révoquer les tokens lors de la déconnexion

Configuration des cookies

• use_secure_cookies : Utiliser des cookies sécurisés
• session_cookie_name : Nom du cookie de session
• session_cookie_lifetime : Durée de vie du cookie de session

🔧 Utilisation

Utilisation basique avec la façade

Utilisation avec injection de dépendances

Middleware d'authentification

Protégez vos routes avec le middleware BjPass :

🌐 Endpoints HTTP intégrés

Le package fournit automatiquement ces endpoints :

Authentification

• GET /auth/start - Démarrer le flux d'authentification
• GET /auth/callback - Gérer le retour du provider OIDC
• GET /auth/error - Page d'erreur d'authentification

API

• GET /auth/api/status - Vérifier le statut d'authentification
• GET /auth/api/user - Obtenir les informations utilisateur
• POST /auth/api/logout - Déconnexion
• POST /auth/api/refresh - Rafraîchir le token d'accès
• POST /auth/api/introspect - Introspecter un token

Routes protégées

• GET /auth/protected/dashboard - Exemple de route protégée

🔐 Sécurité

Gestion des sessions

• Stockage sécurisé des tokens en session Laravel
• Cookies HTTPOnly optionnels pour une sécurité renforcée
• Rotation automatique des refresh tokens

Validation des tokens

• Validation cryptographique des signatures JWT via JWKS
• Vérification des claims OIDC (aud, iss, exp, iat, nonce)
• Cache intelligent des clés publiques JWKS

Protection CSRF

• Validation automatique du paramètre state
• Vérification de l'origine des requêtes
• Protection contre les attaques de rejeu

🔄 Intégration avec le SDK Frontend

Configuration du frontend

Flux d'authentification

1. Démarrage : Le frontend ouvre /auth/start dans une popup
2. Redirection : L'utilisateur est redirigé vers le provider OIDC
3. Callback : Le provider redirige vers /auth/callback
4. Communication : La page de callback communique avec le frontend via postMessage
5. Vérification : Le frontend vérifie le statut via /auth/api/status

🧪 Tests

Exécution des tests

Tests avec couverture

Analyse statique

📚 API Reference

Méthodes principales

createAuthorizationUrl(array $params = [])

Crée une URL d'autorisation OAuth2 avec PKCE.

Paramètres :

• state : Paramètre state personnalisé (optionnel)
• nonce : Paramètre nonce personnalisé (optionnel)

Retour :

exchangeCode(string $code, string $state)

Échange un code d'autorisation contre des tokens.

Retour :

validateIdToken(string $idToken, ?string $expectedNonce = null)

Valide un ID token JWT.

isAuthenticated()

Vérifie si l'utilisateur est authentifié.

getUserInfo()

Récupère les informations de l'utilisateur connecté.

logout()

Déconnecte l'utilisateur et révoque les tokens.

Services disponibles

getAuthService()

Retourne l'instance du service d'authentification.

getTokenService()

Retourne l'instance du service de validation des tokens.

getJwksService()

Retourne l'instance du service de gestion des JWKS.

🚨 Gestion des erreurs

Exceptions personnalisées

Codes d'erreur

• invalid_token : Token invalide ou expiré
• invalid_state : Paramètre state invalide
• authentication_failed : Échec de l'authentification
• session_expired : Session expirée
• insufficient_permissions : Permissions insuffisantes

🔧 Personnalisation

Configuration avancée

Middleware personnalisé

📦 Structure du package

🤝 Contribution

1. Fork le projet
2. Créez une branche pour votre fonctionnalité
3. Committez vos changements
4. Poussez vers la branche
5. Ouvrez une Pull Request

📄 Licence

Ce package est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

🆘 Support

Pour toute question ou problème :

• Ouvrez une issue sur GitHub
• Consultez la documentation
• Contactez l'équipe de développement

Développé avec ❤️ par l'équipe BjPass