{"id":13531624,"url":"https://github.com/collective/pas.plugins.authomatic","last_synced_at":"2025-04-08T04:19:14.948Z","repository":{"id":46284155,"uuid":"44431407","full_name":"collective/pas.plugins.authomatic","owner":"collective","description":"Authomatic OAuth1/OAuth2/OpenID Login Integration with Plone","archived":false,"fork":false,"pushed_at":"2025-04-03T07:56:59.000Z","size":555,"stargazers_count":10,"open_issues_count":19,"forks_count":20,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-03T08:33:52.831Z","etag":null,"topics":["authentication","oauth","oauth2","openid","plone","plone-addon"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pas.plugins.authomatic","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/collective.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","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},"funding":{"github":["plone"]}},"created_at":"2015-10-17T09:35:29.000Z","updated_at":"2025-03-27T18:40:33.000Z","dependencies_parsed_at":"2024-02-01T21:00:27.844Z","dependency_job_id":"5c395a89-4a70-4ded-8fdf-2aa77317b3c3","html_url":"https://github.com/collective/pas.plugins.authomatic","commit_stats":{"total_commits":255,"total_committers":20,"mean_commits":12.75,"dds":"0.44313725490196076","last_synced_commit":"d35f00ea0099d5264531a45dc84c024cdf0de0d9"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collective%2Fpas.plugins.authomatic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collective%2Fpas.plugins.authomatic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collective%2Fpas.plugins.authomatic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collective%2Fpas.plugins.authomatic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/collective","download_url":"https://codeload.github.com/collective/pas.plugins.authomatic/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247773726,"owners_count":20993639,"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","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":["authentication","oauth","oauth2","openid","plone","plone-addon"],"created_at":"2024-08-01T07:01:04.428Z","updated_at":"2025-04-08T04:19:14.942Z","avatar_url":"https://github.com/collective.png","language":"Python","funding_links":["https://github.com/sponsors/plone"],"categories":["Authentication"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\u003cimg alt=\"logo\" src=\"https://raw.githubusercontent.com/collective/pas.plugins.authomatic/main/docs/authomatic.svg\" width=\"70\" /\u003e\u003c/div\u003e\n\n\u003ch1 align=\"center\"\u003eOAuth2 / OpenId Authentication in Plone\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![PyPI](https://img.shields.io/pypi/v/pas.plugins.authomatic)](https://pypi.org/project/pas.plugins.authomatic/)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pas.plugins.authomatic)](https://pypi.org/project/pas.plugins.authomatic/)\n[![PyPI - Wheel](https://img.shields.io/pypi/wheel/pas.plugins.authomatic)](https://pypi.org/project/pas.plugins.authomatic/)\n[![PyPI - License](https://img.shields.io/pypi/l/pas.plugins.authomatic)](https://pypi.org/project/pas.plugins.authomatic/)\n[![PyPI - Status](https://img.shields.io/pypi/status/pas.plugins.authomatic)](https://pypi.org/project/pas.plugins.authomatic/)\n\n\n[![PyPI - Plone Versions](https://img.shields.io/pypi/frameworkversions/plone/pas.plugins.authomatic)](https://pypi.org/project/pas.plugins.authomatic/)\n\n[![Code analysis checks](https://github.com/collective/pas.plugins.authomatic/actions/workflows/code-analysis.yml/badge.svg)](https://github.com/collective/pas.plugins.authomatic/actions/workflows/code-analysis.yml)\n[![Tests](https://github.com/collective/pas.plugins.authomatic/actions/workflows/tests.yaml/badge.svg)](https://github.com/collective/pas.plugins.authomatic/actions/workflows/tests.yaml)\n![Code Style](https://img.shields.io/badge/Code%20Style-Black-000000)\n\n[![GitHub contributors](https://img.shields.io/github/contributors/collective/pas.plugins.authomatic)](https://github.com/collective/pas.plugins.authomatic)\n[![GitHub Repo stars](https://img.shields.io/github/stars/collective/pas.plugins.authomatic?style=social)](https://github.com/collective/pas.plugins.authomatic)\n\n\u003c/div\u003e\n\n## Features\n\n**pas.plugins.authomatic** provides OAuth2 and OpenID login capability for Plone sites by integrating the awesome [Authomatic](https://authomatic.github.io/authomatic/) package.\n\n```\nAuthomatic is a framework agnostic library\nfor Python web applications\nwith a minimalistic but powerful interface\nwhich simplifies authentication of users\nby third party providers like Facebook or Twitter\nthrough standards like OAuth and OpenID.\n```\n*by author Peter Hudec on Authomatic website*\n\n### Supported Providers\n\nOut of the box,  **pas.plugins.authomatic** supports the following providers\n\n#### OAuth 1.0\n\n- Bitbucket\n- Flickr\n- Meetup\n- Plurk\n- Twitter\n- Tumblr\n- UbuntuOne\n- Vimeo\n- Xero\n- Xing\n- Yahoo\n\n#### OAuth 2.0\n\n- Amazon\n- Behance\n- Bitly\n- Cosm\n- DeviantART\n- Eventbrite\n- Facebook\n- Foursquare\n- GitHub\n- Google\n- LinkedIn\n- PayPal\n- Reddit\n- Viadeo\n- VK\n- WindowsLive\n- Yammer\n- Yandex\n\n#### OpenID\n\n- python-openid\n- Google App Engine based OpenID.\n\n\n## Documentation\n\nThis package supports Plone sites using Volto or the Classic UI.\n\n### Volto Frontend\n\n- Endpoint `@login` with GET: Returns list of authentication options\n- Endpoint `@login-authomatic` with GET: Provide information to start the OAuth process.\n- Endpoint `@login-authomatic` with POST: Handles OAuth login and returns a JSON web token (JWT).\n- For Volto sites you must also install [@plone-collective/volto-authomatic](https://github.com/collective/volto-authomatic).\n- Plugin configuration is available in the Control-panel `/controlpanel/authomatic` (linked under users)\n- Example JSON configuration (first level key is the PROVIDER):\n\n```json\n{\n  \"github\": {\n    \"display\": {\n      \"title\": \"Github\",\n      \"cssclasses\": {\n          \"button\": \"plone-btn plone-btn-default\",\n          \"icon\": \"glypicon glyphicon-github\"\n      },\n      \"as_form\": false\n    },\n    \"propertymap\": {\n      \"email\": \"email\",\n      \"link\": \"home_page\",\n      \"location\": \"location\",\n      \"name\": \"fullname\"\n    },\n    \"class_\": \"authomatic.providers.oauth2.GitHub\",\n    \"consumer_key\": \"5c4901d141e736f114a7\",\n    \"consumer_secret\": \"d4692ca3c0ab6cc1f8b28d3ccb1ea15b61e7ef5c\",\n    \"access_headers\": {\n      \"User-Agent\": \"Plone Authomatic Plugin\"\n    }\n  },\n}\n```\n\n### Classic UI\n\n- This package creates a view called `authomatic-handler` where you can login with different providers.\n- The view can be used as well to add an identity from a provider to an existing account.\n- The provider is choosen in the URL so if you call `/authomatic-handler/PROVIDER` you will use PROVIDER to login.\n- Plugin configuration is available in the Controlpanel `@@authomatic-controlpanel` (linked under users)\n- Example JSON configuration (first level key is the PROVIDER):\n\n```json\n{\n  \"github\": {\n    \"display\": {\n      \"title\": \"Github\",\n      \"cssclasses\": {\n          \"button\": \"plone-btn plone-btn-default\",\n          \"icon\": \"glypicon glyphicon-github\"\n      },\n      \"as_form\": false\n    },\n    \"propertymap\": {\n      \"email\": \"email\",\n      \"link\": \"home_page\",\n      \"location\": \"location\",\n      \"name\": \"fullname\"\n    },\n    \"class_\": \"authomatic.providers.oauth2.GitHub\",\n    \"consumer_key\": \"5c4901d141e736f114a7\",\n    \"consumer_secret\": \"d4692ca3c0ab6cc1f8b28d3ccb1ea15b61e7ef5c\",\n    \"access_headers\": {\n      \"User-Agent\": \"Plone Authomatic Plugin\"\n    }\n  },\n}\n```\n\n## Installation\n\nAdd **pas.plugins.authomatic** to the Plone installation using `pip`:\n\n```bash\npip install pas.plugins.authomatic\n```\nor add it as a dependency on your package's `setup.py`\n\n```python\n    install_requires = [\n        \"pas.plugins.authomatic\",\n        \"Products.CMFPlone\",\n        \"plone.restapi\",\n        \"setuptools\",\n    ],\n```\n\nStart Plone and activate the plugin in the addons control-panel.\n\n## Configuration\n\nUsing Classic UI, go to the `Authomatic` controlpanel.\n\n\u003cimg alt=\"Screenshot\" src=\"https://raw.githubusercontent.com/collective/pas.plugins.authomatic/main/docs/plone-control-panel.png\" width=\"300\" /\u003e\n\nConfiguration parameters for the different authorization are provided as JSON text in there. We use JSON because of its flexibility.\n\n\u003cimg alt=\"Screenshot\" src=\"https://raw.githubusercontent.com/collective/pas.plugins.authomatic/main/docs/plugin-settings.png\" width=\"300\" /\u003e\n\nDetails about the configuration of each provider can be found at [Authomatic provider section](https://authomatic.github.io/authomatic/reference/providers.html).\n\nThere are some differences in configuration:\n\n- Value of `\"class_\"` has to be a string, which is then resolved as a dotted path.\n- Each provider can get an optional entry `display` with sub-enties such as:\n\n  - `title` which is used in the templates instead of the section name.\n  - `iconclasses` which is applied in the templates to an span.\n  - `buttonclasses` which is applied in the templates to the button.\n  - `as_form` (true/false) which renders a form for OpenId providers.\n\n- Each provider can get an optional entry `propertymap`.\n  It is a mapping from authomatic/provider user properties to plone user properties, like `\"fullname\": \"name\",`. Look at each providers documentation which properties are available.\n\n## Integration with Entra ID\n\nEnumeration PAS plugin: if you're using **pas.plugins.authomatic** with *Microsoft Entra ID*, we recommend pairing it with [pas.plugins.eea](https://github.com/eea/pas.plugins.eea) for proper user enumeration and metadata synchronization. This complementary plugin enables listing all the Entra ID users and groups and is compatible with both Plone 5 and Plone 6.\n\n## Source Code and Contributions\n\nIf you want to help with the development (improvement, update, bug-fixing, ...) of `pas.plugins.authomatic` this is a great idea!\n\n- [Issue Tracker](https://github.com/collective/pas.plugins.authomatic/issues)\n- [Source Code](https://github.com/collective/pas.plugins.authomatic/)\n\nPlease do larger changes on a branch and submit a Pull Request.\n\nCreator of **pas.plugins.authomatic** is Jens Klein.\n\nWe appreciate any contribution and if a release is needed to be done on PyPI, please just contact one of us.\n\n### Development\n\nYou need a working `python` environment (system, virtualenv, pyenv, etc) version 3.7 or superior.\n\nThen install the dependencies and a development instance using:\n\n```bash\nmake install\n```\n\nTo run tests for this package:\n\n```bash\nmake test\n```\n\nTo lint the codebase:\n\n```bash\nmake lint\n```\n\nBy default we use the latest Plone version in the 6.x series.\n\n### Changelog entries\n\nThe `CHANGES.md` file is managed using [towncrier](https://towncrier.readthedocs.io/). All non trivial changes must be accompanied by an entry in the `news` directory. Using such a tool instead of editing the file directly, has the following benefits:\n\n* It avoids merge conflicts in CHANGES.md.\n* It avoids news entries ending up under the wrong version header.\n\nThe best way of adding news entries is this:\n\n* First create an issue describing the change you want to make. The issue number serves as a unique indicator for the news entry. As example, let's say you have created issue 42.\n\n* Create a file inside of the news/ directory, named after that issue number:\n\n  * For bug fixes: 42.bugfix.\n  * For new features: 42.feature.\n  * For internal changes: 42.internal.\n  * For breaking changs: 42.breaking.\n  * Any other extensions are ignored.\n\n* The contents of this file should be markdown formatted text that will be used as the content of the CHANGES.md entry.\n\nTowncrier will automatically add a reference to the issue when rendering the CHANGES.md file.\n\n### Releasing `pas.plugins.authomatic`\n\nReleasing `pas.plugins.authomatic` is done using a combination of [zest.releaser](https://zestreleaser.readthedocs.io/) and [hatch](https://hatch.pypa.io/latest/).\n\nThe release process consists of three steps: **Pre-release**, **Release**, and **Post-release**.\n\n#### Pre-release\nRun the following command to populate the `CHANGES.md` file with the entries available in the `news/` directory:\n\n```bash\n.venv/bin/prerelease\n```\n\n#### Release\n\n1. Create a new Git tag:\n   ```bash\n   git tag -a {VERSION} -m \"Release {VERSION}\"\n   ```\n2. Build the project:\n   ```bash\n   hatch build\n   ```\n3. Publish the package to PyPI:\n   ```bash\n   hatch publish\n   ```\n\n#### Post-release\nRun the following command to bump the package version, create a new commit, and push all changes to GitHub:\n\n```bash\n.venv/bin/postrelease\n```\n\n## License\n\nThe project is licensed under the GPLv2.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcollective%2Fpas.plugins.authomatic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcollective%2Fpas.plugins.authomatic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcollective%2Fpas.plugins.authomatic/lists"}