{"id":21740146,"url":"https://github.com/bserdar/took","last_synced_at":"2025-07-25T00:10:55.255Z","repository":{"id":66405734,"uuid":"131343035","full_name":"bserdar/took","owner":"bserdar","description":"OIDC Token manager CLI","archived":false,"fork":false,"pushed_at":"2023-03-07T18:43:07.000Z","size":15665,"stargazers_count":6,"open_issues_count":4,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-26T20:51:24.984Z","etag":null,"topics":["jwt-authentication","oidc","oidc-client","token-based-authentication"],"latest_commit_sha":null,"homepage":null,"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/bserdar.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}},"created_at":"2018-04-27T20:42:27.000Z","updated_at":"2023-04-24T20:32:44.000Z","dependencies_parsed_at":"2023-06-11T02:46:44.701Z","dependency_job_id":null,"html_url":"https://github.com/bserdar/took","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bserdar%2Ftook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bserdar%2Ftook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bserdar%2Ftook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bserdar%2Ftook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bserdar","download_url":"https://codeload.github.com/bserdar/took/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248660749,"owners_count":21141341,"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":["jwt-authentication","oidc","oidc-client","token-based-authentication"],"created_at":"2024-11-26T06:12:24.750Z","updated_at":"2025-04-13T03:41:07.094Z","avatar_url":"https://github.com/bserdar.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"Command line token manager for OpenID Connect. Supports authorization\nflow and direct access (resource owner password credentials grant).\n\n# What does it do?\n\nThe main purpose of took is to maintain access tokens for API\ninvocations and refresh them as needed. Once things are set up, you\ncan run:\n\n```\n   took token myapi myuser\n```\nand it should either print out the token for myuser to call myapi,\nor take you through authentication and then print the token. If the\ntoken is expired and if there is a refresh token, it should get you\na new token without any further interaction. Once you have a valid\ntoken, you can do:\n\n```\n   curl -H \"Authorization: Bearer `took token myapi myuser`\" http://myapi\n```\nor\n```\n   curl -H `took token -e myapi myuser`\" http://myapi\n```\n\n\n# Setup\n\nRun\n\n```\n  took setup\n```\n\nIf this is the first time took is run, this will ask you if you want\nto keep your configuration and tokens encrypted on disk. Once you\ndecide whether you want to do that or not and enter your password if\nyou do, the setup command will take you through the setup of an OIDC\nauthorization server based on a known server profile.\n\n * Enter the name of the server profile corresponding to the server you want to authenticate with\n * Assign a name to this authentication configuration\n * You need to enter the following options to create a new authentication configuration:\n    * client id\n    * client secret (not required for public clients)\n    * callback url (not required for password grants)\n    * whether the client will use password grants or not\n\nAfter entering all the information, you can run:\n\n```\n  took token confName userName\n```\n\nThis will take you through authentication, and will print out your token.\n\nServer profile information is stored in /etc/took.yaml. You can add\nmore server profiles by editing that file.\n\nSetup command is only useful to add a new authentication configuration\nbased on a server profile. To add an authentication configuration, use\nthe \"took add\" command.\n\n## Add new authentication server using the \"add\" command\n\nIf your authentication server is not listed as one of the known server\nprofiles (defined in /etc/took.yaml), then you have to use this\nmethod.\n\n```\n  took add oidc \u003coptions\u003e\n```\n\n\nRequired options for oidc:\n * -n Name of the configuration. This is the 'myapi' parameter in the above examples\n * -c Client ID\n * -u Server URL, including domain, excluding protocol specific paths\n\n\nThe following sets up a configuration called 'prod' using OIDC authorization flow:\n```\n  took add oidc -n prod -c 12345 -s abcdef -u https://myserver/realms/myrealm -b http://callback\n```\n\nThen, when you run\n```\n  took token prod myuser\n```\nIt will ask you to visit a URL. That URL will authenticate the user, and redirect to the\ncallback URL, 'http://callback'. Copy this URL, and paste it to the command line, and it should print out a new token.\n\n## Direct Access Grants Flow\n\nTook supports direct access grants. In this flow, took asks username and password, and sends \nthem to the authentication server.\n\n```\n  took add oidc -n prod-direct -c 12345 -s abcdef -u https://myserver/realms/myrealm -f pwd\n```\nTo use this, the authentication server must be configured to support \ndirect access grants flow for this client.\n\n## Refresh Token Flow\n\nTook supports using only refresh token grants. In this flow, took asks for a refresh token\nto send to the authentication server. This is commonly used in conjunction with\noffline refresh tokens.\n\n```\n  took add oidc -n prod-refresh -c 12345 -u https://myserver/realms/myrealm -f refresh\n```\nTo use this, you must already have obtained a refresh token via some other means\n(usually from a web portal).\n\n# Multiple users \n\nTook can maintain tokens for multiple users. If username is omitted, the last username will be used:\n\n```\n  took token myapi user1\n  \u003ctoken for user1\u003e\n\n  took token myapi\n  \u003ctoken for user1\u003e\n\n  took token myapi user2\n  \u003ctoken for user2\u003e\n\n  took token myapi\n  \u003ctoken for user2\u003e\n```\n\n# (In)security\n\nTook can be run in one of three different security modes:\n\n## With Encrypted Configuration and Tokens\n\nTook stores authentication server credentials, access tokens and\nrefresh tokens in ~/.took.yaml. This file is created with owner\nread/write mode, so you might think this is secure enough. However, if\nyou are not comfortable storing plaintext credentials on disk, you\nhave the option to encrypt them with a password. When you run took for\nthe first time, it'll take you through the steps to encrypt the\nconfiguration file. If however you did not want to encrypt then, and\nyou want to encrypt now, run:\n\n```\n  took encrypt\n```\n\nThis will ask you a password to encrypt the configuration file.\n\nOnce the configuration file is encrypted, you have to decrypt it to\nuse it.\n\n```\n  took decrypt -t 10m\n```\n\nThis will ask the encryption password, and if the password is correct,\nstart the decryption server with an idle timeout of 10 minutes. The\nserver will stop after 10 minutes of inactivity. If you do not specify\n-t flag, the default is 10 minutes. You may specify a 0 timeout, which\nwill start a server that will never terminate until the current\nterminal session logs out.\n\nWarning: Took does not store your password. If you forget it, there is\nno way to recover it.\n\n## With Plaintext Configuration and Tokens\n\nWhen took asks you whether you want to encrypt the configuration or\nnot, answer \"N\", and it will not ask you for a decryption password\nagain. Authentication service credentials, access tokens, and refresh\ntokens will be stored as plaintext in ~/.took.yaml. If this makes you\nuncomfortable, you can run\n\n```\n  took encrypt\n```\n\nto encrypt your configuration file.\n\n## Insecure mode\n\nTook requires you use https:// URLs for your servers, and it validates\nthe server certificates. If you do not want to validate certificates,\nor if you want to call http:// server URLs, you have to run took as\ntook-insecure. You can copy the took executable with that name, or\ncreate a symlink.\n\n```\n  ln -s took took-insecure\n```\n\nWhen run as took-insecure, you can use the -k flag to disable\ncertificate validation. Also, took will not complain if you make calls\nto http:// servers. \n\n# Hack: Bypassing the server login page\n\nIt might be possible to describe the authentication form used by your server, so took can emulate\nwhat the browser does to authenticate a user. When you go to the login page with the browser,\ninspect the HTML page, and identify the forms and input fields. For instance, my server has the following\nform:\n```\n\u003cform id=\"kc-form-login\" class=\"form-horizontal\" onsubmit=\"login.disabled = true; return true;\" \naction=\"https://sso.someserver/auth/realms/myrealm/login-actions/authenticate?code=QWI1Bmwm0\u0026amp;execution=bca7381b-65b-4196-936c-7f8941f121\u0026amp;client_id=security-admin-console\u0026amp;tab_id=uRub-YYUVuk\" method=\"post\"\u003e\n  \u003cdiv class=\"form-group\"\u003e\n    \u003cdiv class=\"col-xs-12 col-sm-12 col-md-4 col-lg-3\"\u003e\n       \u003clabel for=\"username\" class=\"control-label\"\u003eUsername or email\u003c/label\u003e\n    \u003c/div\u003e\n    \u003cdiv class=\"col-xs-12 col-sm-12 col-md-8 col-lg-9\"\u003e\n      \u003cinput tabindex=\"1\" id=\"username\" class=\"form-control\" name=\"username\" value=\"\" type=\"text\" autofocus autocomplete=\"off\" /\u003e\n     \u003c/div\u003e\n  \u003c/div\u003e\n  \u003cdiv class=\"form-group\"\u003e\n    \u003cdiv class=\"col-xs-12 col-sm-12 col-md-4 col-lg-3\"\u003e\n       \u003clabel for=\"password\" class=\"control-label\"\u003ePassword\u003c/label\u003e\n    \u003c/div\u003e\n    \u003cdiv class=\"col-xs-12 col-sm-12 col-md-8 col-lg-9\"\u003e\n      \u003cinput tabindex=\"2\" id=\"password\" class=\"form-control\" name=\"password\" type=\"password\" autocomplete=\"off\" /\u003e\n   \u003c/div\u003e\n\n```\nThis HTML page has a form with id=\"kc-form-login\", containing two input fields: username and password. \nYou can define this structure with the -F flag:\n\n```\ntook add oidc -n myapi -s 123 -b http://callback -c abc -u https://myserver \\\n -F '{\"id\":\"kc-form-login\",\"usernameField\":\"username\",\"passwordField\":\"password\",\"fields\":[{\"input\":\"username\",\"prompt\":\"User name\"},\\\n    {\"input\":\"password\",\"prompt\":\"Password\",\"password\":true}]}'\n```\n\nWhen a new token is requested, took will ask for the username and password fields, submit the HTML\nform, and get the tokens.\n\n# Code Organization\n\nTook is designed as a generic front-end for multiple authentication protocols. Protocol implementations\nshould be under proto/, and included in main.go. When included, protocol implementation registers its\nown command line handlers. Currently there is only OIDC.\n\nThese are the directories:\n\n * cmd/: Files under this package contain all the entry points for commands. There should be no\n   dependency from this package to protocol implementations under proto/.\n * proto/: This package contains a protocol registry, and utility functions common to all protocols.\n   In particular, HTTP utilities in this package should be used for all HTTP calls, because they look\n   at the secure flag and turn off certificate validation\n * proto/oidc: This is the OIDC implementation. When included, this implementation registers command line\n   commands, and registers itself to the registry. \n   * cfg.go: Contains the ServerProfile struct, and the code to merge default configs to user configs\n   * cmd.go: Contains command line commands. The setup wizard is also here.\n   * htmlform.go: Contains the parsing code that reads a login web page,parses login fields, and asks those\n     fields in the command line.\n   * protocol.go: Contains the implementation of 'token' command\n   * refresh.go: Token refresh logic\n   * serverinfo.go: Contains the code to get auth server information (part of oidc spec)\n   * validate.go: Contains token validation code\n * crypta/: This package deals with encrypting/decrypting the tokens file.\n   * crypta.go: Contains the encryption/decryption implementation.\n   * proto.go: Defines a simple rpc protocol \n   * rpc/: This package contains an rpc server and rpc client\n   When took detects that the token file is encrypted, it asks for the user password, and starts\n   another instance of took with an RPC server listening to a domain socket under $HOME. This\n   RPC server contains all the ecnryption/decryption functions unlocked using the user's password.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbserdar%2Ftook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbserdar%2Ftook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbserdar%2Ftook/lists"}