{"id":19153828,"url":"https://github.com/flatpak/flatpak-sample-authenticator","last_synced_at":"2025-10-07T09:25:27.765Z","repository":{"id":71341594,"uuid":"224211550","full_name":"flatpak/flatpak-sample-authenticator","owner":"flatpak","description":"Sample authenticator or flatpak","archived":false,"fork":false,"pushed_at":"2019-12-19T08:21:24.000Z","size":42,"stargazers_count":6,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-28T23:25:52.947Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flatpak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-11-26T14:28:52.000Z","updated_at":"2025-01-05T12:00:45.000Z","dependencies_parsed_at":"2023-07-14T07:15:26.392Z","dependency_job_id":null,"html_url":"https://github.com/flatpak/flatpak-sample-authenticator","commit_stats":{"total_commits":9,"total_committers":2,"mean_commits":4.5,"dds":"0.11111111111111116","last_synced_commit":"d34e54d870860011c8913b5f551bf11ab73272f5"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fflatpak-sample-authenticator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fflatpak-sample-authenticator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fflatpak-sample-authenticator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatpak%2Fflatpak-sample-authenticator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flatpak","download_url":"https://codeload.github.com/flatpak/flatpak-sample-authenticator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252826037,"owners_count":21810035,"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":[],"created_at":"2024-11-09T08:24:28.392Z","updated_at":"2025-10-07T09:25:22.711Z","avatar_url":"https://github.com/flatpak.png","language":"C","readme":"# flatpak-sample-authenticator\n\nThis is a sample implementation of a flatpak authenticator, it expects to find a url to an API server\nin the configuration of the remote, and all authentication calls are proxied to that.\n\nNormally the authenticator would be installed and dbus activated, but to avoid installation complexities \nwhen testing it's easiest to just manually run it from the tree like this:\n\n```\n$ ./flatpak-sample-authenticator -v --replace --no-idle-exit\n```\n\nYou then set up this for use like this:\n```\n$ flatpak remote-add --user \\\n   --authenticator-name=org.flatpak.Authenticator.Sample \\\n   --authenticator-options='{\"url\": \u003c\"http://url.to.api.server.com\"\u003e}' \\\n   test-sample-auth http://url.to.repo.com\n```\n\nFor this to be useful there needs to be an implementation of the API to point at. \nThere is a minimal implementation [here](https://github.com/alexlarsson/flat-auth) which you can use for testing.\n\nThere are some more details docs in the Wiki if you just want to [try it out](https://github.com/flatpak/flatpak/wiki/TestingPurchases).\n\n## Design\n\nFor identification the autheticator uses a token allowing it to do authenticated API calls to the api server. \nThis is just a JWT token signed by the API server that contains a valid-until timestamp and a unique id for the user. \n\nThe first time the authenticator needs to do something it must start by doing a login webflow (see below) to get such a token.\nOnce this is done we save it locally and can reuse it until it is not valid anymore and we have to get a new one.\n\nOnce we have a token the main call is the `get_tokens` API call where you pass in a list of refs and get back a list \nof tokens to use for the ref the user should have access to, and a list of refs the user doesn't have access to.\n\nIf the user doesn't have access to a requested ref, then there is a `begin_purchase` API call which you can use to\ntrigger a webflow to purchase it. On success the authenticator does a new call to `get_tokens` to get the new token.\n\n## Webflows\n\nWebflows are different from regular REST API calls, they are meant to be interactive and shown by a real web-browser. \n\nThey are initiated by the authenticator telling flatpak (or whatever app uses libflatpak) to show a uri to the user.\nThe uri contains a redirect_uri argument, and eventually the web interaction ends with a redirect to this uri, which\npoints back to the authenticator via its `http://localhost:XYZW/` form. This tells the authenticator that the webflow is\ndone (and what the result was).\n\nThis is modeled on how OAuth2 works, and in fact you can easily do the login operation by just chaining to some OAuth2 \nservice of your choice (flat-auth uses google).\n\n## HTTP API\n\n`/api/login`: This is not really a REST api, but a standard location where you can initiate a webflow to log in. \n\n|url args | description |\n|-----|-------------|\n|redirect_uri| At the end of the webflow this uri will be redirected to|\n|state| This will be passed back as an argument in the redirected uri|\n\nIn the final redirected uri, on success the argument `token` will be set to a token you can use for further API calls.\n\n`/api/v1/get_tokens`:\n\nThis is a non-interactive call that takes a json object with arguments, it requires a valid bearer token identifying the user.\n\nGet bearer tokens for a list of app ids (like `org.gnome.eog`).\n\n|args | description |\n|-----|-------------|\n|ids| A list of all the app ids we need tokens to download. |\n\nOn success this returns a json object:\n\n|field | description |\n|-----|-------------|\n|tokens| a dict with keys being ids and the values being tokens for the id. |\n|denied| a list of ids that the user doesn't have access too|\n\n\n`/api/v1/begin_purchase`:\n\nThis is a non-interactive call that takes a json object with arguments, it requires a valid bearer token identifying the user.\n\nInitializes a purchase operation of a particular app id.\n\n|args | description |\n|-----|-------------|\n|id| The app id that the user want to purchase. |\n\n|field | description |\n|-----|-------------|\n|start_uri| A url where you can initiate a webflow, accepts standard `redirect_uri` and `state` args. |\n\nWhen the purchase webflow is successful it will redirect to the `redirect_uri` that was specified, with \nthe passed in `state` as an argument. Additionally it will have a new `redirect_uri` argument that the\nauthenticator will follow for the final display after telling flatpak that the webflow is done. \nThis can be used to display a \"thanks for purchasing $app final landing page\".\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatpak%2Fflatpak-sample-authenticator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflatpak%2Fflatpak-sample-authenticator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatpak%2Fflatpak-sample-authenticator/lists"}