|Hugo Thunnissen c369440a28 Add note about test request||1 month ago|
|nginx-config||1 month ago|
|pictures||1 month ago|
|.gitignore||1 month ago|
|README.md||1 month ago|
|authenticate_handler.go||1 month ago|
|authenticate_handler_test.go||1 month ago|
|cached_key.go||1 month ago|
|config-example.yml||1 month ago|
|config.go||1 month ago|
|database.go||1 month ago|
|go.mod||1 month ago|
|go.sum||1 month ago|
|http_common.go||1 month ago|
|key_cache.go||1 month ago|
|key_cache_test.go||1 month ago|
|main.go||1 month ago|
|verify_user_handler.go||1 month ago|
|verify_user_handler_test.go||1 month ago|
This is a tiny daemon that should help gitea communities to prevent malicious users from abusing the gitea API. To do this it introduces the concept of verified users: A verified user will be able to make API requests, but other users will not.
To let the API protector do its thing, you first need to put an instance of nginx in front of your gitea instance as a reverse proxy. With nginx in place, you can make use of it's auth_request module to authenticate users through a subrequest to the API protector.
Basic idea of what happens:
|===========| Subrequest |=====================| | | ---------------------------> | | | | | Gitea API Protector | | | 200 = OK | | | | <--------------------------- |=====================| | Nginx | | | | | subrequest returned 200, |=======| | | proxy to gitea | | | | ---------------------------> | Gitea | |===========| | | |=======| |===========| Subrequest |=====================| | | ---------------------------> | | | | | Gitea API Protector | | | 401 = Unauthorized | | | | <--------------------------- |=====================| | Nginx | | | | | Subrequest returned 401, |=======| | | NO proxy to gitea | | | | X | Gitea | |===========| | | |=======|
In order to determine whether the user doing the API request is a verified user, the API protector requests the user's ID from gitea, using the user's own token! After requesting the ID, and confirming that the user is indeed verified, the API request is executed as it normally would.
The API protector keeps the keys of verified users in an in-memory cache for a while, so that subsequent requests using the same token can be verified without doing an extra API call to gitea.
You can tell the API Protector which users are verified in a very familiar way: through a pull-request! Instance admins can setup a normal git repository and add a special webhook to it. Through the webhook, gitea will tell the API Protector when a pull-request has been merged. Each time a pull request is merged, the user who created the pull request will become a verified user and is allowed to make use of the API.
The pull request itself can be any change at all, as long as it is merged you are good to go. It is up to the maintainers of the repo to decide what kind of change a pull request should contain to become a verified user. Maybe this is a chance to introduce yourself to your gitea community :)
There are currently two ways to install Gitea API Protector: using the binary release and compiling from source. The instructions below assume that you are installing the software on a linux system. In the case of the binary release, an amd64 linux system is assumed in particular.
tar -xf gitea-api-protector-$VERSION.tar.gz
Compiling from source
git clone email@example.com:hugot/gitea-api-protector.git
git checkout $VERSION
go build .
Configure the application
cp ./config-example.yml ./config.yml && $EDITOR ./config.yml
There are two things that need to be configured for nginx: One is the normal reverse proxy stuff for the Gitea API Protector, the other is changing/configuring your gitea reverse proxy to use the auth_request module.
You can find a reverse proxy config for the Gitea API protector at
./nginx-config/gitea-api-protector.conf. Copy it to wherever nginx config is stored on
your system and edit it. There are
# CHANGE ME! comments above each line that you should
There is also a reverse proxy config for gitea at
can edit this near all the
# CHANGE ME! comments and copy it over, or incorporate what
you need into your existing gitea config if you have one. There are a lot of comments in
the config file to explain which parts are important for both gitea and the API protector
to function properly.
Configure the user verification repository
Now it's time to create the repository that will verify users through pull requests.
https://your-api-protector-domain.tld/verifyas target URL and set “Secret” to the secret you defined in your config.yml
To put your configuration to the test, you can do a test request with
curl as a
curl -X GET 'https://gitea.example.com/api/v1/user' -H 'accept: application/json' -H 'Authorization: bearer YOUR_TOKEN_HERE. Unverified users should get
a 401 response and verified users should get a 200 response containing their user data in