Provide a way to access Gitea API through external authentication source #10401

New Issue

GiteaMirror · 2025-11-02T09:06:32-06:00

GiteaMirror commented

2025-11-02 09:06:32 -06:00

Originally created by @bratekarate on GitHub (Mar 9, 2023).

Feature Description

I have the following use case: I have an authorization server running next to my Gitea instance. Gitea is not supposed to do anything related to authentication or authorization other than using session cookies or verifying tokens, i.e. through a public key from said authorization server.

Using the Web UI, this already (kind of) achieved. It is not perfect, as roles (admin role) and group memberships are still managed by Gitea. But I can live with that as long as Gitea does not work with passwords, OTPs, security keys or anything else related to authentication.

However, when using the Rest API or the container registry, things look different. I have to create an API token to get access. This in itself would be fine for me too --- although not perfect --- if there was a way to generate this token without Web UI and without sending password or TOTP.

The example in the docs (https://docs.gitea.io/en-us/api-usage/#generating-and-listing-api-tokens) suggest to either send password/TOTP via curl or use the Web UI. I think this is not enough in the long term.

I know that #13532 has been closed, but I feel the underlying issue is valid: Gitea should be functional without its own authentication capabilities, which should be optional.

It's great that Gitea provides its own, modern authentication features if no dedicated authorization server is used. However, in the long term it would be even greater if Gitea would integrate seamlessly in more complex, sophisticated security architectures.

Screenshots

No response

Originally created by @bratekarate on GitHub (Mar 9, 2023). ### Feature Description I have the following use case: I have an authorization server running next to my Gitea instance. Gitea is not supposed to do anything related to authentication or authorization other than using session cookies or verifying tokens, i.e. through a public key from said authorization server. Using the Web UI, this already (kind of) achieved. It is not perfect, as roles (admin role) and group memberships are still managed by Gitea. But I can live with that as long as Gitea does not work with passwords, OTPs, security keys or anything else related to authentication. However, when using the Rest API or the container registry, things look different. I have to create an API token to get access. This in itself would be fine for me too --- although not perfect --- if there was a way to generate this token without Web UI and without sending password or TOTP. The example in the docs (https://docs.gitea.io/en-us/api-usage/#generating-and-listing-api-tokens) suggest to either send password/TOTP via curl or use the Web UI. I think this is not enough in the long term. I know that #13532 has been closed, but I feel the underlying issue is valid: Gitea should be functional without its own authentication capabilities, which should be optional. It's great that Gitea provides its own, modern authentication features if no dedicated authorization server is used. However, in the long term it would be even greater if Gitea would integrate seamlessly in more complex, sophisticated security architectures. ### Screenshots _No response_

GiteaMirror added the topic/api type/proposal type/feature issue/workaround labels 2025-11-02 09:06:33 -06:00

GiteaMirror commented

2025-11-02 09:06:33 -06:00

@davama commented on GitHub (Apr 13, 2023):

Hello,

Was also looking at this but failed.
We also use an external authoritative server with reverse proxy authentication.

Tried to create a token with python requests.Session with all the session cookies/headers and using basicAuth but still get below which I think I can expected since the user is not managed by gitea nor is the gitea api ready for these types of setups.

{"message":"user does not exist [uid: 12, name: yourusername, keyid: 0]","url":"https://gitea.domain.net/api/swagger"}

if i dont use basicAuth i simply get

{"message":"Only signed in user is allowed to call APIs."}

Would be great to have the api follow similar authentication policies as set for the UI

thanks

@davama commented on GitHub (Apr 13, 2023): Hello, Was also looking at this but failed. We also use an external authoritative server with [reverse proxy authentication](https://docs.gitea.io/en-us/authentication/#reverse-proxy). Tried to create a token with python `requests.Session` with all the session cookies/headers and using basicAuth but still get below which I think I can expected since the user is not managed by gitea nor is the gitea api ready for these types of setups. > {"message":"user does not exist [uid: 12, name: yourusername, keyid: 0]","url":"https://gitea.domain.net/api/swagger"} if i dont use basicAuth i simply get > {"message":"Only signed in user is allowed to call APIs."} Would be great to have the api follow similar authentication policies as set for the UI thanks

GiteaMirror commented

2025-11-02 09:06:33 -06:00

@davama commented on GitHub (Aug 7, 2023):

Was trying this again but with oauth2_client configured on gitea, which works well, but the 3rd party provider JWTs does not seem to be supported by gitea.

Only the JWTs from gitea when gitea "acts" as a oauth2 provider, do the tokens work with api.

Would be nice if the oauth2_client was extended on the api side

@davama commented on GitHub (Aug 7, 2023): Was trying this again but with oauth2_client configured on gitea, which works well, but the 3rd party provider JWTs does not seem to be supported by gitea. Only the JWTs from gitea when gitea "acts" as a [oauth2 provider, do the tokens work with api](https://docs.gitea.com/development/api-usage?_highlight=api&_highlight=token#oauth2-provider). Would be nice if the [oauth2_client](https://docs.gitea.com/administration/config-cheat-sheet?_highlight=oauth2_#oauth2-client-oauth2_client) was extended on the api side

GiteaMirror commented

2025-11-02 09:06:34 -06:00

@stbischof commented on GitHub (Oct 10, 2023):

Same need here. What must be done do get this Feature in?

@stbischof commented on GitHub (Oct 10, 2023): Same need here. What must be done do get this Feature in?

GiteaMirror commented

2025-11-02 09:06:34 -06:00

@philipparndt commented on GitHub (Oct 24, 2024):

After doing some research on the same topic, I found out that there is a way to have an external authentication source for the API.

in the app.ini

[service]
ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true

curl -s -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/v1/user | jq ".id"
1

You can place an authentication reverse proxy in front of your Gitea installation and implement whatever authentication you like. The documentation on https://docs.gitea.com/usage/authentication#reverse-proxy is outdated. I will create a PR for this.

@philipparndt commented on GitHub (Oct 24, 2024): After doing some research on the same topic, I found out that there is a way to have an external authentication source for the API. in the `app.ini` ```ini [service] ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true ``` ```bash curl -s -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/v1/user | jq ".id" 1 ``` You can place an authentication reverse proxy in front of your Gitea installation and implement whatever authentication you like. The documentation on https://docs.gitea.com/usage/authentication#reverse-proxy is outdated. I will create a PR for this.

GiteaMirror commented

2025-11-02 09:06:34 -06:00

@LePau commented on GitHub (Nov 22, 2024):

After doing some research on the same topic, I found out that there is a way to have an external authentication source for the API.

in the app.ini
[service]
ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true
curl -s -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/v1/user | jq ".id"
1
You can place an authentication reverse proxy in front of your Gitea installation and implement whatever authentication you like. The documentation on https://docs.gitea.com/usage/authentication#reverse-proxy is outdated. I will create a PR for this.

This worked great in my scenario - Thank you!

I was already using nginx as a reverse proxy and authelia to authenticate/authorize several apps behind nginx. Gitea was set up a bit differently using authelia as an oauth2 provider.

I was able to use the nginx auth_request directive to authorize any api request that included an auth cookie and return headers that I could pass on to gitea (i.e. X-WEBAUTH-USER).

My custom web app can now access the Gitea API using the same authenticated session they logged into the web app with, without having to use the Gitea web UI to create a PAT, etc...

@LePau commented on GitHub (Nov 22, 2024): > After doing some research on the same topic, I found out that there is a way to have an external authentication source for the API. > > in the `app.ini` > > ```ini > [service] > ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true > ``` > > ```shell > curl -s -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/v1/user | jq ".id" > 1 > ``` > > You can place an authentication reverse proxy in front of your Gitea installation and implement whatever authentication you like. The documentation on https://docs.gitea.com/usage/authentication#reverse-proxy is outdated. I will create a PR for this. This worked great in my scenario - Thank you! I was already using nginx as a reverse proxy and authelia to authenticate/authorize several apps behind nginx. Gitea was set up a bit differently using authelia as an oauth2 provider. I was able to use the nginx auth_request directive to authorize any api request that included an auth cookie and return headers that I could pass on to gitea (i.e. X-WEBAUTH-USER). My custom web app can now access the Gitea API using the same authenticated session they logged into the web app with, without having to use the Gitea web UI to create a PAT, etc...

GiteaMirror commented

2025-11-02 09:06:34 -06:00

@rmathagiarun commented on GitHub (Jan 29, 2025):

@philipparndt @LePau We are currently looking to implement Keycloak token authentication for Git CLI and API access, we would greatly appreciate it if you could share the exact configuration and manifest files used to achieve this integration.

@rmathagiarun commented on GitHub (Jan 29, 2025): @philipparndt @LePau We are currently looking to implement Keycloak token authentication for Git CLI and API access, we would greatly appreciate it if you could share the exact configuration and manifest files used to achieve this integration.

GiteaMirror commented

2025-11-02 09:06:34 -06:00

@Mo0rBy commented on GitHub (Jul 7, 2025):

I have also bumped into needing what I believe this issue is describing.

My specific issue is wanting to use OAuth in order to perform git actions using the HTTP protocol, meaning that my users (who will all authenticate via the external OAuth source) will not be required to setup an SSH key or Access Token in order to clone repos.

I've been learning about git credentials via OAuth and saw the default git-credentials-oauth application configured in Gitea, but quickly realised that this uses Gitea as the authentication source and this doesn't work when using an alternative external service for OAuth authentication.

@Mo0rBy commented on GitHub (Jul 7, 2025): I have also bumped into needing what I believe this issue is describing. My specific issue is wanting to use OAuth in order to perform `git` actions using the HTTP protocol, meaning that my users (who will all authenticate via the external OAuth source) will not be required to setup an SSH key or Access Token in order to clone repos. I've been learning about git credentials via OAuth and saw the default `git-credentials-oauth` application configured in Gitea, but quickly realised that this uses Gitea as the authentication source and this doesn't work when using an alternative external service for OAuth authentication.

GiteaMirror commented

2025-11-02 09:06:35 -06:00

@hramrach commented on GitHub (Aug 19, 2025):

It seems that git operations work with the git oauth helper. Did not try API with oauth.

@hramrach commented on GitHub (Aug 19, 2025): It seems that git operations work with the git oauth helper. Did not try API with oauth.

GiteaMirror commented

2025-11-02 09:06:35 -06:00

@hramrach commented on GitHub (Aug 20, 2025):

Actually logging in with the tea CLI (0.10 and later) using oauth works. That means at least some API endpoints work with oauth at least in some configurations (with external identity provider).

If oauth does not work with API for some people more specific information is needed.

@hramrach commented on GitHub (Aug 20, 2025): Actually logging in with the `tea` CLI (0.10 and later) using oauth works. That means at least some API endpoints work with oauth at least in some configurations (with external identity provider). If oauth does not work with API for some people more specific information is needed.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#10401