habsi/authentik
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

website/integrations: improve Gitea doc (#14194)

Browse Source 
* Updating to new formatting rules, added note based on GH issue, wording improvements.

* Updated formatting, added testing configuration step, numbered steps, imrpoved wording

* Added numbered steps to the Gitea instructions and changed the navigation steps.

* Changed indenting on codeblocks

* Alterations based on feedback

* Altered icon urls and italicization

* changed line 52 to use png instead of svg

* Update website/integrations/services/gitea/index.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Update website/integrations/services/gitea/index.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Update website/integrations/services/gitea/index.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* changed <application lsug> to <slug>

* Update website/integrations/services/gitea/index.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Update website/integrations/services/gitea/index.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Minor changes to wording/formatting and added a resources section

* Update website/integrations/services/gitea/index.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Update website/integrations/services/gitea/index.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Update website/integrations/services/gitea/index.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Update website/integrations/services/gitea/index.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Dewi Roberts <dewi@goauthentik.io>

* Added missing punctuation

* a few tweaks, and bumb to rebuild

---------

Signed-off-by: Dewi Roberts <dewi@goauthentik.io>
Co-authored-by: Dominic R <dominic@sdko.org>
Co-authored-by: Tana M Berry <tana@goauthentik.io>
This commit is contained in:
Dewi Roberts
2025-05-01 15:54:52 +01:00
committed by GitHub
parent a5edaabec0
commit d04a66ad9a
1 changed files with 98 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

192
website/integrations/services/gitea/index.md
View File

@ -10,10 +10,6 @@ support_level: community
> >
> -- https://gitea.io/ > -- https://gitea.io/
:::note
This is based on authentik 2022.10.1 and Gitea 1.17.3 installed using the official docker image [https://docs.gitea.io/en-us/install-with-docker/](https://docs.gitea.io/en-us/install-with-docker/). Instructions may differ between versions.
:::
## Preparation ## Preparation
The following placeholders are used in this guide: The following placeholders are used in this guide:
@ -38,161 +34,169 @@ To support the integration of Gitea with authentik, you need to create an applic
- **Choose a Provider type**: select **OAuth2/OpenID Connect** as the provider type. - **Choose a Provider type**: select **OAuth2/OpenID Connect** as the provider type.
- **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations.
- Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later. - Note the **Client ID**,**Client Secret**, and **slug** values because they will be required later.
- Set a `Strict` redirect URI to <kbd>https://<em>gitea.company</em>/user/oauth2/authentik/callback</kbd>. - Set a `Strict` redirect URI to `https://<gitea.company>/user/oauth2/authentik/callback`.
- Select any available signing key. - Select any available signing key.
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page. - **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
3. Click **Submit** to save the new application and provider. 3. Click **Submit** to save the new application and provider.
### Step 3 ## Gitea configuration
Navigate to the _Authentication Sources_ page at https://gitea.company/admin/auths and click `Add Authentication Source` 1. Log in to Gitea as an admin, then click on your profile icon at the top right and select **Site Administration**.
2. Select the **Authentication Sources** tab and then click on **Add Authentication Source**.
Change the following fields 3. Set the following required configurations:
- **Authentication Name**: `authentik` (This must match the name used in the **Redirect URI** in the previous section)
- Authentication Name: authentik - **OAuth2 Provider**: `OpenID Connect`
- OAuth2 Provider: OpenID Connect - **Client ID (Key)**: Enter the Client ID from authentik.
- Client ID (Key): Step 1 - **Client Secret**: Enter the Client Secret from authentik.
- Client Secret: Step 1 - **Icon URL**: `https://authentik.company/static/dist/assets/icons/icon.png`
- Icon URL: https://authentik.company/static/dist/assets/icons/icon.svg - **OpenID Connect Auto Discovery URL**: `https://authentik.company/application/o/<slug>/.well-known/openid-configuration`
- OpenID Connect Auto Discovery URL: https://authentik.company/application/o/gitea-slug/.well-known/openid-configuration - **Additional Scopes**: `email profile`
- Additional Scopes: `email profile`
![](./gitea1.png) ![](./gitea1.png)
`Add Authentication Source` and you should be done. Your Gitea login page should now have a `Sign in With` followed by the authentik logo which you can click on to sign-in to Gitea with Authentik creds. 4. Click **Add Authentication Source**.
### Step 4 _(optional Claims for authorization management)_ ### Claims for authorization management (optional)
:::note :::note
This step is **optional** and shows how to set claims to control the permissions of users in gitea by adding them to groups. This step is _optional_ and shows how to set claims to control the permissions of users in Gitea by adding them to groups.
::: :::
#### Define Groups #### Create groups
The following groups will be used: The following groups will be created:
- `gituser` for normal Gitea users. - `gituser`: normal Gitea users.
- `gitadmin` for Gitea users with administrative permissions. - `gitadmin`: Gitea users with administrative permissions.
- `gitrestricted` for restricted Gitea users. - `gitrestricted`: restricted Gitea users.
:::note :::note
Users who are in none of these groups will not be able to log in to gitea. Users who are in none of these groups will not be able to log in to gitea.
::: :::
In authentik, create three groups (under _Directory/Groups_) with the _Name_ as mentioned above and leave other settings untouched. 1. Log in to authentik as an administrator, and open the authentik Admin interface.
2. Navigate to **Directory** > **Groups** and click **Create**.
3. Set the group name to `gituser` and click **Create**.
4. Repeat steps 2 and 3 to create two additional groups named `gitadmin` and `gitrestricted`.
5. Click the name of a newly created group and navigate to the **Users** tab.
6. Click **Add existing user**, select the user/s that need Gitea access and click **Add**.
7. Repeat steps 5 and 6 for the two additional groups.
:::note :::note
You can add Members to the groups now or anytime later. You can add users to the groups at any point.
::: :::
#### Create Custom Property Mapping #### Create custom property mapping
In authentik, create a custom property mapping (under _Customization/Property Mappings_) which has the type **Scope Mapping**. 1. Log in to authentik as an admin, and open the authentik Admin interface.
2. Navigate to **Customization** > **Property Mappings** and click **Create**. Create a **Scope Mapping** with the following configurations:
:::note - **Name**: Choose a descriptive name (.e.g `authentik gitea OAuth Mapping: OpenID 'gitea'`)
Only settings that have been modified from default have been listed. - **Scope name**: `gitea`
::: - **Expression**:
- Name: authentik gitea OAuth Mapping: OpenID 'gitea' ```python showLineNumbers
- Scope name: gitea gitea_claims = {}
And as **Expression** set the following: if request.user.ak_groups.filter(name="gituser").exists():
gitea_claims["gitea"]= "user"
if request.user.ak_groups.filter(name="gitadmin").exists():
gitea_claims["gitea"]= "admin"
if request.user.ak_groups.filter(name="gitrestricted").exists():
gitea_claims["gitea"]= "restricted"
```(python) return gitea_claims
gitea_claims = {} ```
if request.user.ak_groups.filter(name="gituser").exists():
gitea_claims["gitea"]= "user"
if request.user.ak_groups.filter(name="gitadmin").exists():
gitea_claims["gitea"]= "admin"
if request.user.ak_groups.filter(name="gitrestricted").exists():
gitea_claims["gitea"]= "restricted"
return gitea_claims 3. Click **Finish**.
```
#### Add the custom Property Mapping to the Gitea Provider #### Add the custom property mapping to the Gitea provider
In authentik, edit the **Gitea** provider (under _Applications/Providers_) by clicking the pencil Icon. 1. Log in to authentik as an admin, and open the authentik Admin interface.
2. Navigate to **Applications** > **Providers** and click on the **Edit** icon of the Gitea provider.
3. Under **Advanced protocol settings** > **Scopes** add the following scopes to **Selected Scopes**:
Unfold the _Advanced protocol settings_ and activate these Mappings: - `authentik default OAuth Mapping: OpenID 'email'`
- `authentik default OAuth Mapping: OpenID 'profile'`
- `authentik default OAuth Mapping: OpenID 'openid'`
- `authentik gitea OAuth Mapping: OpenID 'gitea'`
- authentik default OAuth Mapping: OpenID 'email' 4. Click **Update**.
- authentik default OAuth Mapping: OpenID 'profile'
- authentik default OAuth Mapping: OpenID 'openid'
- authentik gitea OAuth Mapping: OpenID 'gitea'
Click `Update` and the configuration authentik is done.
#### Configure Gitea to use the new claims #### Configure Gitea to use the new claims
:::note :::note
Gitea must set `ENABLE_AUTO_REGISTRATION: true`. For this to function, the Gitea `ENABLE_AUTO_REGISTRATION: true` variable must be set. More information on configurations variables in the [Gitea Configuration Cheat Sheet](https://docs.gitea.com/administration/config-cheat-sheet).
::: :::
Navigate to the _Authentication Sources_ page at https://gitea.company/admin/auths and edit the **authentik** Authentication Source. 1. Log in to Gitea as an admin. Click on your profile icon at the top right > **Site Administration**.
2. Select the **Authentication Sources** tab and edit the **authentik** Authentication Source.
Change the following fields 3. Set the following configurations:
- **Additional Scopes**: `email profile gitea`
- Additional Scopes: `email profile gitea` - **Required Claim Name**: `gitea`
- Required Claim Name: `gitea` - **Claim name providing group names for this source.** (Optional): `gitea`
- Claim name providing group names for this source. (Optional): `gitea` - **Group Claim value for administrator users.** (Optional - requires claim name to be set): `admin`
- Group Claim value for administrator users. (Optional - requires claim name above): `admin` - **Group Claim value for restricted users.** (Optional - requires claim name to be set): `restricted`
- Group Claim value for restricted users. (Optional - requires claim name above): `restricted` 4. Click **Update Authentication Source**.
`Update Authentication Source` and you should be done.
Users without any of the defined groups should no longer be able to log in.
Users of the group **gitadmin** should have administrative privileges, and users in the group **gitrestricted** should be restricted.
## Helm Chart Configuration
authentik can be configured automatically in Gitea Kubernetes deployments via it's [Helm Chart](https://gitea.com/gitea/helm-chart/).
:::note :::note
This is based on authentik 2022.8.2, Gitea v17.2, and Gitea Helm Chart v6.0.1. Instructions may differ between versions. Users who are not part of any defined group will be denied login access.
In contrast, members of the `gitadmin` group will have full administrative privileges, while those in the `gitrestricted` group will have limited access.
::: :::
Add the following to the Gitea Helm Chart `values.yaml` file: ### Helm Chart Configuration
```yaml authentik authentication can be configured automatically in Kubernetes deployments using its [Helm chart](https://gitea.com/gitea/helm-chart/).
Add the following to your Gitea Helm chart `values.yaml` file:
```yaml showLineNumbers title="values.yaml"
gitea: gitea:
oauth: oauth:
- name: "authentik" - name: "authentik"
provider: "openidConnect" provider: "openidConnect"
key: "CLIENT_ID_FROM_AUTHENTIK" #Step 1 key: "<Client ID from authentik>"
secret: "CLIENT_SECRET_FROM_AUTHENTIK" #Step 1 secret: "<Client secret from authentik>"
autoDiscoverUrl: "https://authentik.company/application/o/gitea-slug/.well-known/openid-configuration" autoDiscoverUrl: "https://authentik.company/application/o/<slug>/.well-known/openid-configuration"
iconUrl: "https://goauthentik.io/img/icon.png" iconUrl: "https://authentik.company/static/dist/assets/icons/icon.png"
scopes: "email profile" scopes: "email profile"
``` ```
### Kubernetes Secret ### Kubernetes Secret
Alternatively you can use a Kubernetes secret to set the `key` and `secret` values. You can also utilize a Kubernetes Secret object to store and manage the sensitive `key` and `secret` values.
Create a Kubernetes secret with the following: 1. Create a Kubernetes secret with the following variables:
```yaml ```yaml showLineNumbers
apiVersion: v1 apiVersion: v1
kind: Secret kind: Secret
metadata: metadata:
name: gitea-authentik-secret name: gitea-authentik-secret
type: Opaque type: Opaque
stringData: stringData:
key: "CLIENT_ID_FROM_AUTHENTIK" #Step 1 key: "<Client ID from authentik>"
secret: "CLIENT_SECRET_FROM_AUTHENTIK" #Step 1 secret: "<Client secret from authentik>"
``` ```
Add the following to the Gitea Helm Chart `values.yaml` file: 2. Add the following configurations to your Gitea Helm Chart `values.yaml` file:
```yaml ```yaml showLineNumbers title="values.yaml"
gitea: gitea:
oauth: oauth:
- name: "authentik" - name: "authentik"
provider: "openidConnect" provider: "openidConnect"
existingSecret: gitea-authentik-secret existingSecret: gitea-authentik-secret
autoDiscoverUrl: "https://authentik.company/application/o/gitea-slug/.well-known/openid-configuration" autoDiscoverUrl: "https://authentik.company/application/o/<slug>/.well-known/openid-configuration"
iconUrl: "https://goauthentik.io/img/icon.png" iconUrl: "https://authentik.company/static/dist/assets/icons/icon.png"
scopes: "email profile" scopes: "email profile"
``` ```
## Resources
- [Official Gitea Documentation](https://docs.gitea.com/)
## Configuration verification
To verify that authentik is correctly set up with Gitea, log out and then log back in using the **Sign in with authentik** button.