mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 13:52:51 +00:00
d8ea041c56
## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
177 lines
7.9 KiB
Plaintext
177 lines
7.9 KiB
Plaintext
---
|
|
title: ZITADEL with Java Spring Boot
|
|
sidebar_label: Java Spring Boot
|
|
---
|
|
|
|
This integration guide demonstrates the recommended way to incorporate ZITADEL into your Spring Boot web application.
|
|
It explains how to enable user login in your application and how to fetch data from the user info endpoint.
|
|
|
|
By the end of this guide, your application will have login functionality and will be able to access the current user's profile.
|
|
|
|
<Callout>
|
|
This documentation references our [example](https://github.com/zitadel/zitadel-java) on GitHub.
|
|
You can either create your own application or directly run the example by providing the necessary arguments.
|
|
</Callout>
|
|
|
|
## Set up application
|
|
|
|
Before we begin developing our application, we need to perform a few configuration steps in the ZITADEL Console.
|
|
You'll need to provide some information about your app. We recommend creating a new app to start from scratch. Navigate to your Project, then add a new application at the top of the page.
|
|
Select the **Web** application type and continue.
|
|
|
|
|
|
|
|
We recommend that you use [Proof Key for Code Exchange (PKCE)](/apis/openidoauth/grant-types#proof-key-for-code-exchange) for all applications.
|
|
|
|
|
|
|
|
### Redirect URIs
|
|
|
|
The Redirect URIs field tells ZITADEL where it's allowed to redirect users after authentication. For development, you can set dev mode to `true` to enable insecure HTTP and redirect to a `localhost` URI.
|
|
The Post-logout redirect send the users back to a route on your application after they have logged out.
|
|
|
|
<Callout>
|
|
If you are following along with the [example](https://github.com/zitadel/zitadel-java), set the dev mode to `true`, the Redirect URIs to `http://localhost:18080/webapp/login/oauth2/code/zitadel` and Post redirect URI to `http://localhost:18080/webapp`.
|
|
</Callout>
|
|
|
|
|
|
|
|
Continue and create the application.
|
|
|
|
### Client ID
|
|
|
|
After successful creation of the app, a pop-up will appear displaying the app's client ID. Copy the client ID, as you will need it to configure your Java client.
|
|
|
|
|
|
|
|
## Spring setup
|
|
|
|
Now that you have configured your web application on the ZITADEL side, you can proceed with the integration of your Spring client.
|
|
This guide will reference the [example repository](https://github.com/zitadel/zitadel-java) and explain the necessary steps taken in there.
|
|
If your starting from scratch, you can use the Spring Initializer with the [following setup](https://start.spring.io/#!type=maven-project&language=java&platformVersion=3.2.1&packaging=jar&jvmVersion=17&dependencies=web,thymeleaf,security,oauth2-client,lombok) as a base.
|
|
|
|
### Support classes
|
|
|
|
To be able to take the most out of ZITADELs RBAC, we first need to create a GrantedAuthoritiesMapper, that will map the role claims (`urn:zitadel:iam:org:project:roles`)
|
|
into Spring Security `authiorities`, which can be used later on to determine the granted permissions.
|
|
|
|
So in your application, create a 'support/zitadel' package and in there the `ZitadelGrantedAuthoritiesMapper.java`:
|
|
|
|
```java reference
|
|
https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/support/zitadel/ZitadelGrantedAuthoritiesMapper.java
|
|
```
|
|
|
|
The following two classes will provide you the possibility to access and use the user's token for requests to another API, e.g. the Spring Boot API example.
|
|
|
|
Directly create them in the `support` package.
|
|
|
|
```java reference
|
|
https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/support/TokenAccessor.java
|
|
```
|
|
|
|
```java reference
|
|
https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/support/AccessTokenInterceptor.java
|
|
```
|
|
|
|
### Application server configuration
|
|
|
|
As we have now our support classes, we can now create and configure the application server (and API client) itself.
|
|
|
|
In a new `config` package, create first the `WebClientConfig.java`, which will provide a RestTemplate using the previously created AccessTokenInterceptor:
|
|
|
|
```java reference
|
|
https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/config/WebClientConfig.java
|
|
```
|
|
|
|
Additionally also create the `WebSecurityConfig.java` in the same package. This class will take care of the authentication, redirecting the user to the login,
|
|
mapping the claims (using the ZitadelGrantedAuthoritiesMapper) and also provide the possibility for logout:
|
|
|
|
```java reference
|
|
https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/config/WebSecurityConfig.java
|
|
```
|
|
|
|
For the authentication (and the server in general) to work, the application needs some configuration, so please provide the following to your `application.yml` (resources folder):
|
|
|
|
```yaml reference
|
|
https://github.com/zitadel/zitadel-java/blob/main/web/src/main/resources/application.yml
|
|
```
|
|
|
|
Note that both the `issuer-uri` as well as the `client-id` are only placeholders. You can either change them in here using the values provided by ZITADEL
|
|
or pass them later on as arguments when starting the application.
|
|
|
|
### Add pages to your application
|
|
|
|
To be able to serve these pages create a `templates` directory in the `resources` folder.
|
|
Now create three HTML files in the new `templates` folder and copy the content of the examples:
|
|
|
|
**index.html**
|
|
|
|
The home page will display the Userinfo from the authentication context and the granted roles / Spring security authorities.
|
|
|
|
```html reference
|
|
https://github.com/zitadel/zitadel-java/blob/main/web/src/main/resources/templates/index.html
|
|
```
|
|
|
|
**fragments.html**
|
|
|
|
The navigation to switch between the home and tasks page and allows the user to logout.
|
|
|
|
```html reference
|
|
https://github.com/zitadel/zitadel-java/blob/main/web/src/main/resources/templates/fragments.html
|
|
```
|
|
|
|
**tasks.html**
|
|
|
|
The tasks page allows to interact with the Spring Boot API example and display / add new tasks.
|
|
|
|
```html reference
|
|
https://github.com/zitadel/zitadel-java/blob/main/web/src/main/resources/templates/tasks.html
|
|
```
|
|
|
|
**UiController**
|
|
|
|
To serve these pages and handler their actions, you finally need a `UiController.java`:
|
|
|
|
```java reference
|
|
https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/web/UiController.java
|
|
```
|
|
|
|
### Start your application
|
|
|
|
In case you've created your own application and depending on your development setup you might need to build the application first:
|
|
|
|
```bash
|
|
mvn clean package -DskipTests
|
|
```
|
|
|
|
You will need to provide the `issuer-uri` (your Custom Domain) and the `client-id` previously created:
|
|
|
|
```bash
|
|
java \
|
|
-Dspring.security.oauth2.client.provider.zitadel.issuer-uri=<see configuration above> \
|
|
-Dspring.security.oauth2.client.registration.zitadel.client-id=<see configuration above> \
|
|
-jar web/target/web-0.0.2-SNAPSHOT.jar
|
|
```
|
|
|
|
This could look like:
|
|
|
|
```bash
|
|
java \
|
|
-Dspring.security.oauth2.client.provider.zitadel.issuer-uri=https://my-domain.zitadel.cloud \
|
|
-Dspring.security.oauth2.client.registration.zitadel.client-id=243861220627644836@example \
|
|
-jar web/target/web-0.0.2-SNAPSHOT.jar
|
|
```
|
|
|
|
If you then visit on [http://localhost:18080/webapp](http://localhost:18080/webapp) you should directly be redirected to your ZITADEL instance.
|
|
After login with your existing user you will be presented the profile page:
|
|
|
|
|
|
|
|
## Completion
|
|
|
|
Congratulations! You have successfully integrated your Spring Boot web application with ZITADEL!
|
|
|
|
If you get stuck, consider checking out our [example](https://github.com/zitadel/zitadel-java) application.
|
|
This application includes all the functionalities mentioned in this quickstart.
|
|
You can directly start it with your own configuration. If you face issues, contact us or raise an issue on [GitHub](https://github.com/zitadel/zitadel-java/issues).
|