{"id":29908757,"url":"https://github.com/passbolt/passbolt-ldap-certificate-bundler","last_synced_at":"2025-08-02T00:43:59.763Z","repository":{"id":302787952,"uuid":"1000275174","full_name":"passbolt/passbolt-ldap-certificate-bundler","owner":"passbolt","description":"A tool for retrieving and configuring LDAPS certificates for Passbolt.","archived":false,"fork":false,"pushed_at":"2025-07-04T07:50:21.000Z","size":32,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-04T08:37:06.979Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/passbolt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-11T14:24:37.000Z","updated_at":"2025-07-04T07:50:25.000Z","dependencies_parsed_at":"2025-07-04T08:48:53.313Z","dependency_job_id":null,"html_url":"https://github.com/passbolt/passbolt-ldap-certificate-bundler","commit_stats":null,"previous_names":["passbolt/passbolt-ldap-certificate-bundler"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/passbolt/passbolt-ldap-certificate-bundler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/passbolt%2Fpassbolt-ldap-certificate-bundler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/passbolt%2Fpassbolt-ldap-certificate-bundler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/passbolt%2Fpassbolt-ldap-certificate-bundler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/passbolt%2Fpassbolt-ldap-certificate-bundler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/passbolt","download_url":"https://codeload.github.com/passbolt/passbolt-ldap-certificate-bundler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/passbolt%2Fpassbolt-ldap-certificate-bundler/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268320361,"owners_count":24231801,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-02T00:43:57.919Z","updated_at":"2025-08-02T00:43:59.703Z","avatar_url":"https://github.com/passbolt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Passbolt LDAPS Certificate Bundler\n\nA tool for retrieving and configuring LDAPS certificates for Passbolt. Automatically retrieves and formats certificate chains from LDAPS servers, handling both standard and self-signed certificates.\n\n## Features\n\n- Retrieves complete certificate chains from LDAPS servers\n- Handles self-signed certificates commonly used in internal LDAP servers\n- Validates certificate chain integrity\n- Supports both PEM and DER output formats\n- Provides detailed debugging information\n- Compatible with Passbolt's LDAPS configuration requirements\n\n## Requirements\n\n### System Requirements\n- [OpenSSL](https://www.openssl.org/) command-line tool\n  - Usually available as package `openssl` in most Linux distributions and package managers\n  - The script uses `openssl s_client` to establish an SSL/TLS connection and retrieve the certificate chain\n- Python 3.11 or higher\n  - Required for running the tool\n  - On Debian/Ubuntu, you may need to install the following additional packages:\n    ```bash\n    sudo apt-get install python3-venv python3-pip build-essential libssl-dev libffi-dev python3-dev\n    ```\n- Pip (Python package installer)\n  - The setup script will attempt to install pip if it is missing, but it is recommended to install it beforehand\n\n### Python Package Requirements\n- cryptography package (installed automatically in the virtual environment)\n\n## Setup\n\nThe tool uses a Python virtual environment to manage dependencies. To set up:\n\n1. Make the setup script executable:\n```shell\nchmod +x setup_python_env.sh\n```\n\n2. Run the setup script:\n- This will create a virtual environment and install all required dependencies. The script will exit when complete.\n```shell\n./setup_python_env.sh\n```\n\n👉 After setup completes, you need to activate the virtual environment once per shell session before running the tool:\n```shell\nsource venv/bin/activate\n```\n\n## Usage\n\n### Basic Usage\n\n1. First, activate the virtual environment in your shell:\n```shell\nsource venv/bin/activate\n```\n\n2. Run the script with your LDAPS server:\n```shell\npython3 ldaps_cert_chain_retriever.py --server your.ldaps.server\n```\n\n3. When you're done, you can deactivate the virtual environment:\n```shell\ndeactivate\n```\n\n### Saving the Certificate Bundle\n\nTo save the certificate bundle to a file:\n```shell\npython3 ldaps_cert_chain_retriever.py --server your.ldaps.server \u003e ldaps_bundle.crt\n```\n\n### Testing\n\nTest the tool using the test mode:\n```shell\npython3 ldaps_cert_chain_retriever.py --test --debug\n```\n\nThe test mode will try multiple test servers and show detailed connection information if --debug is enabled.\n\n## Certificate Installation\n\n### Standard Installation\n\nAfter obtaining the certificate bundle:\n\n1. Copy the certificate to the appropriate location:\n```shell\nsudo cp ldaps_bundle.crt /etc/ssl/certs/\n```\n\n2. Set proper permissions:\n```shell\nsudo chown root:root /etc/ssl/certs/ldaps_bundle.crt\nsudo chmod 644 /etc/ssl/certs/ldaps_bundle.crt\n```\n\n3. Configure your LDAP client to use the certificate by editing `/etc/ldap/ldap.conf`:\n```\nTLS_CACERT /etc/ssl/certs/ldaps_bundle.crt\n```\n\n## Passbolt Integration\n\nPassbolt can be configured to use the LDAPS certificate in two ways:\n\n### 1. Using passbolt.php (Recommended)\n\nAdd the following configuration to your `config/passbolt.php`:\n\n```php\nreturn [\n    'passbolt' =\u003e [\n        'plugins' =\u003e [\n            'directorySync' =\u003e [\n                'security' =\u003e [\n                    'sslCustomOptions' =\u003e [\n                        'enabled' =\u003e true,\n                        'verifyPeer' =\u003e true,\n                        'cadir' =\u003e '/etc/ssl/certs',\n                        'cafile' =\u003e '/etc/ssl/certs/ldaps_bundle.crt',\n                    ],\n                ],\n            ],\n        ],\n    ],\n];\n```\n\n### 2. Using Environment Variables\n\n```shell\n# Enable custom SSL options\nexport PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_ENABLED=true\n\n# Enable peer verification\nexport PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_VERIFY_PEER=true\n\n# Set the CA directory (where system certificates are stored)\nexport PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_CADIR=/etc/ssl/certs\n\n# Set the path to your LDAPS certificate bundle\nexport PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_CAFILE=/etc/ssl/certs/ldaps_bundle.crt\n```\n\n\u003e **Note**: \n\u003e - Environment variables must be in uppercase\n\u003e - Paths should be absolute\n\u003e - Use either the `ldap.conf` method or the Passbolt configuration method, not both\n\n## Docker-Specific Installation\n\nIf you're running Passbolt in Docker, you'll need to:\n\n1. **Get the Certificate Bundle**:\n```shell\npython3 ldaps_cert_chain_retriever.py --server your.ldaps.server \u003e ldaps_bundle.crt\n```\n\n2. **Choose an Installation Method**:\n\n   a. **Using Volume Mount (Recommended)**:\n   ```shell\n   # Add to your docker-compose.yml\n   volumes:\n     - ./ldaps_bundle.crt:/etc/ssl/certs/ldaps_bundle.crt:ro\n   ```\n\n   b. **Using Environment Variables**:\n   ```shell\n   # Add to your docker-compose.yml\n   environment:\n     - PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_ENABLED=true\n     - PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_VERIFY_PEER=true\n     - PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_CADIR=/etc/ssl/certs\n     - PASSBOLT_PLUGINS_DIRECTORY_SYNC_SECURITY_SSL_CUSTOM_OPTIONS_CAFILE=/etc/ssl/certs/ldaps_bundle.crt\n   ```\n\n3. **Restart the Container**:\n```shell\ndocker-compose restart passbolt\n```\n\n\u003e **Note**: \n\u003e - The volume mount method is recommended as it persists across container recreations\n\u003e - Keep your certificate bundle in version control (if appropriate) or a secure location\n\u003e - Update the certificate bundle when it expires or is renewed\n\u003e - Consider using Docker secrets for production environments\n\n## Running the Tool in a Dedicated Container\n\nYou can also build and run this tool in a fully isolated container (without installing Python or dependencies on your host).\n\nA sample `Dockerfile` is provided in the repository.\n\n### Build the container:\n\n```shell\ndocker build -t ldaps-cert-tool .\n```\n\n### Run the tool:\n\n```shell\ndocker run --rm ldaps-cert-tool --server your.ldaps.server --debug\n```\n\n### Save the certificate bundle to a file:\n\n```shell\ndocker run --rm -v $(pwd):/out ldaps-cert-tool --server your.ldaps.server --output /out/ldaps_bundle.crt\n```\n\n- The output bundle will appear in your current directory as `ldaps_bundle.crt`.\n- You can then use it with Passbolt as described above.\n\n\n## Using the Makefile (optional convenience)\n\nA `Makefile` is provided to simplify common operations:\n\n```\nmake build                   # Build the Docker image\nmake run SERVER=your.ldaps.server  # Run the tool interactively (prints certs to stdout)\nmake save SERVER=your.ldaps.server # Save the certificate bundle to ./ldaps_bundle.crt\nmake test                    # Run unit tests inside the container\nmake help                    # Show help\n```\n\n### Build the container:\n\n```shell\nmake build\n```\n\n### Run the tool:\n\n```shell\nmake run SERVER=your.ldaps.server\n```\n\n### Save the certificate bundle to a file:\n\n```shell\nmake save SERVER=your.ldaps.server\n```\n\n- The output bundle will appear in your current directory as `ldaps_bundle.crt`.\n- You can then use it with Passbolt as described above.\n\n### Run unit tests:\n\n```shell\nmake test\n```\n\n## Advanced Debugging\n\n### Using ldapsearch\n\nFor additional debugging, you can use the `ldapsearch` command (from the ldap-utils package):\n\n\u003e **Important**: When testing with Passbolt, execute ldapsearch as the web user, not as root:\n\u003e - Debian/Ubuntu: `www-data`\n\u003e - openSUSE: `wwwrun`\n\u003e - RHEL-based: `nginx`\n\nExample command:\n```shell\nsudo su -s /bin/bash -c 'ldapsearch -x -D \"username\" -W -H ldaps://your_ldap_host -b \"dc=domain,dc=ext\" -d 9' www-data\n```\n\n### Common Issues\n\n1. **Certificate Chain Issues**\n   - Use debug mode to verify the complete certificate chain\n   - Ensure all intermediate certificates are included\n   - Verify the certificate is properly chained for OpenLDAP\n\n2. **Permission Issues**\n   - Verify the web user has read access to the certificate\n   - Check SELinux contexts if applicable\n   - Ensure proper ownership and permissions (644)\n\n3. **Connection Issues**\n   - Verify LDAPS port (636) is accessible\n   - Check firewall rules\n   - Test with debug mode for detailed connection information\n   - Verify DNS resolution for the LDAP server\n\n4. **Passbolt-Specific Issues**\n   - Ensure the certificate is trusted by the Passbolt instance\n   - Verify the certificate configuration in passbolt.php\n   - Check web server user permissions\n   - Verify LDAP connection parameters in Passbolt\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a new Pull Request\n\n## License\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License (AGPL) as published by the Free Software Foundation version 3.\n\nThe name \"Passbolt\" is a registered trademark of Passbolt SA, and Passbolt SA hereby declines to grant a trademark license to \"Passbolt\" pursuant to the GNU Affero General Public License version 3 Section 7(e), without a separate agreement with Passbolt SA.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See GNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License along with this program. If not, see [GNU Affero General Public License v3](https://www.gnu.org/licenses/agpl-3.0.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpassbolt%2Fpassbolt-ldap-certificate-bundler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpassbolt%2Fpassbolt-ldap-certificate-bundler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpassbolt%2Fpassbolt-ldap-certificate-bundler/lists"}