diff --git a/assets/images/integrations/keycloak/finish-keycloak-configuration.png b/assets/images/integrations/keycloak/finish-keycloak-configuration.png new file mode 100644 index 0000000..3025425 Binary files /dev/null and b/assets/images/integrations/keycloak/finish-keycloak-configuration.png differ diff --git a/assets/images/integrations/keycloak/finish-keycloak-configuration.webp b/assets/images/integrations/keycloak/finish-keycloak-configuration.webp new file mode 100644 index 0000000..7cc0619 Binary files /dev/null and b/assets/images/integrations/keycloak/finish-keycloak-configuration.webp differ diff --git a/assets/images/integrations/keycloak/identity-providers.png b/assets/images/integrations/keycloak/identity-providers.png new file mode 100644 index 0000000..c8a970f Binary files /dev/null and b/assets/images/integrations/keycloak/identity-providers.png differ diff --git a/assets/images/integrations/keycloak/identity-providers.webp b/assets/images/integrations/keycloak/identity-providers.webp new file mode 100644 index 0000000..c17166c Binary files /dev/null and b/assets/images/integrations/keycloak/identity-providers.webp differ diff --git a/assets/images/integrations/keycloak/manage-oauth2-applications.png b/assets/images/integrations/keycloak/manage-oauth2-applications.png new file mode 100644 index 0000000..d403a5c Binary files /dev/null and b/assets/images/integrations/keycloak/manage-oauth2-applications.png differ diff --git a/assets/images/integrations/keycloak/manage-oauth2-applications.webp b/assets/images/integrations/keycloak/manage-oauth2-applications.webp new file mode 100644 index 0000000..bcbbaf9 Binary files /dev/null and b/assets/images/integrations/keycloak/manage-oauth2-applications.webp differ diff --git a/assets/images/integrations/keycloak/new-oauth2-application.png b/assets/images/integrations/keycloak/new-oauth2-application.png new file mode 100644 index 0000000..60f9b7a Binary files /dev/null and b/assets/images/integrations/keycloak/new-oauth2-application.png differ diff --git a/assets/images/integrations/keycloak/new-oauth2-application.webp b/assets/images/integrations/keycloak/new-oauth2-application.webp new file mode 100644 index 0000000..6e9f8e4 Binary files /dev/null and b/assets/images/integrations/keycloak/new-oauth2-application.webp differ diff --git a/assets/images/integrations/keycloak/redirect-uri.png b/assets/images/integrations/keycloak/redirect-uri.png new file mode 100644 index 0000000..66670dc Binary files /dev/null and b/assets/images/integrations/keycloak/redirect-uri.png differ diff --git a/assets/images/integrations/keycloak/redirect-uri.webp b/assets/images/integrations/keycloak/redirect-uri.webp new file mode 100644 index 0000000..9c0c48c Binary files /dev/null and b/assets/images/integrations/keycloak/redirect-uri.webp differ diff --git a/content/integrations/keycloak.md b/content/integrations/keycloak.md new file mode 100644 index 0000000..5f29d0c --- /dev/null +++ b/content/integrations/keycloak.md @@ -0,0 +1,84 @@ +--- +eleventyNavigation: + key: KeycloakIntegration + title: Integrating with Keycloak + parent: Integrations +--- + +This article will guide you through integrating Codeberg with Keycloak, allowing you to use Codeberg as an authentication provider. + +**DISCLAIMER:** 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: +> +> ```shell data-line 2 +> 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 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**"](https://codeberg.org/user/settings/applications). You should be able to find a section called *Manage OAuth2 Applications*. + +> **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: +> . + +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*](https://codeberg.org/.well-known/openid-configuration) 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)*](https://docs.gitea.com/next/development/oauth2-provider#supported-oauth2-grants) 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!