Passer au contenu principal

Joplin Server

Joplin est une application open source de prise de notes, et Joplin Server est son serveur de synchronisation auto-hébergé. Depuis la version 3.4.1, Joplin Server peut authentifier les utilisateurs via un fournisseur d'identité (IdP) SAML 2.0. Avec Casdoor comme IdP, les utilisateurs se connectent à Joplin Server, et aux applications Joplin qui s'y synchronisent, avec leur compte Casdoor.

Joplin Server vérifie la réponse SAML avec samlify et xml-crypto. xml-crypto ne prend pas en charge la normalisation XML 1.1, que Casdoor utilise par défaut pour signer, donc l'application dans Casdoor doit avoir Enable SAML C14N10 activé. Utilisez la dernière version de Casdoor : les versions plus anciennes signent ces réponses d'une manière que Joplin Server rejette, avec FAILED_TO_VERIFY_SIGNATURE ou avec une erreur de schéma XML.

Les exemples utilisent https://joplin.example.com pour Joplin Server et https://door.example.com pour Casdoor.

Créer l'application dans Casdoor​

  1. Dans la console d'administration Casdoor, ouvrez l'organisation de vos utilisateurs et ajoutez une application, ou ouvrez-en une existante.

  2. Ajoutez l'identifiant d'entité (Entity ID) de Joplin Server et son URL de service consommateur d'assertions (ACS) aux Redirect URLs. L'identifiant d'entité est l'entityID dans le fichier du fournisseur de services (SP) que vous écrivez ci-dessous, Joplin dans l'exemple. L'URL ACS est <APP_BASE_URL>/api/saml :

    Joplin
    https://joplin.example.com/api/saml

  3. Dans l'onglet SAML :

    • Activez Enable SAML C14N10, et laissez SAML C14N10 prefix vide.

    • Activez Enable SAML POST binding. Joplin Server envoie sa requête à Casdoor avec le binding HTTP-POST, donc les métadonnées doivent lister le point de terminaison HTTP-POST de Casdoor.

    • Ajoutez deux lignes aux SAML attributes. Joplin Server lit uniquement ces deux attributs, et les noms sont sensibles à la casse : les attributs Email et DisplayName envoyés par défaut par Casdoor ne comptent pas.

      NameName formatValue
      emailBasic$user.email
      displayNameBasic$user.displayName

      Chaque utilisateur a besoin d'une adresse e-mail dans Casdoor. Joplin Server identifie l'utilisateur grâce à elle.

  4. Enregistrez, et cliquez sur Copy SAML metadata URL. Avec Enable SAML POST binding activé, l'URL se termine par enablePostBinding=true :

    https://door.example.com/api/saml/metadata?application=admin/<application-name>&enablePostBinding=true

  5. Ouvrez l'URL et enregistrez le XML sous idp.xml. Joplin Server lit les métadonnées de l'IdP depuis un fichier, et non depuis une URL.

Préparer Joplin Server​

  1. Écrivez le fichier SP sp.xml. Définissez entityID comme l'identifiant d'entité ajouté aux Redirect URLs, et Location comme l'URL ACS :

    <?xml version="1.0"?>
    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="Joplin">
      <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://joplin.example.com/api/saml" index="1" />
      </md:SPSSODescriptor>
    </md:EntityDescriptor>

  2. Placez idp.xml et sp.xml là où Joplin Server peut les lire. Avec Docker, montez un répertoire, par exemple ./saml:/saml:ro dans docker-compose.yml.

  3. Définissez les variables d'environnement de Joplin Server, par exemple dans son fichier .env :

    APP_BASE_URL=https://joplin.example.com
    API_BASE_URL=https://joplin.example.com
    SAML_ENABLED=true
    SAML_IDP_CONFIG_FILE=/saml/idp.xml
    SAML_SP_CONFIG_FILE=/saml/sp.xml
    SAML_ORGANIZATION_DISPLAY_NAME=Casdoor
    DELETE_EXPIRED_SESSIONS_SCHEDULE=
    VariableDescription
    APP_BASE_URL, API_BASE_URLSAML needs both set to the same URL.
    SAML_ENABLEDTurns on SAML sign-in.
    SAML_IDP_CONFIG_FILEThe path of the IdP metadata from Casdoor.
    SAML_SP_CONFIG_FILEThe path of the SP file.
    SAML_ORGANIZATION_DISPLAY_NAMEOptional. The name that the sign-in page shows above the SAML button.
    DELETE_EXPIRED_SESSIONS_SCHEDULEPar défaut, Joplin Server nettoie les sessions toutes les 6 heures, ce qui oblige les utilisateurs SAML à se reconnecter manuellement ensuite. Une valeur vide désactive cette option.

    Pour autoriser uniquement la connexion SAML, définissez également LOCAL_AUTH_ENABLED=false.

  4. Redémarrez Joplin Server.

Vérifier le résultat​

  1. Ouvrez https://joplin.example.com/login dans une fenêtre de navigateur privée et cliquez sur Login using your organisation account.
  2. Connectez-vous à Casdoor. Joplin Server ouvre sa page d'accueil avec l'utilisateur Casdoor connecté. Un utilisateur qui n'existe pas encore dans Joplin Server est créé lors de cette première connexion, avec l'adresse e-mail et le nom affiché issus de Casdoor.
  3. Dans une application Joplin, choisissez Joplin Server (SAML) comme cible de synchronisation et saisissez https://joplin.example.com. L'application ouvre la page de connexion dans le navigateur. Après votre connexion à Casdoor, Joplin Server affiche un code que vous devez saisir dans l'application pour démarrer la synchronisation.

Dépannage​

SymptomCause and fix
Joplin Server logs FAILED_TO_VERIFY_SIGNATURE: POST /api/samlUpdate Casdoor to the latest version. If it persists, download the metadata again: Joplin Server must have the certificate of the application's current Cert.
Joplin Server logs canonicalization algorithm 'http://www.w3.org/2006/12/xml-c14n11' is not supportedTurn on Enable SAML C14N10 on the application.
Joplin Server logs ERR_EXCEPTION_VALIDATE_XML, about xs:string without a namespace declarationUpdate Casdoor to the latest version. Older versions drop the xs namespace from the response when they sign it.
email must be a string or displayName must be a stringAdd the email and displayName rows to SAML attributes, with these exact names, and check that Disable SAML attributes is off.
Could not login using email "..."Joplin Server already has a local account with a password for this email, and doesn't let SAML sign in to it. Delete or rename the local account in Joplin Server.
The browser opens a Joplin Server URL that ends with [object Object]The IdP metadata has no HTTP-POST endpoint. Turn on Enable SAML POST binding, and download the metadata again with enablePostBinding=true.
Casdoor shows Issuer URI: Joplin doesn't exist in the allowed Redirect URI listAdd the entityID of sp.xml to Redirect URLs.
Casdoor shows AssertionConsumerServiceURL: ... doesn't match the SAML reply URL or the allowed Redirect URI listAdd <APP_BASE_URL>/api/saml to Redirect URLs.

Voir aussi​