{"id":31897917,"url":"https://github.com/jcmturner/authenvoy","last_synced_at":"2025-10-13T11:49:25.423Z","repository":{"id":57565618,"uuid":"158928857","full_name":"jcmturner/authenvoy","owner":"jcmturner","description":"Authentication ambassador, ReST to Kerberos proxy","archived":false,"fork":false,"pushed_at":"2020-11-04T15:19:38.000Z","size":40,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-06-20T08:19:34.644Z","etag":null,"topics":["ambassador","authentication","kerberos"],"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/jcmturner.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}},"created_at":"2018-11-24T11:18:28.000Z","updated_at":"2024-01-26T15:37:22.000Z","dependencies_parsed_at":"2022-09-03T11:21:10.030Z","dependency_job_id":null,"html_url":"https://github.com/jcmturner/authenvoy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jcmturner/authenvoy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcmturner%2Fauthenvoy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcmturner%2Fauthenvoy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcmturner%2Fauthenvoy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcmturner%2Fauthenvoy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcmturner","download_url":"https://codeload.github.com/jcmturner/authenvoy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcmturner%2Fauthenvoy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279014818,"owners_count":26085595,"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-10-13T02:00:06.723Z","response_time":61,"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":["ambassador","authentication","kerberos"],"created_at":"2025-10-13T11:49:15.607Z","updated_at":"2025-10-13T11:49:25.404Z","avatar_url":"https://github.com/jcmturner.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# authenvoy\n[![Go Report Card](https://goreportcard.com/badge/github.com/jcmturner/authenvoy)](https://goreportcard.com/report/github.com/jcmturner/authenvoy) [![build status](https://github.com/jcmturner/authenvoy/workflows/v1/badge.svg)](https://github.com/jcmturner/authenvoy/actions?query=workflow%3Av1)\n\nauthenvoy provides a simple ReST interface for performing user authentication against a Kerberos Domain Controller (KDC).\n\n![connectivity diagram](diagram.svg)\n\nThe aim is to make it simpler for applications that use form based authentication to securely validate the credentials that are posted to them.\n\n### Connectivity\nThe authenvoy implements the ambassador pattern.\n\nThe connection from the application to authenvoy is over loopback and therefore does not traverse the network.\nThis is enforced as authenvoy is coded to _only_ listen on loopback.\nBy default HTTP (not HTTPS) is used between the application and the authenvoy in order to avoid the complexity of certificate management.\nIf encryption is desired this can be turned on with the ``-tls`` switch. With this option set authenvoy automatically \ngenerates a self signed certificate for encryption. Self signed is sufficient as the loopback interface cannot be spoofed by a remote host.\n\nThe connection to the KDC uses the kerberos protocol.\n\nThe net result is that the **user's credentials are never sent over the network** other than when they are posted into the application.\n\n### Usage\n#### Input\nFrom the application POST user credentials to the following endpoint:\n```\nhttp://localhost:8088/v1/authenticate\n```\n(the port number is configurable)\n\nThe user's credentials can be sent either a a JSON document or as an HTTP form:\n##### JSON POST\nWhen POSTing credentials in JSON the following format must be used:\n```json\n{\n\t\"LoginName\": \"loginname\",\n\t\"Domain\": \"EXAMPLE.COM\",\n\t\"Password\": \"passwordvalue\"\n}\n```\n##### Form POST\nCredentials can be sent by POSTing as a form.\nWhen doing this the ``Content-Type`` header must be set to:\n```\napplication/x-www-form-urlencoded\n```\nThe following form fields must be provided:\n* ``login-name``\n* ``domain``\n* ``password``\n\n#### Output\nThe response from the authenvoy ReST API will be in JSON form.\n##### Successful Authentication\nBelow is an example of successful authentication:\n```json\n{\n    \"Valid\": true,\n    \"Domain\": \"USER.GOKRB5\",\n    \"LoginName\": \"testuser1\",\n    \"DisplayName\": \"Test1 User1\",\n    \"Groups\": [\n        \"S-1-5-21-2284869408-3503417140-1141177250-1110\",\n        \"S-1-5-21-2284869408-3503417140-1141177250-513\",\n        \"S-1-5-21-2284869408-3503417140-1141177250-1109\",\n        \"S-1-5-21-0-0-0-497\",\n        \"S-1-18-1\"\n    ],\n    \"AuthTime\": \"2018-11-30T12:00:41Z\",\n    \"SessionID\": \"d6e7d370-498a-d6fc-a01d-c228fdb9a2e9\",\n    \"Expiry\": \"2018-11-30T22:00:41Z\"\n}\n```\nYour code **MUST** check the \"Valid\" field.\nOther information about the user is also provided. \nMost of this information is self explanatory but some additional information is available if Active Directory (AD) is used as the KDC.\n* ``DisplayName`` - the full display name of the user in AD\n* ``Groups`` - a list of the groups the user is a member of. These are the underlying SIDs of the AD groups. \nThe group SIDs can be used for authorization in your application.\n\nIn addition a unique ``SessionID`` is provided. \nThis can be used in the application and is logged in the authenvoy's logs to allow tracing of the user session including the authentication.\n\nThe application can choose to use the ``Expiry`` time for re-authentication. \nThis is derived from the KDC's configuration for the maximum age of tickets.\n\n##### Failed Authentication\nIf authentication fails the response will be:\n```json\n{\n    \"Valid\": false,\n    \"Domain\": \"USER.GOKRB5\",\n    \"LoginName\": \"testuser1\",\n    \"DisplayName\": \"testuser1\",\n    \"Groups\": null,\n    \"AuthTime\": \"0001-01-01T00:00:00Z\",\n    \"SessionID\": \"\",\n    \"Expiry\": \"0001-01-01T00:00:00Z\"\n}\n```\n\n### Configuration\nThere are only four configurations needed for authenvoy:\n```\nUsage of ./authenvoy:\n  -krb5-conf string\n    \tPath to krb5.conf file. (default \"./krb5.conf\")\n  -log-dir string\n    \tDirectory to output logs to. (default \"./\")\n  -port int\n    \tPort to listen on loopback. (default 8088)\n  -tls\n    \tEnable TLS using self signed certificate.\n  -version\n    \tPrint version information.\n```\nFor the krb5.conf file please see: https://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html\n\nLog files will be placed in the directory specified by the -log-dir argument.\nThere are three special values to this argument:\n* ``stdout`` - all log lines will be sent to stdout.\n* ``stderr`` - all log lines will be sent to stderr.\n* ``null`` - all log lines will be discarded.\n\nThe log files generated are:\n* ``event.log`` - this tracks the authentication requests and steps to process it.\n* ``access.log`` - this provides HTTP style access logging in a structured JSON format.\n* ``authenvoy.log`` - this provides logging of any errors or information from the authenvoy process.\n\nThe ``-tls`` switch will result in authenvoy generating a self signed certificate on start up and using this for a TLS \nencrypted connection over the loopback interface. Self signed is sufficient as the loopback interface address cannot be \nspoofed by a remote host. It will require the application to ignore certificate validation errors when talking to \nauthenvoy as there is no trusted certificate authority involved. The certificate generated is not persisted and a new \none is generated each time authenvoy is started. \nThe aim here is to achieve encryption, we do not need to rely on the certificate to provide trust of identity as we are \nonly talking to the loopback interface, not a remote network device.\n\n\n### Building\n```\ngo build -ldflags \"-X main.buildtime=`date -u '%FT%T%Z'` -X main.buildhash=`git rev-parse HEAD`\"\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcmturner%2Fauthenvoy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcmturner%2Fauthenvoy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcmturner%2Fauthenvoy/lists"}