{"id":16453280,"url":"https://github.com/trallnag/token2go-server","last_synced_at":"2025-08-02T08:33:50.161Z","repository":{"id":63672236,"uuid":"534984617","full_name":"trallnag/token2go-server","owner":"trallnag","description":"Augmentation to auth schemas that provides access to secrets.","archived":false,"fork":false,"pushed_at":"2025-02-03T18:03:39.000Z","size":2570,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-01T22:25:19.660Z","etag":null,"topics":["authn","authz","oauth2","oidc"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trallnag.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2022-09-10T11:59:26.000Z","updated_at":"2023-07-18T09:16:18.000Z","dependencies_parsed_at":"2023-12-11T18:46:17.383Z","dependency_job_id":"f29dd970-982d-4670-a30b-1d377c11e590","html_url":"https://github.com/trallnag/token2go-server","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/trallnag/token2go-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trallnag%2Ftoken2go-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trallnag%2Ftoken2go-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trallnag%2Ftoken2go-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trallnag%2Ftoken2go-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trallnag","download_url":"https://codeload.github.com/trallnag/token2go-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trallnag%2Ftoken2go-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268355682,"owners_count":24237367,"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-02T02:00:12.353Z","response_time":74,"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":["authn","authz","oauth2","oidc"],"created_at":"2024-10-11T10:15:07.062Z","updated_at":"2025-08-02T08:33:50.127Z","avatar_url":"https://github.com/trallnag.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![status](https://img.shields.io/badge/status-active-brightgreen)](#project-status)\n[![release](https://img.shields.io/github/v/release/trallnag/token2go-server)](https://github.com/trallnag/token2go-server/releases)\n[![docker pulls](https://img.shields.io/docker/pulls/trallnag/token2go-server)](https://hub.docker.com/r/trallnag/token2go-server)\n[![codecov](https://codecov.io/gh/trallnag/token2go-server/branch/master/graph/badge.svg?token=YB5AMNQL6L)](https://codecov.io/gh/trallnag/token2go-server)\n\n# Token2go Server \u003c!-- omit from toc --\u003e\n\nThe Token2go server is an augmentation to existing auth schemas that provides\nusers direct and easy access to tokens and secrets in general. In that regard it\nacts as an escape hatch.\n\nIt is aimed at scenarios where users want to work directly and interactively\nwith protected APIs that do not support static secrets or advanced flows like\nthe OAuth 2.0 device code grant.\n\nFor end users, Token2go client libraries (small pieces of code that implement\nflows on the client-side) are probably more interesting than the Token2go server\nitself.\n\nTwo high level features are included:\n\n- **Simple web interface** that presents tokens that are extracted from incoming\n  requests to the end user. Includes quality of life features like directly\n  copying the token into the user's clipboard.\n- **Flows for REPLs** (Jupyter notebooks, small scripts, shells) to\n  automatically retrieve tokens without requiring the user to manually copy and\n  paste tokens into the respective program.\n\nThe Token2go server is supposed to be hosted behind a gateway that performs\nauthentication and / or authorization and that adds the token to the request\nbefore forwarding it to Token2go.\n\nRemember to only provide token access to clients that can be trusted to handle\ntokens directly.\n\n## Table of Contents \u003c!-- omit from toc --\u003e\n\n- [Use Case Examples](#use-case-examples)\n  - [Retrieve OAuth 2.0 access token via web page](#retrieve-oauth-20-access-token-via-web-page)\n  - [Retrieve OAuth 2.0 access token programmatically](#retrieve-oauth-20-access-token-programmatically)\n- [Getting Started](#getting-started)\n- [Configuration](#configuration)\n- [API Endpoints](#api-endpoints)\n- [Token Redirect Flow](#token-redirect-flow)\n- [Project Status](#project-status)\n- [Licensing](#licensing)\n- [Links](#links)\n\n## Use Case Examples\n\n### Retrieve OAuth 2.0 access token via web page\n\nYou have an app that provides access to data. The app is using OAuth 2.0 and\nOIDC. It includes a web interface using authorization code grant. Other apps are\nusing your app as a data source. These apps rely on authorization code grant or\nclient credentials grant in combination with on-behalf-of grant.\n\nNow you have some users that want direct access your app's API from arbitrary\nenvironments like an interactive Jupyter notebook or a small shell script. They\ncan't use the aforementioned approaches. For example it is not feasible to\nprovide every user with their own OAuth 2.0 client. But they still need the\naccess token.\n\nYou could add a simple endpoint to your app that extracts tokens from incoming\nrequests and returns them directly for example as text.\n\nOr you can use the Token2go web interface that also extracts tokes from incoming\nrequests, but also includes a nice page that includes quality of life features\nlike directly copying the token into the user's clipboard.\n\n[Here is a video showcasing the web page and it's functionality](assets/2022-11-20-usecase-token-from-web-page.gif)\n\n### Retrieve OAuth 2.0 access token programmatically\n\nYou have an app that provides access to data. The app is using OAuth 2.0 and\nOIDC. It includes a web interface using authorization code grant. Other apps are\nusing your app as a data source. These apps rely on authorization code grant or\nclient credentials grant in combination with on-behalf-of grant.\n\nNow you have some users that want to access your app's API from arbitrary\nenvironments like an interactive Jupyter notebook or a small shell script. They\ncan't use the aforementioned approaches. For example it is not feasible to\nprovide every user with their own OAuth 2.0 client. The device code grant is not\nsupported. They still need the access token. They don't want to manually copy\nand paste tokens.\n\nOne solution: Host the Token2go server. It provides an interface that can be\nused by programs that can act as a Token2go client. Your users use a small\nlibrary in their interactive program. It leverages a local browser and a\ntemporary local HTTP server to interact with the Token2go server. Tokens are\nredirected securely to the running program using the so called token redirect\nflow.\n\n## Getting Started\n\nDeploy the server behind some sort of gateway or reverse proxy that handles\nAuthN / AuthZ and adds the token to the request's headers before forwarding.\n\nEither build Token2go yourself, use the provided binaries attached to individual\nreleases, or use the provided container images hosted on Docker Hub.\n\n## Configuration\n\nThe Token2go server is configured via environment variables.\n\n### General Core \u003c!-- omit from toc --\u003e\n\n- `T2G_SERVER_PORT`: Optional port for the server to listen on. Defaults to\n  `8080`.\n\n### Token extraction \u003c!-- omit from toc --\u003e\n\n- `T2G_TOKEN_HEADER_NAMES`: Optional list of header names to look for when\n  extracting tokens. List elements separated by commas. Defaults to\n  `Access-Token`, `Authorization`, `Token`, `X-Auth-Request-Access-Token`, and\n  `X-Forwarded-Access-Token`.\n- `T2G_ADD_TOKEN_HEADER_NAMES`: Optional list of additional header names to look\n  for when extracting tokens. List elements separated by commas. Unset by\n  default.\n- `T2G_FALLBACK_TOKEN`: Optional token to use when no token has been extracted.\n  Unset by default.\n\nFor Token2go to work correctly, `T2G_TOKEN_HEADER_NAMES` or\n`T2G_ADD_TOKEN_HEADER_NAMES` must contain the token header name used in your\nenvironment. Check with the `/echo` endpoint.\n\n### User Interface \u003c!-- omit from toc --\u003e\n\n- `T2G_UI_TARGET`: Optional. Name of the product the Token2go server is used\n  with.\n- `T2G_UI_TITLE`: Optional. Override the title.\n- `T2G_UI_DESC1`: Optional. Override description.\n- `T2G_UI_DESC2`: Optional. Add additional second description. Must be valid\n  HTML.\n- `T2G_UI_MISC`: Optional. Add additional section to bottom. Must be valid HTML.\n\nSetting `T2G_UI_TARGET` should be enough.\n\n## API Endpoints\n\n*This is just a very brief overview over the endpoints provided by Token2go. For\nmore comprehensive insights check out the Swagger UI and the flow-related\ndocumentation in this README.*\n\n### Core \u003c!-- omit from toc --\u003e\n\n- `/`: Entrypoint to web page. Calls out to other embedded files.\n- `/token`: Get token as a JSON payload. Used by web page script.\n- `/swagger-ui`: API schema. Essential to understand and use flows.\n\n### Flows \u003c!-- omit from toc --\u003e\n\n- `/flow/redirect/token`: Perform the token redirect flow. Encrypted token is\n  encoded into the redirect URL pointing at provided target.\n\n### Management \u003c!-- omit from toc --\u003e\n\n- `/health`: Check health of Token2go server.\n- `/echo`: Get an echo of request headers, parameters, and more.\n\n## Token Redirect Flow\n\nBasic idea is that a redirect response is used to get the token from the\nToken2go server to the Token2go client (for example a Python script in a Jupyter\nnotebook). The token is send via query parameters in encrypted form making\ntransfer secure even without TLS.\n\n[![redirect-token-flow-sequence-diagram](assets/redirect-token-flow-sequence-diagram.drawio.png)](assets/redirect-token-flow-sequence-diagram.drawio.png)\n\nToken2go client wants to get a token. The client opens this endpoint in the\nuser's browser. Among other input, a public key is provided with the URL as part\nof the query parameters. The server generates a key and encrypts it with the\nprovided public certificate. The key is used to encrypt token data. Encrypted\nkey and data are encoded into query parameters and added to the provided\nredirect URL. Finally, the user is redirected. Probably to a server hosted on\nlocalhost by the Token2go client.\n\nThere is only one endpoint (`/flow/redirect/token`) used in the token redirect\nflow.\n\nHere is how it's supposed to be used and how it works in general:\n\n1. Client setup.\n   1. Start up temporary server on localhost.\n   1. Generate key pair according to requirements.\n   1. Bake input baked into URL query parameters.\n   1. Open this endpoint in user's browser.\n1. Endpoint processing.\n   1. Extract token and stuff.\n   1. Generate key for symmetric encryption.\n   1. Encrypt key using asymmetric encryption.\n   1. Encrypt payload with generated key.\n   1. Bake encrypted key and data into URL query parameters.\n   1. Return redirect to provided target + query parameters.\n1. Receive and process redirection in client.\n   1. Base64 decode key, nonce, and payload.\n   1. Decrypt key with private key.\n   1. Decrypt payload with decrypted key and nonce.\n   1. Retrieve token and other data by unmarshalling.\n\nFor more information please refer to the OpenAPI specification. For example via\nthe `/swagger-ui` endpoint or the schema file\n[`static/swagger.yaml`](static/swagger.yaml) itself.\n\n## Project Status\n\nThe project is maintained by [trallnag](https://github.com/trallnag). Not used\nin production. The server is more or less done, but there are no clients yet.\n\nContributions are welcome, see [`CONTRIBUTING.md`](CONTRIBUTING.md) for more.\n\n## Licensing\n\nThis work is licensed under the\n[Apache License](https://choosealicense.com/licenses/apache-2.0/) (Apache-2.0),\na permissive license whose main conditions require preservation of copyright and\nlicense notices. See [`LICENSE`](LICENSE) for the license text.\n\nThis work comes with an explicit [`NOTICE`](NOTICE) file containing additional\nlegal notices and information.\n\n## Links\n\n- Docker Hub:\n  [hub.docker.com/r/trallnag/token2go-server](https://hub.docker.com/r/trallnag/token2go-server)\n- CodeCov:\n  [app.codecov.io/gh/trallnag/token2go-server](https://app.codecov.io/gh/trallnag/token2go-server)\n- Pre-commit CI:\n  [results.pre-commit.ci/repo/github/534984617](https://results.pre-commit.ci/repo/github/534984617)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrallnag%2Ftoken2go-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrallnag%2Ftoken2go-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrallnag%2Ftoken2go-server/lists"}