# hornet-js-passport

> Gestion d'authentification

Latest version **5.5.0-rc.4** (published 2020-04-06) · CECILL-2.1 license · 0 weekly downloads

## Install

```sh
npm install hornet-js-passport
pnpm add hornet-js-passport
yarn add hornet-js-passport
bun add hornet-js-passport
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.5.0-rc.4 |
| Published | 2020-04-06 |
| First published | 2018-04-03 |
| Weekly downloads | 0 |
| License | CECILL-2.1 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 21 |
| Unpacked size | 454.2 KB |
| Known vulnerabilities | 0 (+22 in 5 direct dependencies) |
| Install scripts | no |
| Author | MEAE - Ministère de l'Europe et des Affaires étrangères |
| Maintainers | moulinw |

## Links

- npm: https://www.npmjs.com/package/hornet-js-passport
- Repository: https://github.com/diplomatiegouvfr/hornet-js
- Homepage: https://github.com/diplomatiegouvfr/hornet-js#readme
- Issues: https://github.com/diplomatiegouvfr/hornet-js/issues
- npm.io page: https://npm.io/package/hornet-js-passport

## Dependencies (21)

- [url](https://npm.io/package/url.md) 0.11.0
- [react](https://npm.io/package/react.md) 16.12.0
- [tslib](https://npm.io/package/tslib.md) 1.10.0
- [xml2js](https://npm.io/package/xml2js.md) 0.4.22
- [xmldom](https://npm.io/package/xmldom.md) 0.1.27
- [request](https://npm.io/package/request.md) 2.88.0
- [parseurl](https://npm.io/package/parseurl.md) 1.3.3
- [passport](https://npm.io/package/passport.md) 0.4.1
- [react-dom](https://npm.io/package/react-dom.md) 16.12.0
- [xml-crypto](https://npm.io/package/xml-crypto.md) 1.4.0
- [xmlbuilder](https://npm.io/package/xmlbuilder.md) 13.0.2
- [lodash.merge](https://npm.io/package/lodash.merge.md) 4.6.2
- [connect-flash](https://npm.io/package/connect-flash.md) 0.1.1
- [lodash.assign](https://npm.io/package/lodash.assign.md) 4.2.0
- [hornet-js-core](https://npm.io/package/hornet-js-core.md) 5.5.0-rc.4
- [xml-encryption](https://npm.io/package/xml-encryption.md) 0.11.2
- [hornet-js-utils](https://npm.io/package/hornet-js-utils.md) 5.5.0-rc.4
- [hornet-js-logger](https://npm.io/package/hornet-js-logger.md) 5.5.0-rc.4
- [lodash.startswith](https://npm.io/package/lodash.startswith.md) 4.2.1
- [hornet-js-components](https://npm.io/package/hornet-js-components.md) 5.5.0-rc.4
- [hornet-js-react-components](https://npm.io/package/hornet-js-react-components.md) 5.5.0-rc.4

## Recent versions

- 5.5.0-rc.4 (latest) — 2020-04-06
- 5.4.1 — 2019-07-25
- 5.4.0 — 2019-07-25
- 5.4.0-RC1 — 2019-05-27
- 5.3.0 — 2019-03-28
- 5.2.4 — 2019-01-10
- 5.2.3 — 2018-11-23
- 5.2.2 — 2018-10-17
- 5.2.1 — 2018-10-12
- 5.2.0 — 2018-08-10
- 5.1.1 — 2018-04-03

## README

# hornet-js-passport

hornet-js-passport fournit un module pour la gestion des droits d'accès pour les applications HornetJS.

Ce module est basé sur *PassportJs* qui est un Middleware d'authentification pour NodeJs, il propose donc des stratégies, ainsi que des middlewares Express pour simplifier son utilisation.


## Prérequis #

* NodeJS 10.X

## Utilisation dans un projet #

Ajouter au package.json

```shell
  "dependencies": {
    "hornet-js-passport": "5.5.X",
  }

```

Puis lancer la commande :

```shell
npm install
```

## PassportJs et Stratégies

PassportJS s'appuie sur des stratégies d'authentification. Une même instance de ce Middleware peut gérer plusieurs stratégies, dès qu'une a pû permettre de s'authentifier, les suivantes ne sont pas exécutées.

### Présentation et mise en place

Tout d'abord il faut instancier PassportJs et lui fournir les méthodes de sérialisation et désérialisation :

```javascript

import passport = require('passport');
passport.serializeUser(function (user, done) {
    done(null, user);
});

passport.deserializeUser(function (user, done) {
    done(null, user);
});

```

Dans cet exemple aucune sérialisation/désérialisation est faite, le user est complet dans la session, mais nous aurions pu, par exemple, sauvegarder l'utilisateur en base et ne mettre que son id dans la session lors de la sérialisation, et le récupérer de la base pour le mettre dans la session lors de la désérialisation.

Ensuite il faut préciser la ou les stratégies à utiliser, exemple :

```javascript

passport.use(new authentication.StrategySaml());

```

A l'appel de la méthode *authenticate*, 'PassportJs' appelle la méthode *authenticate* sur la stratégie, tout en ayant auparavant ajouté dynamiquement sur cette dernière les méthodes suivantes :
* succes
* fail
* redirect
* pass
* error

Maintenant, nous avons une instance de PassPortJs prête à être utilisée, mais attention, elle peut avoir besoin de s'appuyer sur d'autres middlewares suivant les cas (LocalStrategy utilise Flash pour échanger les erreurs entre les Middlewares ou les requêtes).
La position des Middlewares est importante, elle induit l'ordre d'exécution. Dans la plus part des cas l'utilisateur sera sauvegardé en session, donc l'ajout des Middlewares devra se faire apprès celui gérant la session, exemple :

```javascript

server.use(flash()); // middleware d'échange d'information (passe par la session)
server.use(passport.session()); // charge le user présent dans la session
server.get(utils.buildContextPath('/logout'), function (req, res, next) { //déconnexion
    req.logout();
    res.redirect(307, utils.buildContextPath('/'));
});
server.use(function ensureAuthenticated(req, res, next) { // test si l'utilisateur est déjà connecté, sinon demande une authentification
    if (req.isAuthenticated()) {
        return next();
    }
    passport.authenticate('saml')(req, res, next);
});

```

## Surcouches

Afin de simplifier toute cette mise en place et l'instanciation des différents middlewares, une surcouche a été mise en place. Elle s'appuie sur un objet static pour la configuration et un middleware unique gérant les différentes phases de connexion.

La couche d'authentification s'appuie sur un objet de configuration simple pour gérer les phases de connexion, contenant l'url de connexion et de déconnexion :

* appLoginPath : url relative de l'application déclenchant le process de connexion.
* appLogoutPath : url relative de l'application déclenchant le process de déconnexion.
* idpSessionTimeout : paramètre optionel de type boolean pour tenir compte du timeout de la session idp ( par défaut c'est `true`, donc activé).

On instancie le module d'authentification et on lui ajoute les stratégies d'authentification.

### Les Stratégies

#### SAML

Cette stratégie s'appuie sur la classe de configuration *hornet-js-passport/src/strategy/saml/saml-configuration*, et l'initialisation des différents attributs est faite lors de l'instanciation de l'objet de configuration :

- **`callbackUrl`**: Page de connexion de l'application (en général "/login")
- **`logoutCallbackUrl`**: Page de déconnexion de l'application (en général "/logout")
- **`hostUrlReturnTo`**: Nom du serveur applicatif par défaut (en environnement de DEV: "http://localhost:8888")
- **`issuer`**: Chaîne permettant à l'application d'être identifiée par l'IDP (url de l'application)
- **`certSignature`**: Clé publique de l'application
- **`privateCert`**: clé privée de l'application
- **`availableIdp`**: IDPs déclarés au sein de l'application: objet de type `IdentityProviderProps` ou tableau d'objet de type `IdentityProviderProps`
- **`verifyFunction`**: Fonction de callback permettant de traiter la réponse du flux SAML
- **`isMetadataAccessible`**: Détermine si le metadata de l'application est accessible via la route `/metadata-saml` (valorisé par défaut à true)

##### Propriétés de l'/des IDP(s): `availableIdp`

Le module `passport-saml` permet la gestion d'un ou plusieurs IDP. Lors de sa déclaration, il peut être de la forme d'un objet ou d'un tableau d'objets:

- **`name`**: Nom de l'IDP
- **`shibbolethUrl`**: URL pointant vers le fichier des metadata liés à l'IDP
- **`httpsCert`**: Certificat de l'IDP

La propriété `httpsCert` n'est pas nécessaire dans le cas où le fichier metadata de l'idp (renseigné via la propriété `shibbolethUrl`) n'est pas une Url dynamique sécurisée (https).

Un Parser SAML permet ensuite de récupérer les informations utiles à la connexion/déconnexion auprès de l'IDP. Ces informations sont présentes dans le fichier metadata mis à disposition depuis l'url `shibbolethUrl`. Le parser permet alors de récupérer:

- **`entryPoint`**: adresse de redirection vers l'IDP lors de l'authentification
- **`logoutUrl`**: adresse de redirection vers l'IDP lors de la déconnexion
- **`certSignature`**: Certificat de chiffrement pour la signature de l'IDP
- **`certChiffrement`**: Certificat de chiffrement de l'IDP

##### Certificat (`certSignature`) et clé applicatifs (`privateCert`)

ils peuvent être générés via la commande:

```shell

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -nodes -days 900

```

##### Exemple d'utilisation pour une application

Dans le fichier de configuration de l'application **default.json** :

```javascript

"authentication": {
    "loginUrl": "/login",
    "logoutUrl": "/logout",
    "saml": {
      "enabled": true,
      "configuration": {
        "hostUrlReturnTo": "http://localhost:8888",
        "callbackUrl": "/login",
        "logoutCallbackUrl": "/logout",
        "issuer": "http://localhost:8888/applitutoriel",
        "idp": [
          {
            "name": "toto",
            "shibbolethUrl": "{metadata-idp.xml}",
          }
        ,{
            "name": "titi",
            "shibbolethUrl": "{metadata-idp.xml}",
          }
        ],
        "cert": "{chemin}/{cer.pem}",
        "key": ".{chemin}/{key.pem}"
      }
    }
}

```

il faut rajouter également au niveau de la sécurité csp, la configuration suivante:

```js
"formAction": [
  "'self'",
  "{hostName de l'IDP}"
],

```

Dans le fichier **server.ts** :

```javascript

// Authent passport
import { PassportAuthentication } from "hornet-js-passport/src/passport-authentication";
import { AuthenticationtConfiguration } from "hornet-js-passport/src/authentication-configuration";
// Cas
import { SamlConfiguration } from "hornet-js-passport/src/strategy/saml/saml-configuration";
import { SamlStrategy } from "hornet-js-passport/src/strategy/saml/saml-strategy";

let configAuth = new AuthenticationtConfiguration(
Utils.config.get("authentication.loginUrl"),
Utils.config.get("authentication.logoutUrl"));

let authent = new PassportAuthentication(configAuth);

// Ajout du middleware d'authentification (passport-saml)
let configuration = new SamlConfiguration(
    Utils.config.get("authentication.saml.configuration.callbackUrl"),
    Utils.config.get("authentication.saml.configuration.logoutCallbackUrl"),
    // Page de retour par défaut
    Utils.config.get("authentication.saml.configuration.hostUrlReturnTo"),
    // Usually specified as `/shibboleth` from site root
    Utils.config.get("authentication.saml.configuration.issuer"),
    // Certificat applicatif
    fs.readFileSync(Utils.config.get("authentication.saml.configuration.cert"), "utf8"),
    // Clé privée de décryptage
    fs.readFileSync(Utils.config.get("authentication.saml.configuration.key"), "utf8"),

    Utils.config.get("authentication.saml.configuration.idp")
);

authent.initStrategy(new SamlStrategy(configuration));


var server = new Server(configServer, hornetMiddlewareList);
server.start();

```


##### Génération du fichier metadata.xml de l'application

Afin d'être référencé auprès de l'IDP, il faut au préalable fournir un fichier metadata auprès de ce dernier. Une fois les certificats générés et l'application paramétrée,
le `metadata` applicatif sera accessible depuis la route: ${urlDeMonApplication}/metadata-saml


## Licence


`hornet-js-passport` est sous [licence cecill 2.1](./LICENSE.md).

Site web : [http://www.cecill.info](http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.html)

---
_Source: https://npm.io/package/hornet-js-passport · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
