Press / to focus
Codeberg Documentation

Getting Started with Codeberg
What is Codeberg? Your First Steps on Codeberg Install Git Your First Repository The Basics of Issue Tracking Integrated Wiki Email Settings Licensing on Codeberg Frequently Asked Questions
Collaborating with Others
Citable Code Pull requests and Git flow Invite Collaborators Create and Manage an Organization Repository Permissions Resolve Conflicts
Working with Git Repositories
Using .gitignore Configuring Git Clone & Commit via CLI Clone & Commit via Web Merge multiple commits into one Tags and Releases Working with large files
Writing in Markdown
Introduction to Markdown Using Links Topics Preformatted Text Using Images Using Lists Tables in Markdown Markdown FAQ
Security
Setting up two-factor authentication Adding an SSH key to your account Verifying you're connected to Codeberg using SSH fingerprints Adding a GPG key to your account
Codeberg Pages
Using Custom Domains Troubleshooting Example: Docs as Code with Sphinx Pushing output from SSGs into Codeberg Pages Redirects
Advanced Usage
Using Webhooks Generating an Access Token Migrating Repositories
Working with Codeberg's CI
Using Forgejo Actions (Self-hosted)
Integrations with Other Services
Integrating with Keycloak Integrating with Matrix Integrating with Read the Docs
Codeberg Translate
Getting started Manual Component configuration Introduction to Weblate
Improving Codeberg
Contributing Code
Improving the Documentation
Style Guide How to create a new article? Can I preview my article? How to make screenshots for Codeberg Documentation? Documentation Contributor FAQ
Contact

Integrating with Keycloak

This article will guide you through integrating Codeberg with Keycloak, allowing you to use Codeberg as an authentication provider.

Warning

Using Codeberg with Keycloak means that you explicitly trust Codeberg and its operators with managing your identities.

To test configurations on your localhost, the --hostname-url flag can be used to change the Redirect URI and other relevant fields' prefixes. The following example is not persistent between executions:

docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:22.0.0 start-dev \
  --hostname-url=http://127.0.0.1:8080

This instance will be accessible at http://127.0.0.1:8080/admin with the Username and Password, admin.

Creating a new identity provider

From the Keycloak Administration UI, click on "Identity providers" and select "OpenID Connect v1.0" in the "User-defined" section.

Screenshot of the Identity Providers menu. The OpenID Connect v1.0 button is marked with a red box.

You should see a field called Redirect URI that has already been filled out for you. Copy the link to your clipboard and leave the page open.

Screenshot of the Redirect URI field.

Set up an OAuth2 application on Codeberg

On Codeberg, go to "Settings", then "Applications". You should be able to find a section called Manage OAuth2 Applications.

Tip

Applications can also be created under an org as opposed to being tied to one user's account, keeping your Application safe from a single point of failure: https://codeberg.org/org/YOUR_ORG_NAME/settings/applications.

The Application Name can be arbitrary; we will use "My Keycloak Instance" for illustrative purposes. Make sure to paste the Redirect URI that was shown in Keycloak earlier.

Screenshot of Manage OAuth2 Applications section in Application settings on Codeberg.

When you are done, click on the green Create Application button.

You should now see two new fields: Client ID and Client Secret.

Screenshot of the newly created application on Codeberg; it contains some generic information about the application, as well as the Client ID and Client Secret credentials.

Finish configuring Keycloak

Let's finish configuring the OpenID Connect provider on Keycloak.

  • Alias: Arbitrary. For illustrative purposes, we will use oidc. codeberg could be used as well.
  • Display Name: Also arbitrary. Here, we will just use Codeberg.
  • Set Use discovery endpoint to On.
  • Discovery endpoint: https://codeberg.org/.well-known/openid-configuration
  • Client ID: Use the Client ID provided by Codeberg.
  • Client Secret: Use the Client Secret provided by Codeberg.

All other options can be left untouched. The discovery endpoint will be used to fetch all metadata required for your Keycloak instance to work together with Codeberg.

You can also optionally enable the Proof Key for Code Exchange (PKCE) extension in the Show metadata dropdown menu.

In summary, this is what your configuration should look like:

Screenshot of the Identity provider configuration page; it contains all aforementioned configuration options.

Click on the Add/Save button. You will be redirected to the settings of your brand new identity provider. Now, you will be able to use Codeberg to authenticate with the services that you use Keycloak with. Enjoy!

Hey there! 👋 Thank you for reading this article!

Is there something missing, or do you have an idea on how to improve the documentation? Do you want to write your own article?

You're invited to contribute to the Codeberg Documentation at its source code repository, for example, by adding a pull request or joining in on the discussion in the issue tracker.

For an introduction on contributing to Codeberg Documentation, please have a look at the Contributor FAQ.

© Codeberg Docs Contributors. See LICENSE