Delegated access management

Hosted Login

Multifactor Authentication

Passwordless Authentication

Audit Trail

Identity Brokering

Platform

Service Accounts

Features

Easy integration

B2B (Business to Business)

Self Service

Existing identities

Secure authentication

Use Cases

Learn how to install, setup, and use ZITADEL.

Documentation

ZITADEL Cloud

Self-hosting

Trust center

Examples and Guides

Github Repository

Develop

Get Started

Contribute

Roadmap

Changelog

About Us

Jobs

Contact

Company

Read the blog

Sign up

Login

Pricing

Blog


## Introduction

In this post, we'll demonstrate how to leverage Postman, a great tool for API development and testing, to explore and validate the APIs provided by ZITADEL. Postman is renowned among developers and testers for its comprehensive suite of features that facilitate the building, testing, and modification of APIs. Its interface simplifies the process of sending requests and analyzing responses, making it a great tool for debugging and making sure that API functionality aligns with security and operational requirements.

The focus of this post will be on using Postman to interact with ZITADEL's APIs, which are used for tasks such as user authentication and token management. We will begin by examining the user login flow, explaining how to authenticate users on a web application and obtain access tokens. 

The objective is to provide developers with practical insights into integrating ZITADEL within their applications. By the end of this post, readers will gain an understanding of ZITADEL's capabilities by making use of the efficiency Postman brings to testing web application security.


## Set Up Postman

Getting started with Postman is straightforward, and it begins with setting up an account and familiarizing yourself with its interface and capabilities. Here's a brief guide to kickstart your journey:

Visit [Postman](https://web.postman.co/home) to create a new account or log in to an existing one. Once logged in, explore the Postman workspace. The interface is designed to be intuitive, with the primary sections being Collections, Environments, and APIs. Collections are groups of requests that can be organized and run together. To create a collection, click the **+** button under **Collections** and give it a name. This is where you'll store the requests you create to test ZITADEL's APIs.

<img src="/blog/2024-03-07-testing-login-with-postman-01.png" alt="Testing User Login Flows in ZITADEL with Postman" />

<img src="/blog/2024-03-07-testing-login-with-postman-02.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Environments in Postman allow you to use variables, making it easier to switch between different sets of data (such as API keys, tokens, and URLs) without changing your requests manually. We will not be using environments in this setup. 


## Set Up ZITADEL

To get started with setting up your environment in ZITADEL, including creating instances, projects, and human users, we recommend following the [ZITADEL's Quick Start Guide](https://zitadel.com/docs/guides/start/quickstart). 

Follow the guide to do the following tasks: 

- [Sign up for the ZITADEL Cloud customer portal and register your organization](https://zitadel.com/docs/guides/start/quickstart#1-sign-up-for-the-zitadel-cloud-customer-portal-and-register-your-organization)
- [Create your first instance](https://zitadel.com/docs/guides/start/quickstart#1-sign-up-for-the-zitadel-cloud-customer-portal-and-register-your-organization)
- [Create your first project](https://zitadel.com/docs/guides/start/quickstart#3-create-your-first-project)
- [Add a user](https://zitadel.com/docs/guides/start/quickstart#4-add-users-optional)


If you are interested in integrating these setup processes into DevOps pipelines or automating them, ZITADEL's APIs offer the flexibility to programmatically create and manage these entities. 

For detailed API references and guides on doing the above programmatically, you can take a look at  [ZITADEL's API documentation](https://zitadel.com/docs/apis/introduction), such as the [Management Service API for creating a project](https://zitadel.com/docs/apis/resources/mgmt/management-service-add-project). These resources offer in-depth insights into the specific APIs you'll need to use for each step of the setup and management process.


## Secure a Web Application: Test User Login


### Set Up a Web Application in ZITADEL

Create a Web Application in your ZITADEL project by selecting **WEB**. Click **Continue**.

<img src="/blog/2024-03-07-testing-login-with-postman-03.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Select **PKCE** and continue. 

<img src="/blog/2024-03-07-testing-login-with-postman-04.png" alt="Testing User Login Flows in ZITADEL with Postman" />

The callback URL needed for this setup is provided by the Postman UI, which is `https://oauth.pstmn.io/v1/browser-callback`. 

<img src="/blog/2024-03-07-testing-login-with-postman-05.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Add the callback URL in ZITADEL as shown below: 

<img src="/blog/2024-03-07-testing-login-with-postman-06.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Check if your application details are correct and click **Create**. 

<img src="/blog/2024-03-07-testing-login-with-postman-07.png" alt="Testing User Login Flows in ZITADEL with Postman" />

You will thereafter receive the **ClientId** for your application without the Client Secret because you don’t need it for the Authorization Code with PKCE grant type. 

<img src="/blog/2024-03-07-testing-login-with-postman-08.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Also note down the **token_endpoint**, **authorization_endpoint** and the **userinfo_endpoint**  from the **URLs** section in your application as shown below:

<img src="/blog/2024-03-07-testing-login-with-postman-09.png" alt="Testing User Login Flows in ZITADEL with Postman" />


### Test the Flow with Postman

Next, we'll walk through testing this authentication flow using Postman.


#### Retrieve the Access Token

Go to the Postman application and open the **Authorization** tab.

<img src="/blog/2024-03-07-testing-login-with-postman-10.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Select **OAuth 2.0** authorization from the drop-down.

<img src="/blog/2024-03-07-testing-login-with-postman-11.png" alt="Testing User Login Flows in ZITADEL with Postman" />

A new panel will be shown with different values. Fill up the values as shown in the image.


- Token: **Available Tokens**
- Header Profile: **Bearer**
- Token Name: *A name of your choice*
- Grant Type: **Authorization Code (With PKCE)**
- Auth URL: *ZITADEL authorization_endpoint you copied earlier*
- Access Token URL: *ZITADEL token_endpoint you copied earlier*
- Client Id: *Your app's client_id*
- Code Challenge Method: **SHA-256**
- Code Verifier: *Keep it blank or provide any string*
- Scope: **openid urn:zitadel:iam:org:project:id:zitadel:aud**
- Client Authentication: **Send as Basic Auth header**

<img src="/blog/2024-03-07-testing-login-with-postman-12.png" alt="Testing User Login Flows in ZITADEL with Postman" />

<img src="/blog/2024-03-07-testing-login-with-postman-13.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Click **Get New Access Token**. 

<img src="/blog/2024-03-07-testing-login-with-postman-14.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Now, if you haven't logged into ZITADEL yet, you'll be redirected to the ZITADEL login page. This simulates the user login experience. Here, enter your email address. 

<img src="/blog/2024-03-07-testing-login-with-postman-15.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Now enter your password.

<img src="/blog/2024-03-07-testing-login-with-postman-16.png" alt="Testing User Login Flows in ZITADEL with Postman" />

New users need to verify their email and set a new password if they haven't done so already.

If the authentication is a success, you will receive the token. Click **Proceed**.

<img src="/blog/2024-03-07-testing-login-with-postman-17.png" alt="Testing User Login Flows in ZITADEL with Postman" />


#### Use the Token

Click **Use Token** within Postman to apply this token for subsequent API calls. This token enables you to interact with your application's APIs or ZITADEL's, such as fetching user information from the userinfo endpoint.

<img src="/blog/2024-03-07-testing-login-with-postman-18.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Now (after clicking **Use Token**), enter the user_info endpoint as the request URL and set Bearer as the **Header Prefix** for authorization as shown below. Click **Send**. 

<img src="/blog/2024-03-07-testing-login-with-postman-19.png" alt="Testing User Login Flows in ZITADEL with Postman" />

The response will be as follows: 

<img src="/blog/2024-03-07-testing-login-with-postman-20.png" alt="Testing User Login Flows in ZITADEL with Postman" />

We didn’t receive user information because we did not specify sufficient scopes. Modify the scope field to include **profile** and **email**, then obtain a new access token.

<img src="/blog/2024-03-07-testing-login-with-postman-21.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Use the new access token this time. And when you send the request to the userinfo endpoint, you will see the following response. 

<img src="/blog/2024-03-07-testing-login-with-postman-22.png" alt="Testing User Login Flows in ZITADEL with Postman" />


#### View User Roles 

By default, user roles are not included in the userinfo response. To include roles, assign a role to a user. You can [add a user](https://zitadel.com/docs/guides/start/quickstart#4-add-users-optional), [add a role](https://zitadel.com/docs/guides/start/quickstart#5-add-roles-to-your-project-optional), and [add the role](https://zitadel.com/docs/guides/start/quickstart#6-add-authorizations-to-your-project) to the user by following the Quick Start Guide. 

However, to see this role information in the response, you must enable the **User roles inside ID Token** option under **Token Settings** in your web application configuration. Click **Save**.

<img src="/blog/2024-03-07-testing-login-with-postman-23.png" alt="Testing User Login Flows in ZITADEL with Postman" />

Now generate a new access token in Postman and send the request. You will now see the role information included in the response. 

<img src="/blog/2024-03-07-testing-login-with-postman-24.png" alt="Testing User Login Flows in ZITADEL with Postman" />


## Wrap-up

Postman's prowess in simplifying API testing, combined with ZITADEL's robust security features, offers a powerful duo for enhancing your web application's authentication process.

Stay tuned for the next installment in our series, where we'll dive into token introspection with ZITADEL and Postman. We'll show you how to verify token validity and understand its scopes, ensuring strong security for your API access. 

This post explains how to integrate ZITADEL's login flow into your web application, guiding you through the setup process step by step, and also how to leverage Postman to test and ensure the login flow works flawlessly.

Test User Login Flows in ZITADEL with Postman


## Introduction

In our [previous post](/blog/testing-login-with-postman), we focused on how to use Postman to test the user login process, detailing the steps for authenticating users in a web application and obtaining an access token. We also illustrated how to use this access token to access ZITADEL's userinfo endpoint, a secured endpoint that requires an access token for access. In this post, we'll guide you through the process of implementing API introspection within your API, ensuring it requires a token to respond to requests. Furthermore, we'll show you how to use Postman to call this secured API.

We can utilize the token obtained from the user login flow in the previous post. However, to guarantee that this token provides the access we require, a minor adjustment to its scopes is essential. By updating the token's scopes, we can align its permissions with the security demands of our target API, facilitating authenticated and authorized interactions. We'll delve into this aspect shortly. First, let's set up a sample API.

## Create an API

This step is optional if you already have an API to test. To create a simple API with two endpoints (a simple `GET` that doesn’t require a token, and a `GET` that checks the token by calling the ZITADEL introspection endpoint) using Node.js and Express, follow these steps. 

### Prerequisites

- Install Node.js


### Step 1: Initialize Your Node.js Project

Create a new directory for your project, initialize a Node.js application, and install the necessary packages as detailed below:

```bash
mkdir zitadel-api
cd zitadel-api
npm init -y
npm install express axios dotenv
```


### Step 2: Set Up Environment Variables

Create a `.env` file in the root of your project directory. Add your ZITADEL credentials and the introspection endpoint URL. To obtain these values, you must create an API application in ZITADEL, which will be done in the next section. 

```plaintext
ZITADEL_CLIENT_ID=<your_client_id>
ZITADEL_CLIENT_SECRET=<your_client_secret>
ZITADEL_INTROSPECTION_ENDPOINT=<https://your-zitadel-instance.com/oauth/v2/introspect>
```


### Step 3: Create the API

Create a file named `app.js` in your project directory. Open it in your text editor and add the following code:

```javascript
require('dotenv').config();
const express = require('express');
const axios = require('axios');
const app = express();

app.use(express.json());

// Simple GET endpoint
app.get('/simple-get', (req, res) => {
   res.send({ message: "This is a simple GET response." });
});

// Protected GET endpoint
app.get('/protected-get', async (req, res) => {
   const authHeader = req.headers.authorization;
   if (!authHeader) {
       return res.status(401).send({ error: "No authorization header provided" });
   }

   const token = authHeader.split(' ')[1];
   try {
       const response = await axios.post(process.env.ZITADEL_INTROSPECTION_ENDPOINT, `token=${token}`, {
           headers: {
               'Content-Type': 'application/x-www-form-urlencoded',
           },
           auth: {
               username: process.env.ZITADEL_CLIENT_ID,
               password: process.env.ZITADEL_CLIENT_SECRET,
           },
       });

       if (!response.data.active) {
           return res.status(403).send({ error: "Inactive token" });
       }

       res.send({ message: "Access to the protected resource granted." });
   } catch (error) {
       console.error("Introspection error:", error.response ? error.response.data : error.message);
       return res.status(500).send({ error: "Failed to introspect token", details: error.response ? error.response.data : error.message });
   }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
   console.log(`Server running on port ${PORT}`);
});

```

This API features two endpoints:

1. **`/simple-get`**: A simple `GET` endpoint that responds with a basic message. This endpoint is public and does not require authentication, making it accessible to any client that makes a request to it and returns a greeting message.

2. **`/protected-get`**: This is a secured `GET` endpoint that requires a valid Bearer token for access. This endpoint demonstrates how to implement token-based authentication in an Express application by:
   - Extracting the token from the `Authorization` header of incoming requests.
   - Using the `axios` HTTP client to send the token to ZITADEL's introspection endpoint, validating the token's activity status.
   - Responding with access to a protected resource if the token is active, or appropriate error messages if the token is missing, inactive, or if there's an error during introspection.


### Step 4: Run Your API

Run your API by executing:

```bash
node app.js
```

Your API is now running on `http://localhost:3000` (or another port if you've configured it differently) and can be tested using Postman.


## Set Up an API Application in ZITADEL 

Go to your ZITADEL project and add a new API application by selecting type **API**. 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-01.png" alt="Testing token introspection in ZITADEL with Postman" />


Click on **Basic** in the next screen because we will be using a Client ID and Client Secret for the API application to authenticate itself when introspecting a token with ZITADEL. Click **Continue**. 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-02.png" alt="Testing token introspection in ZITADEL with Postman" />


In the next screen, review your application details and click **Create**. 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-03.png" alt="Testing token introspection in ZITADEL with Postman" />


Now you will be shown a **Client Id** and **Client Secret**, which you must add to the .env file we created for our Node.js application. 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-04.png" alt="Testing token introspection in ZITADEL with Postman" />


You must also copy the **introspection_endpoint** to add to the .env file. The introspection endpoint can be found in the **URLs** section. 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-05.png" alt="Testing token introspection in ZITADEL with Postman" />


**Note that when testing an API locally (when using localhost), you will need to install the Postman Desktop Agent in your browser. Postman prompts you to install the Desktop Agent on your browser when you try to make a request to localhost.**


## Test the API with Postman


### Test the Non-Secured Endpoint

In Postman, create a new request to test the simple GET endpoint of our API: http://localhost:3000/simple-get. Since this endpoint doesn’t require a token for access, you will get the response as shown below: 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-06.png" alt="Testing token introspection in ZITADEL with Postman" />


### Test the Secured Endpoint

To test the protected endpoint, you need a valid token. Create a new API request in your collection for http://localhost:3000/protected-get. 

Next, go to the **Authorization** tab and select **OAuth 2.0** in the **Type** dropdown as shown below: 


<img src="/blog/2024-03-07-testing-token-introspection-with-postman-07.png" alt="Testing token introspection in ZITADEL with Postman" />


Next, you need to add an access token. You can obtain the access token the same way we did earlier with the PKCE request. However, we have to make a small adjustment in the scope parameter to include the Project ID as shown below. 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-08.png" alt="Testing token introspection in ZITADEL with Postman" />


You must set up the required scopes and claims to ensure that the front-end (Postman) and back-end can exchange data securely. It’s important to note that when specifying the scope when calling the token API, the scope must contain the project ID of the ZITADEL project in which the API resides (to enable token validation by the back-end API). Copy the ID of the project, which you can find in the ZITADEL UI, as highlighted below:  

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-09.png" alt="Testing token introspection in ZITADEL with Postman" />


Go back to Postman and modify the scope field to the following: 
 
**openid profile email urn:zitadel:iam:org:project:id:YOUR_API_PROJECT_ID:aud**. 

Replace API_PROJECT_ID with the ID of the ZITADEL project in which your API resides. 

Get a token, and then send the request. If the token is valid, you will receive a response as shown below: 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-10.png" alt="Testing token introspection in ZITADEL with Postman" />



## Run a Sequence of Requests in Postman

We can automate our requests to the APIs, especially when the execution depends on the outcome of previous requests (like utilizing an obtained token in subsequent calls). This can be managed through Postman's Collection Runner and Pre-request Scripts. Here's how to achieve this, including handling token refreshes:

### Step 1: Set Up an Active Environment and Environment Variables

We need to reuse the access token generated from the Auth Code PKCE request for our subsequent API requests. We can also store auth_url, token_url, client_id, project_id, and access_token as environment variables. To do this, go to the Environments tab in Postman, add a new Environment (the one listed here is Dev), select the environment as the active environment (black tick), and finally add the variable names and their values as shown below.

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-11.png" alt="Testing token introspection in ZITADEL with Postman" />


### Step 2: Set Up Your Postman Collection with the Necessary Requests

We will be using the same requests as we did before with slight changes to include environment variables and a pre-request script in order to use the same access token for all the requests to simulate the typical flow of a user-driven web application. 

1. **Userinfo Endpoint Call**: This initial request authenticates the user and obtains an access token to call ZITADEL’s userinfo endpoint. Assume that this is how the user logs in first to the web application. Notice how the environment variables are used. 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-12.png" alt="Testing token introspection in ZITADEL with Postman" />

2. **Simple GET Call**: A basic request that doesn't require authentication.

3. **Protected API Call**: Requires the token for authentication. Notice how we have set the **Authorization Type** to **Bearer Token** here and refers to the environment variable that we created earlier. 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-13.png" alt="Testing token introspection in ZITADEL with Postman" />



### Step 3: Extract and Store the Token

In the **Tests** tab in your first request (userinfo endpoint call), add the following code to extract the access token from the first request to store it as a variable:


```javascript
if (pm.request.headers.has("Authorization")) {
   let authHeader = pm.request.headers.get("Authorization");
   let accessToken = authHeader.split(" ")[1]; // Assuming the format is "Bearer <token>"
   pm.environment.set("access_token", accessToken);
}
```

Test scripts in Postman are written in JavaScript and run after the response is received. Don’t forget to save the script. 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-14.png" alt="Testing token introspection in ZITADEL with Postman" />


### Step 4: Run Your Postman Collection

Utilize Postman's Collection Runner to run the entire collection. 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-15.png" alt="Testing token introspection in ZITADEL with Postman" />


We are going to run the requests manually. Click the **Run** button to run the test. 

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-16.png" alt="Testing token introspection in ZITADEL with Postman" />


This way you can test the OIDC login flow of your web application along with calling the protected endpoints with the received access token. This approach ensures that you can sequentially execute requests that depend on authentication, and efficiently test both authenticated and non-authenticated endpoints within your Postman collection.

<img src="/blog/2024-03-07-testing-token-introspection-with-postman-17.png" alt="Testing token introspection in ZITADEL with Postman" />


## Wrap-up

In this guide, we've taken you through enhancing API security by integrating ZITADEL's API introspection, with a deep dive into Postman for extensive testing. We developed a straightforward API using Node.js and Express, featuring both public and protected endpoints, to showcase how token introspection with ZITADEL can be practically applied and tested using Postman's comprehensive features. Keep an eye out for our upcoming post, where we'll demonstrate setting up ZITADEL programmatically through Postman.




This post walks you through the process of calling a protected API that utilizes token introspection in ZITADEL. We'll guide you step by step through the setup and demonstrate how to use Postman for effective testing.

Test Token Introspection in ZITADEL with Postman


## Introduction

In our previous two posts, we explored testing with Postman the [PKCE Authorization Code login flow for web applications](/blog/testing-login-with-postman) and [token introspection](/blog/testing-token-introspection-with-postman). This time, we'll show you how to bypass manual setups in the ZITADEL Console by using Postman to programmatically create projects, apps, and users. To get started, you'll need to set up a service user and secure an access token, which will enable you to interact with the ZITADEL management API effectively.


## Add a New Service User to call the Management API

Go to **Users** in the console. Next, click on the **Service Users** tab.


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-01.png" alt="Testing management APIs in ZITADEL with Postman" />


Click on **+New**

<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-02.png" alt="Testing management APIs in ZITADEL with Postman" />

Next, add details and create your service user. 


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-03.png" alt="Testing management APIs in ZITADEL with Postman" />


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-04.png" alt="Testing management APIs in ZITADEL with Postman" />


## Provide Admin Permissions to the Service User

Now you have to add the Service User as an Organization Manager. Go to the Project and click **+** next to **ZA**.

<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-05.png" alt="Testing management APIs in ZITADEL with Postman" />

Now choose **Service User** as the **Org Owner**. Or you can select the relevant roles based on what he can do in the project. 


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-06.png" alt="Testing management APIs in ZITADEL with Postman" />


## Create an Access Token for the Service User

Now go to the Service User’s profile again. We’ll create a Personal Access Token (PAT) to set up things quickly. You can choose to go ahead with Client Credentials as well, but for this demo, we’ll be choosing the **Personal Access Token**. 


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-07.png" alt="Testing management APIs in ZITADEL with Postman" />


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-08.png" alt="Testing management APIs in ZITADEL with Postman" />

## Create a Project via the Management API

You can find more details on how to call the Management API to create a ZITADEL project [here](https://zitadel.com/docs/apis/resources/mgmt/management-service-add-project).

Create a new API request and add the headers as shown below. 

<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-09.png" alt="Testing management APIs in ZITADEL with Postman" />

**Authorization Type** should be **Bearer** and you can add the PAT in the **Token** field. 

<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-10.png" alt="Testing management APIs in ZITADEL with Postman" />

Go to the **Body** tab and add the following: 

```
{
  "name": "MyPostmanProject",
  "projectRoleAssertion": true,
  "projectRoleCheck": true,
  "hasProjectCheck": true,
  "privateLabelingSetting": "PRIVATE_LABELING_SETTING_UNSPECIFIED"
}
```

<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-11.png" alt="Testing management APIs in ZITADEL with Postman" />

Also in the **Tests** tab, set an environment variable to capture the Project Id (when it is returned) as shown below: 

```
let response_body = pm.response.json();
pm.environment.set("project_id", response_body.id); 
```

<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-12.png" alt="Testing management APIs in ZITADEL with Postman" />

Now send the request and you will get a response as shown below: 


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-13.png" alt="Testing management APIs in ZITADEL with Postman" />

And you will also see that an environment variable called `project_id` is set after this call. 


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-14.png" alt="Testing management APIs in ZITADEL with Postman" />

If you go to the ZITADEL console, you will also see that a new project was created. 


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-15.png" alt="Testing management APIs in ZITADEL with Postman" />


## Create an Application via the Management API

Now let’s add our OIDC web application. You can find more details about how to invoke this API [here](https://zitadel.com/docs/apis/resources/mgmt/management-service-add-oidc-app).


Create a new request (**Add OIDC Web App**). Use the `project_id` environment variable in the request URL as shown below. 



<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-16.png" alt="Testing management APIs in ZITADEL with Postman" />

Add Headers. 



<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-17.png" alt="Testing management APIs in ZITADEL with Postman" />

Add the body as follows: 
```
{
 "name": "MyOIDCWebApp",
 "redirectUris": [
   "https://oauth.pstmn.io/v1/browser-callback"
 ],
 "responseTypes": [
   "OIDC_RESPONSE_TYPE_CODE"
 ],
 "grantTypes": [
   "OIDC_GRANT_TYPE_AUTHORIZATION_CODE"
 ],
 "appType": "OIDC_APP_TYPE_WEB",
 "authMethodType": "OIDC_AUTH_METHOD_TYPE_NONE",
 "version": "OIDC_VERSION_1_0",
 "devMode": true,
 "accessTokenType": "OIDC_TOKEN_TYPE_BEARER",
 "accessTokenRoleAssertion": true,
 "idTokenRoleAssertion": true,
 "idTokenUserinfoAssertion": true,
 "clockSkew": "1s",
 "additionalOrigins": [
   "scheme://localhost:8080"
 ],
 "skipNativeAppSuccessPage": true
}
```

<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-18.png" alt="Testing management APIs in ZITADEL with Postman" />

We will also need to store the Client ID to an environment variable, so set up an environment variable called `web_app_client_id`. 


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-19.png" alt="Testing management APIs in ZITADEL with Postman" />

Add the script below to the **Tests** tab of the request. 

```
let response_body = pm.response.json();
pm.environment.set("web_app_client_id", response_body.clientId); 
```


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-20.png" alt="Testing management APIs in ZITADEL with Postman" />

And as before, add the service user’s PAT as the Bearer Token: 



<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-21.png" alt="Testing management APIs in ZITADEL with Postman" />


And you should get the following response. 



<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-22.png" alt="Testing management APIs in ZITADEL with Postman" />

Check if the environment variable is also set for the web app’s client id. 



<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-23.png" alt="Testing management APIs in ZITADEL with Postman" />


Similarly, you can now add the API application to this project as well. See [here](https://zitadel.com/docs/apis/resources/mgmt/management-service-add-api-app) for more details about how to call this API. You can duplicate the previous OIDC web app creation request and change the body as follows: 

```
{
"name": "MyAPIApp",
"authMethodType": "API_AUTH_METHOD_TYPE_BASIC"
}
```

You don’t need any scripts for this request. When you send this request, you will receive the clientId and clientSecret. This needs to be added to the Node API project’s .env file. 


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-24.png" alt="Testing management APIs in ZITADEL with Postman" />

## Create a User via the Management API

Let’s also [add a user](https://zitadel.com/docs/apis/resources/mgmt/management-service-import-human-user) to the project via the API.

Create the request as shown below (you can duplicate the previous request): 


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-25.png" alt="Testing management APIs in ZITADEL with Postman" />

Add the following text to the body:

```
{
"userName": "minnie-mouse",
"profile": {
  "firstName": "Minnie",
  "lastName": "Mouse",
  "nickName": "Mini",
  "displayName": "Minnie Mouse",
  "preferredLanguage": "en",
  "gender": "GENDER_FEMALE"
},
"email": {
  "email": "minnie@mouse.com",
  "isEmailVerified": true
},
"phone": {
  "phone": "+41 71 000 00 00",
  "isPhoneVerified": true
},
"hashedPassword": {
  "value": "$2a$12$k0LsiR40ZNcMxbyD80g5nebjB9R0/VqilwfFLLr6m/XTOc9WRf8Om"
},
"passwordChangeRequired": true,
"requestPasswordlessRegistration": true,
"otpCode": "string"
}
```

<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-26.png" alt="Testing management APIs in ZITADEL with Postman" />

You will receive the following response when you send the request: 


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-27.png" alt="Testing management APIs in ZITADEL with Postman" />


You will now see the new user appearing in the ZITADEL Console: 


<img src="/blog/2024-03-07-testing-zitadel-apis-with-postman-28.png" alt="Testing management APIs in ZITADEL with Postman" />


## Try it out Yourself

You can visit our GitHub repository at [https://github.com/zitadel/example-postman-collections](https://github.com/zitadel/example-postman-collections) to download the collection and environment setup that we covered in our Postman blog series. You can add other types of applications, users and roles via the ZITADEL API to this collection and test out various scenarios. Whether you're looking to automate your authentication flows, manage users, or secure your applications, our Postman collection is a great starting point. Happy testing!


This post walks you through the process of testing the ZITADEL Management API to create ZITADEL Projects, Apps, and Users with Postman.

Test the ZITADEL Management API with Postman

With PBKDF2 support now available, transitioning your users from Keycloak to ZITADEL has become smoother than ever. Dive into this tutorial to master the migration process.

Migrate Users from Keycloak to ZITADEL


We decided to adopt a resource-based API for ZITADEL in response to feedback from our customers and community members.
Our overarching goal has always been to provide an exceptional experience for developers using our platform.
However, through ongoing conversations with users, we came to the understanding that while some of our architecture and design decisions were technically sound, they didn't necessarily translate into an intuitive and user-friendly experience from a developer's perspective.

Our API design was identified as one area where we could significantly enhance the developer experience.
By transitioning to a resource-based API, we are making our system more intuitive and easy to understand.
A resource-based API structure focuses on "resources" as the main entities, as opposed to methods or operations, which aligns better with the way developers think about their interactions with our platform.
We believe this change will make ZITADEL more approachable and enjoyable for developers to use.


## Persona-based API design

ZITADEL's API design is grounded in the concept of personas, each with different use cases.
The distinct APIs cater to these various personas and their specific needs, creating a more personalized and intuitive interface.
For instance, the Authentication API is designed primarily for currently authenticated users.
Therefore, if you're developing a user profile or settings page for authenticated users, the Authentication API would be your main resource. 

<figure>
  <img
    src="/blog/2023-08-03-resource-based-api-01.png"
    width="100%"
    alt="Persona-based API"
  />
  <figcaption>
    Figure 1: Persona-based API design
  </figcaption>
</figure>


Similarly, different APIs are designated for different roles.
The Management API is accessible to the administrator of an organization, while the Admin API is available for the IAM administrator.

At first glance, the division of responsibilities and access based on roles appears to make a lot of sense.
However, when we take into account how developers typically interact with our platform, potential complications become evident.
It's not uncommon for developers to dive straight into implementation without thoroughly studying the documentation. 

Let's take an example: a developer wants to create a settings page for a user and needs to retrieve the user information.
They would go to the API documentation and search for "get user".
This seemingly simple query returns multiple results, each tied to a different API and with different permissions:

- Auth API: "Get my own user"
- Management API: "Get user by ID from my organization"
- Admin API: "Get user by ID from any organization"

Without proper understanding of the differences between these APIs, developers may become confused and unsure about which option is the right one for their needs.
This is the kind of complication we aim to reduce with our new API design.

## Resource-based API design

After considering all the above factors, we have concluded that a resource-based API is significantly more straightforward to understand than a persona-based API.

By "resource-based API", we mean an API that allows access to the various resources ZITADEL provides, irrespective of the user's role or persona.
The fundamental principle here is that users access resources through a single API, and the depth or breadth of the results they see depends on the permissions of the user making the request.
This design simplifies the user's navigation through the API and makes for a more intuitive experience.


<figure>
  <img
    src="/blog/2023-08-03-resource-based-api-02.png"
    width="100%"
    alt="Resource-based API"
  />
  <figcaption>
    Figure 2: Resource-based API design
  </figcaption>
</figure>


Let's take an example of how this resource-based API design works.
Let's say we have a 'users' resource in the API.
This resource supports various operations such as create, update, delete, get by ID, and search for users.

- If I'm an end user, and I request a 'get by id' operation, the API will only permit me to retrieve my own user information, respecting the principle of least privilege.

- If I'm an administrator of an organization, I can utilize the 'search users' operation to retrieve details of all users within my organization, representing a higher level of access.

- Finally, if I'm an Identity and Access Management (IAM) administrator, I can use the 'search users' operation to access information on users across any organization in the system, reflecting the highest level of access.

This approach simplifies interactions by centralizing operations on a single resource, while still maintaining appropriate access control based on the user's role.

## Our Progress and Future Plans

We have already made considerable progress with the new API. 
All the necessary requests to construct your own login and registration UI have been implemented. 
As we continue to expand this new API, we will add new requests and gradually transition existing requests from the previous APIs (Auth, Management, Admin) to this new, resource-based API.

With the full implementation of this new API design, we are confident that we will significantly enhance the developer experience. We believe that these changes will simplify not only our customers' experience but also streamline our own operations. 
We look forward to offering a more efficient, user-friendly platform thanks to this resource-based API design.

Stay tuned for more updates! 


## Read the API Documentation

See the documentation of the currently available API resources of the new API if you want to learn more right away.

- [User](https://zitadel.com/docs/apis/resources/user_service)
- [Session](https://zitadel.com/docs/apis/resources/session_service)
- [Settings](https://zitadel.com/docs/apis/resources/settings_service)
- [OIDC](https://zitadel.com/docs/apis/resources/oidc_service)


We decided to adopt a resource-based API for ZITADEL in response to feedback from our customers and community members.

From Persona-based to Resource-based: Rethinking ZITADELs API Design


[ZITADEL](https://zitadel.com) is an open source identity platform that addresses the challenges of self-service, authentication, and authorization by integrating them into your project. It supports multi-tenancy for business-to-business (B2B), identity brokering, multifactor/passwordless authentication, delegated access management, in-context audit trail, [OpenID Connect](https://openid.net/connect/), SAML 2.0, and [OAuth 2.0](https://oauth.net/2/). 

In contrast, [Firebase](http://firebase.google.com/) is a backend as a service (BaaS) that provides developers with a variety of tools and services to help them build quality applications. It's categorized as a NoSQL database platform because the data is stored in a JSON-like format.

With ZITADEL, you can avoid hours of creating, configuring, and operating complex authentication and authorization systems. Meanwhile, Firebase on the other end provides you with commodity features for all of your backend needs, including cloud messaging, testing, crashlytics, authentication, and real-time databases.

Developing with a powerful and feature-rich platform can be essential in creating a reliable and high-quality mobile and web application. It takes a lot of dedication and time to manage files and resources, server configuration, analytics, and other related operations.

In this article, you'll compare ZITADEL and Firebase authentication and look specifically at where they differ in regard to their authentication and authorization features, integrations, and architecture.

## ZITADEL vs. Firebase

ZITADEL and Firebase can both be used to achieve authentication and authorization in your application. However, there are a few factors, like authentication features and integrations, that can help you decide which platform is best for you. Let's take a look at the authentication features each platform offers:

### Firebase Authentication

The main goal of an authentication provider is to be able to identify each user in your application, which is where Firebase Auth comes into play. With Firebase, you have to obtain an authentication credential from the user in order to sign them into your application. The user's email address and password or an OAuth token from a third-party service can serve as these credentials. If you choose to upgrade to Firebase Authentication with Identity Platform, you can authenticate users on your platform with any identity provider that supports [OIDC](https://firebase.google.com/docs/auth/web/openid-connect) or [SAML](https://firebase.google.com/docs/auth/web/saml).

You can incorporate a quick sign-up and sign-in feature for your users using FirebaseUI Auth. By doing so, users spend less time creating profiles or signing up, which boosts conversion rates. Additionally, it tackles scenarios that can be tricky to manage appropriately in terms of security, such as [account recovery and account linkage](https://firebase.google.com/docs/auth/web/firebaseui). Furthermore, the Firebase SDK Authentication is also an authentication function you can include in your application. It gives you various authentication functions, including the following:

- **Email and password authentication:** Users that sign in with their email addresses and passwords can be created and managed using the Firebase Authentication SDK.
- **Third-party-powered authentication:** Google, Facebook, Twitter, and GitHub user accounts can be used to log in using the Firebase Authentication SDK's APIs.
- **Phone number authentication:** Users can be authenticated after receiving a one-time password (OTP) SMS message on their phones.
- Other authentication channels include custom authentication using a limited list of [federated identity providers](https://firebase.google.com/docs/auth/where-to-start#firebasesdk), any third-party identity providers on a [pricier plan](https://firebase.google.com/docs/auth#identity-platform), and anonymous authentication for temporary accounts.

Firebase authentication can also be achieved using an identity platform. You have the option to add an optional authentication feature (like multifactor authentication, blocking function, multi-tenancy, SAML, and OIDC) to your application using the [Identity Platform](https://firebase.google.com/docs/auth).

### ZITADEL Authentication

ZITADEL provides you with the option to use third-party-powered authentication to provide trust between your application and the users. For instance, if you set Google as an identity provider, ZITADEL can redirect the user to log in with their Google account and give ZITADEL access to take their credentials as a form of identification on the platform.

You can use the following authentication features with ZITADEL:

- You can register an OIDC client of your choice and add a ZITADEL callback redirect (make sure the provider is OIDC 1.0 compliant with a proper [discovery endpoint](/docs/guides/integrate/login-users). This will give your users the option to log into your ZITADEL-powered application using the OIDC authentication feature.
- You can use a SAML sign-in option that gives your users the ability to authenticate once and gain access to multiple secured parts of your application without resubmitting their credentials.
- You can choose to let your users log in with a traditional username and password.
- You can authenticate via external identities, such as Google, Microsoft, or Apple.
- You can force a user to register and use multifactor authentication through a universal second factor, such as OTP, alongside their pin.
- You can decide to use passwordless login authentication. Your user can either use device-dependent (e.g., fingerprint, face recognition, and [Windows Hello](https://support.microsoft.com/en-us/windows/learn-about-windows-hello-and-set-it-up-dae28983-8242-bb2a-d3d1-87c9d265a5f0)) or device-independent (e.g., [YubiKey](https://www.yubico.com) and [SoloKeys](https://solokeys.com)) access.
- You can use multi-tenancy authentication to allow a user to authenticate themselves once with authorizations in multiple organizations. It simplifies the whole authentication process for users regardless of their tenancy, while allowing you to have multiple organizations with different users. ZITADEL ensures each tenant has complete privacy regarding their data, a highly-customizable login flow, and on-demand scaling.

As you can see, both ZITADEL and Firebase provide numerous ways to authenticate your users. However, ZITADEL stands out in that it gives you open access to any third-party [identity broker](/docs/concepts/features/identity-brokering) without any complex pricing plans. You can use OIDC or SAML to connect with any third-party identity provider and provide your users with the authentication they want.

If you're in need of a quick authentication feature for your application, Firebase is a good option. However, if you need more advanced authorization, user self-service, and multi-tenancy features for your application, ZITADEL is the superior choice because it's built to handle your authentication needs, no matter the complexity of your application.

### Firebase Integrations

Programming in C++, Java, JavaScript, JavaScript/Node.js, Objective-C, and Swift is supported by the [Firebase SDK](https://firebase.google.com/docs/firestore/client/libraries). Database bindings and libraries with limited functionality in [Angular](https://github.com/angular/angularfire), [Backbone.js](https://github.com/googlearchive/backbonefire) and [Ember.js](https://github.com/FirebaseExtended/emberfire) are also supported.

For the uninitiated, bindings are basic mappings of APIs to in-code functions that carry out standard operations like CRUD. However, they're not as detailed as SDKs, and sometimes a binding scan can go beyond the basic CRUD operations and offer cosmetic improvements or alternatives to existing methods and features, in which case they are often referred to as auxiliary or supplementary bindings.

Google has added a few supplementary bindings and libraries like [FirebaseUI](https://github.com/firebase/firebaseui-web), [GeoFire](https://github.com/googlearchive/geofire), [Firebase Queue](https://github.com/FirebaseExtended/firebase-queue), and [FirebaseJobDispatcher](https://developer.android.com/topic/libraries/architecture/workmanager/). These auxiliary bindings add more functionality to your application, including [drop-in authentication with FirebaseUI](https://firebaseopensource.com/projects/firebase/firebaseui-web) and [real-time location queries with GeoFire](https://firebaseopensource.com/projects/firebase/geofire-android/).

Additionally, Firebase allows for integration with [Elasticsearch](https://www.elastic.co/what-is/elasticsearch) and the import of big JSON data collections. You can find out more about implementation in the official [Firebase docs](https://firebase.google.com/docs/guides).

### ZITADEL Integrations

ZITADEL is younger than Firebase and provides gRPC, gRPC-web, and Rest APIs, which are supported by most common programming languages, including Angular, React, [Flutter](https://flutter.dev/), [Next.js](https://nextjs.org/), Java, Python, Go, .NET, and [Dart](https://dart.dev/). In addition, you can opt for either the cloud SaaS version or [self-host](/docs/guides/deploy/overview) it using the [open-sourced repo](http://github.com/zitadel/zitadel). To see a few different ways integrations can be used, check out [ZITADEL's official docs](/docs/sdk-examples/introduction).

ZITADEL provides ample APIs and SDKs to help you integrate with most programming languages. You can also easily integrate your apps with open standards such as OpenID Connect, OAuth 2.0, SAML, etc., when using ZITADEL.

Both ZITADEL and Firebase integrate with a wide range of programming languages, which gives you the ability to work with whatever language or framework you're most comfortable with.

### Firebase Use Cases

As previously stated, Firebase is a full-featured BaaS platform, offering all the capabilities required to swiftly create complex, collaborative apps that can support millions of users. The architecture of Firebase is designed to work in any of the following situations:

* **Firebase-powered application:** Firebase sits in between your application and your client. All you need to worry about is the client side of the application, while Firebase handles the complex backend structure. Resource sharing and storage are both handled by Firebase.
* **Firebase-powered application with server-side:** Firebase is positioned between the server and clients in this architecture. In other words, your server interacts with Firebase to send and receive resources from clients. You can decide who has full access to the data and how it should be handled using your security settings and Firebase rules. Then your server code keeps an eye out for any data changes made by clients and reacts as needed. Even though you're still running a server, Firebase is handling all the heavy lifting of scale and real-time updates.
* **Firebase-powered functionality in an existing application:** In this architecture, Firebase can be integrated alongside your existing server. Your clients will establish connections to both your server and Firebase, using Firebase to power your real-time features while keeping the rest of your application running smoothly.

Using any of these capabilities, you can add a real-time notification system for your users, integrate a chat feature into your website, produce a real-time comment feed, and more. An easy way to start using Firebase is to test out some of its minor functionalities.

### ZITADEL Use Cases

ZITADEL offers you much more control over how your IAM system is deployed. You can use ZITADEL in any of the following use-cases:

* **Out-of-the-box integration with your apps:** ZITADEL can offer you a central login experience that can handle all your users in one place. When a user requests to authenticate, you send them over to the central login widget of ZITADEL to retrieve their details once they're successfully authenticated.
* **Multi-tenancy support:** When building business-to-business (B2B) apps, you need to enable your customers to have control over their authentication flow. They should be able to choose and customize things like branding, federation, and policies. This is often not possible with providers like Firebase Auth because it was originally intended for business-to-consumer (B2C) apps. ZITADEL enables you to support your B2B customers and provide their users with the best experience possible.
* **Self-service experience:** As mentioned above, B2B customers need control over their branding and access rules, and it's not scalable for you to approve or moderate changes. ZITADEL offers you a complete self-service platform that your customers can use to easily self-manage their projects in your apps.
* **Using existing identities:** Many B2B customers want to rely on established third-party identity providers or their own company logins instead of going down the generic email-password route. Federated login flows only partly solve this problem because they don't allow you to choose *any* third-party provider, and reusing a company login is an even more complex task. ZITADEL works best in this case since you can allow your customers to use common protocols like OIDC and SAML to register any recognized identity provider with the IAM solution and manage it on a centralized platform.

Internally, ZITADEL is composed of [two principal architectural styles](https://zitadel.com/docs/concepts/architecture/software): command and query responsibility segregation (CQRS), and event sourcing (ES). Combining ES and CQRS improves ZITADEL's consistency and offers numerous advantages.

Due to the nature of Event Sourcing, ZITADEL has the singular ability to create a robust audit record of everything that occurs on its resources—all while maintaining storage costs and audit trail length.

In summary, if your application needs backend functionality, authentication needs, or real-time data alongside your existing server, Firebase gives you the ability to integrate it with your application at any stage (development or production). Meanwhile, ZITADEL's easy integration into your application helps you handle the authentication, authorization, and self-service parts of your application. If you're looking for a platform that will manage your user identity and provide you complete control over it, ZITADEL is the superior choice.

## Conclusion

In this article, you learned about the key differences between Firebase Authentication and [ZITADEL](https://zitadel.com/). You saw how they compared to each other and how you can integrate them into your project, their architectural choices, as well as the different features they offer.

Firebase in general provides you with backend functions that you can use while building your application's frontend or when scaling your applications. In contrast, ZITADEL gives you flexibility with your programming language and unlimited authentication options.

[ZITADEL](https://zitadel.com/) is an open source identity management platform that provides you with a wide range of features like OpenID Connect, SAML 2.0, OAuth 2, FIDO2, OTP, and an unlimited audit trail. With ZITADEL, you can solve all your authentication and authorization needs. Check out the ZITADEL repo and give us a [GitHub star](https://github.com/zitadel/zitadel). We appreciate the feedback.


*This article was contributed by [Aransiola Ayodele](https://portal.draft.dev/writers/rec2hTGbxNzwgQITY).*


The purpose of this article is to guide readers on what are the differences between ZITADEL and Firebase

Comparing ZITADEL to Firebase


## Introduction

With the release of [ZITADEL v2.22.0](https://github.com/zitadel/zitadel/releases/tag/v2.22.0), we announced the availability of Flat Role Claims. This feature enables you to easily integrate user roles into your tokens through customizable actions, providing greater flexibility and control over the claims in your access tokens, ID tokens, and user info.

Flat role claims are a way of representing user roles in a simplified and easily readable format. Instead of using nested structures or complex JSON objects, flat role claims utilize a list of strings where each string represents a user's role, often combined with additional identifiers, such as organization or project IDs. For example, a flat role claim could look like this: 

`["{orgId}:{role}", "{orgId}:{role}", ...]`

Before supporting flat role claims, ZITADEL represented role claims using a JSON object structure. While this format provided all the necessary information, it could be difficult to parse and integrate with certain third-party tools and applications that expected roles in a simpler format.

ZITADEL switched to supporting flat role claims to provide more flexibility and ease of integration with various tools and systems. For example, better compatibility with tools such as [OAuth2 Proxy](https://github.com/oauth2-proxy/oauth2-proxy) or using ZITADEL as an OIDC provider with [Hashicorp Vault](https://www.vaultproject.io/). Flat role claims are easier to read, parse, and work with, reducing the complexity of managing user roles without having to recreate the role information as user metadata. 

## A Practical Use Case

Let’s consider that an organization has a project management application that integrates with ZITADEL for user authentication. The project management application requires user roles and permissions to be included in the ID token as custom claims in a specific format.

The organization uses ZITADEL's built-in roles and permissions for its users. However, the project management application expects user roles in a flat format (e.g., `orgId:role`), while ZITADEL provides roles as a JSON object.

To address this requirement,  ZITADEL allows the organization to reformat the user roles into the required flat format and include them as custom claims in the ID token. This way, the project management application can receive the ID token containing the custom claim and use it to grant the user access based on their roles and permissions.

By supporting flat role claims, ZITADEL enables the organization to customize the ID token to meet the specific requirements of their third-party application.

## How to Configure Flat Role Claims in ZITADEL

### Terminology: Actions, Triggers, and Flows
[ZITADEL Actions](https://zitadel.com/docs/apis/actions/introduction) is a key feature to extend the functionality of ZITADEL and continuously improve upon ZITADEL features and expand use cases. Actions allow you to create extended functionality by writing scripts using JavaScript. For example, the script of an action called doSomething should have a function called doSomething and would look like this:

```
function doSomething(ctx, api){
   // read from ctx and manipulate with api
}
```

[Trigger Types](https://zitadel.com/docs/apis/actions/introduction#trigger-types) define the point during the execution of a request. Each trigger defines which readable information (`ctx`) and mutual properties (`api`) are passed into the called function as well as which libraries are available for the function. 

[Flows](https://zitadel.com/docs/apis/actions/introduction#flows) are the links between an action and a trigger type. Currently, ZITADEL provides the following flows:

- Internal Authentication
- External Authentication
- Complement Token

The **Complement Token Flow** is the process flow of token creation and token introspection. The flow contains the following triggers: 

**Pre Userinfo creation**: This is the trigger that is called before `userinfo` is set in the token or response, and takes in the parameters (`ctx` and `api`) and their respective fields, such as `claims`, `getUser()`, `user`, `getMetadata()`, `grants`, and `setClaim()`.

**Pre access token creation**: This is the trigger that is called before claims are set in the access token and the token type is set to JWT. It takes in the parameters (`ctx` and `api`) and their fields, including `claims`, `getUser()`, `user, getMetadata()`, `grants`, `setClaim()`, and `appendLogIntoClaims()`.

You can define custom claims within the Complement Token Flow. You can create an action and use roles from ZITADEL to add a claim to your tokens/userinfo in the format of your choice. 

### A Sample Action
This code snippet is a JavaScript function named`flatRoles` that sets additional role claims in a token, combining the project ID and role name as a key-value pair. The function is part of the Complement token flow and is triggered during Pre Userinfo creation and Pre access token creation.

``` JavaScript

/**
 * Sets the roles as an additional claim in the token with roles as the value and project as the key.
 *
 * The role claims of the token look like the following:
 *
 * // Added by the code below
 * "my:zitadel:grants": ["{projectId}:{roleName}", "{projectId}:{roleName}", ...],
 * // added automatically
 * "urn:zitadel:iam:org:project:roles": {
 *   "asdf": {
 *     "201982826478953724": "zitadel.localhost"
 *   }
 * }
 *
 * Flow: Complement token, Triggers: Pre Userinfo creation, Pre access token creation
 *
 * @param ctx
 * @param api
 */
function flatRoles(ctx, api) {
    if (ctx.v1.user.grants === undefined || ctx.v1.user.grants.count == 0) {
        return;
    }
    let grants = [];
    ctx.v1.user.grants.grants.forEach(claim => {
        claim.roles.forEach(role => {
            grants.push(claim.projectId + ':' + role)
        })
    })
    api.v1.claims.setClaim('my:zitadel:grants', grants)
}

```


1. The function accepts two parameters: `ctx` and `api`.
  - `ctx`: Contains context information about the user, including user grants.
  - `api`: Provides methods to interact with ZITADEL's API.
2. The function checks if `ctx.v1.user.grants` is undefined or has no elements; if true, it returns immediately, as there's nothing to process.
3. If there are user grants, the function initializes an empty array called `grants`, which will be used to store the flattened roles.
4. Next, it iterates through the user's grants and roles, concatenating the `projectId` and `role` with a colon (":") separator, and then pushes the result into the `grants` array.
5. Finally, the function sets a new claim called `my:zitadel:grants` with the content of the grants array using the `api.v1.claims.setClaim()` method.
6. When the function is executed, it adds the flat role claims to the token in the format `{projectId}:{roleName}`.

### Enable the Action in ZITADEL
To use this flat role claim feature in ZITADEL, follow these steps:

1. Log in to the ZITADEL management console and navigate to the project where you want to use the flat role claim feature. Click on **Actions**. 

<figure>
  <img
    src=" /blog/2023-03-30-custom-claims-01.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

2. Click on the **New** button to create a new action.

<figure>
  <img
    src=" /blog/2023-03-30-custom-claims-02.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

3. In the **Create an Action** section, give the action the same name as the function name, e.g., flatRoles. In the script field, paste the provided flatRoles code. Click on **Add**.

<figure>
  <img
    src=" /blog/2023-03-30-custom-claims-03.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

4. The **flatRoles** action will now be listed. 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-04.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

5. Next, we must select a **Flow Type**. Select **Complement Token** from the dropdown. 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-05.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

6. Next, you must choose a trigger. Click **Add trigger**.  

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-06.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>


7. Select **Pre Userinfo creation** as the **Trigger Type** and select **flatRoles** as the associated action. 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-07.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

8. You will see the **Pre Userinfo creation** trigger listed. 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-08.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>


9. Follow the same steps to add the  **Pre access token creation** trigger and add **flatRoles** as the associated action. Afterwards, you will see both triggers listed as shown below: 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-09.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

10. Don't forget to select the **Assert Roles on Authentication** checkbox on the Project dashboard and click **Save**. 

<figure>
  <img
    src="/blog/2023-03-30-custom-claims-10.png"
    width="100%"
    alt="Custom Claims."
  />
</figure>

Now, when a user logs in and receives an ID token, the action will be executed, transforming the user roles into the required flat format and adding them as a custom claim with the key `my:zitadel:grants`. This custom claim can then be used by third-party applications to manage user access based on their roles and permissions in the desired format.

## Closing Remarks

In summary, supporting custom role claims in ZITADEL enhances the user experience by providing more customization options, better compatibility with third-party tools, and improved adaptability to different use cases

Thanks for reading!

ZITADEL is FREE! So, go on and [try it out](https://zitadel.com/signin). 


This article demonstrates how to add custom claims to your tokens through customizable actions.

Configuring Custom Claims in ZITADEL

This follow-up article demonstrates how to use ZITADEL to secure APIs and how back-end applications can access these protected APIs.

API Access and Token Introspection with OpenId Connect in ZITADEL


## New Features

The [ZITADEL OIDC library](https://github.com/zitadel/oidc) is where we implement the OpenID Connect standard in a Go library. It is used by ZITADEL and our clients. Whenever we need to support additional parts of the specification or OAuth2-related RFCs in ZITADEL, the first step is to implement it in our OIDC library. In short, the following features lay important groundwork for later support in ZITADEL.

### Dynamic Issuer

The framework can now set the issuer of tokens based on the hostname in the request. This is an improvement for multi-domain deployments. The feature was already in use for almost a year in ZITADEL and now is finally merged to be available to a wider audience.

### Token Exchange (RFC 8693)

We have received a significant contribution from the community that completes the implementation of the Token Exchange flow. Big shoutout to [lefelys](https://github.com/lefelys) for his pull request!

### Device Authorization (RFC 8628)

The OIDC framework now offers device authorization flow as defined by RFC 8628. This feature allows authorization of devices that cannot open a browser for users to authenticate themselves. Instead, a code is generated and displayed along with a URL where the user should point their browser to authenticate and authorize the device.

## Test Coverage

We had a big bump in coverage after a community contribution from [muir](https://github.com/muir) (Thanks!!) last November from 12% to almost 40%. Ever since then,  we have been steadily growing coverage. And today we have crossed the 50% line!

## Refactoring

We have started refactoring some core parts of the library. For v2, we have started to simplify the usage of the collection of token claims, user info, and introspection response. These used to be interfaces, with their implementations as private structs and tons of getter/setter methods. In the case of custom claims a `map[string]interface{}` had to be used, with awkward type assertions.

Now we export those structs, and by the use of generics/type parameters, it is now possible to replace the OIDC types with custom types as decoding/unmarshal targets, essentially allowing type-safe access to additional fields. Don’t worry, the standard types still carry a map if you need the flexibility.

## The Future

We aim to continue to refactor parts of the library. We are looking to get rid of redundant code. Also, we are working hard to replace stale dependencies such as gorilla/mux. And we have some priorities planned, such as improving error handling and logging. In essence, the [issue list](https://github.com/zitadel/oidc/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) gives a good overview of what we are planning to do.

Given the fact that we have some major refactoring in the pipeline, it might not be long until we tag a v3. However, we didn’t want to postpone the release of v2, as we had a split development target for almost a year now. Instead, we’ve decided to be more proactive when it comes to increasing to a new major version while refactoring.

## Conclusion

The release notes for this and the upcoming releases can always be found on the [Github releases page](https://github.com/zitadel/oidc/releases). We are forever grateful for PRs sent in by our [Contributors](https://github.com/zitadel/oidc/graphs/contributors).


We have released version 2.0 of our OpenID Connect library, which includes many changes.

OIDC Version 2.0 Release


A single-page application (SPA) is an approach to website implementation that aims to provide a better and faster user experience without necessarily hitting the server every time a user interacts with the site. The SPA pattern is a popular approach to designing websites and web apps, with many prominent sites—including [Airbnb](https://www.airbnb.com), Facebook, Gmail, [Jira](https://www.atlassian.com/software/jira), [LinkedIn](https://www.linkedin.com/), and [Netflix](https://www.netflix.com/)—utilizing it.

Security issues are not unique to SPA websites, but this type of solution poses several security drawbacks that aren't present in typical server side websites—that is, a website that loads new pages when you click a link. This is due to the architectural pattern of SPAs, where they sometimes use access tokens to incorporate secure API endpoints in an insecure environment known as the browser. This exposes the site to some [security issues](https://appcheck-ng.com/single-page-applications), such as ​​cross-site scripting (XSS) attacks, cross-site request forgery (CSRF), and session tracking and authentication.

In this article, you'll learn about single-page applications, some security issues associated with the approach, and how to improve the security of any SPA site using [Cloudflare Workers](https://workers.cloudflare.com/) and [ZITADEL](https://zitadel.com/).

## Security Concerns

Let's look at some of the specific security concerns that hackers might exploit in a site that uses the SPA approach.

### Cross-Site Scripting Attacks

![Cross-site scripting (XSS) attacks](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-01.png)

Cross-site scripting, or XSS for short, is a web security vulnerability where hackers inject malicious client-side scripts into the application (in this case the SPA). Using this technique, hackers can steal an access token that was kept in the browser storage. The extracted access token can then be used by the attacker to access resources through the API endpoints. As long as the access token is valid the malicious actor will be able to access any resources that the original user of the token had permissions for.

Additionally, when content security policy (CSP) settings are not properly set, hackers can use the stolen token on an external system.

### Cross-Site Request Forgery

![Cross-site request forgery (CSRF)](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-02.png)

Cross-site request forgery (CSRF) is also known as a one-click attack or session riding and is occasionally abbreviated XSRF. Regardless of what it's called, it's an online security vulnerability where a user is deceived into doing an unwanted activity on a site that they are logged in.

For instance, a hacker may send a user an email that asks them to change their password and provides them with a malicious link through which to do so. The link contains a hidden trigger, such as a hidden form request. When the user follows the link and changes their password, the hidden form request is made along with the submitted password.

As a result, the hacker might be able to access the application API endpoints using the stolen password or other sensitive information. If the compromised user has a privileged position inside the application, the hacker may ultimately gain control of all the data and functionality of the application.

### Session Tracking and Authentication

A single-page application is made up of two primary parts, the frontend systems and API endpoint (backend) systems:

- The frontend systems can consist of websites built with HTML, CSS, and JavaScript, as well as assets that load on the browser, such as photos and JavaScript libraries.
- The backend systems are made up of one or more API endpoints that handle business logic and data processing.

Similar to the conventional multipage approach, an SPA must be secure; however, to achieve an optimal level of security, the web server employs session cookies—a server-specific cookie to proxy the API endpoints. Although session cookies are also vulnerable to cyberattacks, when configured correctly, they can be more secure and offer fewer security risks. Let's take a look at a few additional security measures that can further secure your SPA.

## SPA Security Tips

Following are some tips for improving your SPA security:

### Don't Store Tokens in the Browser

As discussed in the previous sections of this article, SPAs operate primarily in an unverified environment. Storing sensitive information, such as the token from an SSO provider like ZITADEL, can have serious security implications. It is highly recommended that you only use cookie-based sessions.

Although cookie-based sessions can't offer your SPA hundred-percent security from attackers, they're a much better practice than browser storage. Additionally, some attributes may be added to your cookie-based sessions to ensure that your SPA has sufficient security.

One attribute is secure HTTP (HTTPS). If this attribute is enabled, it blocks scripts from non-HTTPS sources (*ie* those that are not secure) from accessing the backend server, even if they have access to the cookie.

The SameSite attribute gives the browser instructions on how to manage cookies. This attribute has three different options, with each option having distinct behaviors:

- **Lax:** This is the default SameSite option if the SameSite attribute isn't set. This option only grants access to the backend server if the domain in the URL bar is the same as the cookie domain (first-party only).
- **Strict:** This option only grants access to the backend server if the domain in the URL bar is the same as the cookie domain and the request isn't coming from an external (third-party) site.
- **None:** This option grants access to the backend server from any domain, regardless of the source (third-party or first-party site).

Properly configuring the CORS headers in your SPA may also help shield against unwanted attacks, especially CSRF attacks.

### Rely on Cookies from a Proxy Instead of Storing SSO Tokens

Instead of storing sensitive information in the browser storage, a better and securer option is to utilize cookies from a proxy, such as Cloudflare Workers.

A proxy, in this context, is a server application that acts as an intermediary between the backend servers and the frontend server:

![Backend for frontend (BFF) approach](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-03.png)

This technique of utilizing cookies from a proxy rather than directly from the token is referred to as the backend for frontend (BFF) approach. In this method, the frontend receives a secure cookie from the token handler (proxy module), and the token is completely concealed from the browser, making it impossible for an attacker to access it. Additionally, the security of the SPA is strengthened, and any security issue that may occur will be from the backend server (API endpoints).

An example of a proxy module is Cloudflare Workers, and you can leverage Curity's [Cloudflare Workers OAuth Proxy Module](https://curity.io/resources/learn/cloudflare-oauth-proxy-module/) to integrate Cloudflare Workers into your SPA.

## How to Secure an SPA Using React and ZITADEL.

In this section, you'll walk through how to set up a secured SPA using [React](https://reactjs.org/) and ZITADEL.

### Prerequisites

You'll need a few things to follow along with this tutorial:

- [ZITADEL](https://zitadel.com/) account.
- [Cloudflare Workers](https://workers.cloudflare.com/) account and Cloudflare subdomain.
- [npm](https://www.npmjs.com/) or [Yarn](https://yarnpkg.com/) installed in your environment.

### Create a React SPA

Run `npx create-react-app <NAME-OF-REACT-APP>` to initialize a new React application. However, you can use an existing React application if you have one.

You also need to install an [OAuth](https://oauth.net/)/[OpenID Connect](https://openid.net/connect/) client to connect your react SPA with ZITADEL. Run the command `npm install oidc-react` to install the client library.

### Set Up Your Cloudflare Workers

The first thing to do in this step is to install Wrangler, which is a CLI for building Cloudflare Workers. Wrangler enables you to initialize, develop, and publish your Workers projects.

Use either of the following commands to install Wrangler:

* If you're using npm, use the command `npm install -g wrangler`.
* If you're using Yarn, use the command `yarn global add wrangler`.

> **Please note:** Wrangler requires Node.js v16.13.0 or higher.

The next step is to authenticate Wrangler.

Run `wrangler login`, and your browser will launch. You'll be routed to a screen requesting that you log into the Cloudflare dashboard. After you log in, Wrangler will ask whether it has permission to modify your Cloudflare account. Scroll down and click **Allow** to proceed.

Change the directory (`cd`) to your react app directory, and use the following command to start a new Wrangler project:

```
`wrangler init <YOUR_WORKER>`; 
```

The value of `<YOUR_WORKER>` can be any name you decide.

In your terminal, you'll be asked the following questions:

* "Would you like to use git to manage this Worker? (y/n)": Indicate `y`.
* "No package.json found. Would you like to create one? (y/n)": Indicate `y`.
* "Would you like to use TypeScript? (y/n)": Indicate `n` to continue with JavaScript.
* "Would you like to create a Worker at demo_one/src/index.js?": Select **None**.

![Wrangler initialization process](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-04.png)

### Create a ZITADEL Application and Set Up SSO

Log into your [ZITADEL Cloud account](https://zitadel.com/signin) and click **New** at the top right to create a new instance. You can select either a free instance or a premium (pay-as-you-go) instance for this tutorial.

Follow the prompts to create the instance and log into the instance once it has been created. It will look like the following screenshot:

![ZITADEL instance](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-05.png)

Click the domain link to access the console:

![ZITADEL console](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-06.png)

Click the **Create Project** button and insert your project name.

Once the project has been created, click the **+** button to create an application.

Fill in the application details as required by the form wizard:

1. Insert your application name and select the **User Agent** option:

![Create a ZITADEL application: **Name and Type**](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-07.png)

2. Select the **PKCE** option:

![Create a ZITADEL application: **Authentication Method**—Select PKCE](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-08.png)

3. Insert your SPA dashboard URL (such as `http://localhost:3000/dashboard`) in the **Redirect URIs** section and set the **Post Logout URIs** to `http://localhost:3000`:

![Create a ZITADEL application: **Redirect URIs**](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-09.png)

> **Please note:** You'll need to enable development mode in your project's **Redirect Settings** for these URLs to work.

4. Review your selections and click the **Create** button at the bottom right:

![Create a ZITADEL application: **Overview**](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-10.png)

### Configure SPA with ZITADEL Authentication

Go back to your SPA and create a new file with the name of your choice. Import the `AuthProvider` component from the installed `oidc` package to the new file:

```
`import { AuthProvider } from "oidc-react";`
```

Create a constant variable containing an object with the required parameters:

```
const oidcConfig = {
    onSignIn: async (response: any) => {
      alert(
        "You logged in :" +
          response.profile.given_name +
          " " +
          response.profile.family_name
      );
      window.location.hash = "";
    },
    authority: "https:/[your-domain]-[random-string].zitadel.cloud", // replace with your instance
    clientId: "YOUR-CLIENT-ID",
    responseType: "code",
    redirectUri: "YOUR-REDIRECT-URL",
    scope: "openid profile email",
  };
```

`YOUR-CLIENT-ID` should be replaced with the generated client ID of your ZITADEL application. To locate this, navigate to the **Project** tab of your ZITADEL console and select **Configuration**:

![Client ID](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-11.png)

`YOUR-REDIRECT-URL` should be replaced with the redirect URL you specified when creating the application. If you need to be reminded, you can select **Redirect Settings** on the project tab to see your redirect URL.

Wrap the authenticated components/sections in the `AuthProvider` component and pass the constant variable as a prop using the JSX Spread operator:

```
function Dashboard() {
  return (
    <AuthProvider {...oidcConfig}>
      <div className="App">
        <header className="App-header">
          <p>Welcome Back</p>
        </header>
      </div>
    </AuthProvider>
  );
}

export default Dashboard;
     
```

Install [React Router](https://reactrouter.com/) into your React application by running `npm i react-router-dom@latest`, and then set up the router in the `App.js` file by importing the `react-router-dom` components with the command `import { BrowserRouter, Routes, Route } from "react-router-dom";`.

Import the dashboard, home, and other created components into the `App.js` file:

```
import Dashboard from 'path/to/file/Auth'
import Home from "path/to/file/Home";
```

Use the imported components:

```
function App() {
  return (
    <BrowserRouter>
      <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/dashboard" element={<Dashboard />} />
      </Routes>
    </BrowserRouter>
  );
}

export default App;
```

### Publish Your Application Using Workers

Change the directory (`cd`) into your React application and create a file called `wrangler.toml` with the following contents:

```
name = "<NAME-OF-REACT-APP>"
account_id = '<YOUR_CLOUDFLARE_ACCOUNT_ID>'
usage_model = 'bundled'
compatibility_date = "2022-09-19"
workers_dev = true
main = "<FOLDER-NAME-OF-THE-WORKER-SITE>/index.js"
[site]
bucket = 'build'
```

To get your `<YOUR_CLOUDFLARE_ACCOUNT_ID>`, log into your Cloudflare Workers account, click on **Workers** on the sidebar, and copy your **Account ID** from the right side of the page:

![Cloudflare Workers **Account ID**](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-12.png)

Change the directory into `<FOLDER-NAME-OF-THE-WORKER-SITE>` and create a file named `index.js`; then paste in the following code snippet:

```
import { getAssetFromKV, mapRequestToAsset} from "@cloudflare/kv-asset-handler";

/**
 * The DEBUG flag will do two things that help during development:
 * 1. we will skip caching on the edge, which makes it easier to
 *    debug.
 * 2. we will return an error message on exception in your Response rather
 *    than the default 404.html page.
 */

const DEBUG = false;

addEventListener("fetch", (event) => {

  try {
    event.respondWith(handleEvent(event));
  } catch (e) {
    if (DEBUG) {
      return event.respondWith(
        new Response(e.message || e.toString(), {
          status: 500,
        })
      );
    }
    event.respondWith(new Response("Internal Error", { status: 500 }));
  }
});

async function handleEvent(event) {
  const url = new URL(event.request.url);
  let options = {};
  /**
   * You can add custom logic to how we fetch your assets
   * by configuring the function `mapRequestToAsset`
   */
  options.mapRequestToAsset = (req) => {
    // First let's apply the default handler, which we imported from
    // '@cloudflare/kv-asset-handler' at the top of the file. We do
    // this because the default handler already has logic to detect
    // paths that should map to HTML files, for which it appends
    // `/index.html` to the path.
    req = mapRequestToAsset(req);
    // Now we can detect if the default handler decided to map to
    // index.html in some specific directory.
    if (req.url.endsWith("/index.html")) {
      // Indeed. Let's change it to instead map to the root `/index.html`.
      // This avoids the need to do a redundant lookup that we know will
      // fail.
      return new Request(`${new URL(req.url).origin}/index.html`, req);
    } else {
      // The default handler decided this is not an HTML page. It's probably
      // an image, CSS, or JS file. Leave it as-is.
      return req;
    }
  };
  try {
    if (DEBUG) {
      // customize caching
      options.cacheControl = {
        bypassCache: true,
      };
    }
    return await getAssetFromKV(event, options);
  } catch (e) {
    // Fall back to serving `/index.html` on errors.
    return getAssetFromKV(event, {
      mapRequestToAsset: (req) =>
        new Request(`${new URL(req.url).origin}/index.html`, req),
    });
  }
}

```

The previous code snippet is required for an SPA made with React, [Vue.js](https://vuejs.org/), or [Angular](https://angular.io/). It monitors the Cloudflare Workers for any incoming requests and serves the corresponding asset from Workers KV.

Change the directory back into the root of the React app and run the command `npm install @cloudflare/kv-asset-handler`.

Build your application by running the `npm run build` command, and then publish your application to Cloudflare Workers by running `wrangler publish`:

![Wrangler publish](/blog/2023-01-26-increase-spa-security-with-cloudflare-workers-13.png)

To access the application, open your browser and go to `https://<workers-name>.<cloudflare-subdomain>/`, where `<workers-name>` is the `<NAME-OF-REACT-APP>` and `<cloudflare-workers-subdomain>` is your Cloudflare Workers subdomain.

You can see all the code used in this tutorial in [this GitHub repo](https://github.com/Olaogunjames/cloudflare-workers-react).

## Conclusion

This article provided a basic overview of single-page applications as well as the security issues associated with SPAs. You've also seen how you can set up a secured SPA using React and [ZITADEL](https://zitadel.com/). With ZITADEL, you can seamlessly scaffold your application access-control level (ACL) and assign roles to your users using ZITADEL's role-based access control (RBAC).

[ZITADEL](https://zitadel.com/) is an open source identity management platform that provides you with a wide range of features like OpenID Connect, SAML 2.0, OAuth 2, FIDO2, OTP, and an unlimited audit trail. With ZITADEL, you can solve all your authentication and authorization needs. Check out our repo and give us a [GitHub star](https://github.com/zitadel/zitadel). We appreciate the feedback.

*This article was contributed by [James Olaogun](https://portal.draft.dev/writers/rec8roCYYfi889uRl).*


In this article, you'll learn about single-page applications, some security issues associated with the approach, and how to improve the security of any SPA site using Cloudflare Workers.

Increase Your SPA Security with Cloudflare Workers


In the current IT ecosystem, it's not uncommon to see businesses and organizations relying on all kinds of software systems to address their unique business challenges. While these systems help organizations by providing their expected value, they introduce a security challenge where users have to manage their passwords for each system separately.

Having a lot of passwords causes all sorts of problems, including increased customer support tickets to reset passwords, degraded user experience when logging into each system separately, and management challenges for corporate users if they have to be added or removed from multiple systems in the organization.

This is where [single sign-on (SSO)](https://encyclopedia.kaspersky.com/glossary/single-sign-on-sso/) comes to the rescue. SSO enables you to delegate the users' account creation and management to a central authentication server. Instead of separately managing a username and password for each application in your organization, your applications delegate the authentication to a trusted SSO server.

In this tutorial, you'll learn what benefits SSO brings to the table. You'll learn how to delegate access from a self-hosted [Nextcloud](https://nextcloud.com/about/) service to
[ZITADEL](https://zitadel.com/) as an SSO provider utilizing the [OpenID Connect (OIDC)](https://openid.net/connect/) protocol.

## Key Benefits of SSO

SSO is beneficial because it provides a better user experience. For instance, SSO makes it seamless for the user to access multiple systems smoothly and quickly without being interrupted by password logins. A side effect of this benefit is an increased software adoption rate, as onboarding any new software application will be a matter of integrating it with the SSO server.

In addition, password reset tickets are a [significant support cost](https://bioconnect.com/2021/12/08/are-password-resets-costing-your-company/).
By reducing the number of systems that require separate passwords, you'll decrease the number of password reset tickets (which, in turn, reduces cost).

SSO also provides higher security. Storing user accounts and passwords centrally enables you to harden them in one place—the SSO server. Moreover, you'll be able to easily revoke or grant users access by managing them from a single system rather than multiple scattered systems.

This is why you'll see SSO being widely used both internally on corporations and externally on software-as-a-service (SaaS) systems like [Slack](https://slack.com) (which uses Google as an SSO provider).

## How to Integrate ZITADEL SSO OIDC with Self-Hosted Nextcloud

Now that you know what SSO is and why you would want to use it, it's time to implement it using ZITADEL and the Nextcloud self-hosted service. The final architecture will look like this:

<div className="dark:hidden">
  <img
    src="/blog/2022-12-08-zitadel-as-sso-provider-for-selfhosting-01-light.png"
    alt="Final architecture courtesy of Mohammed Osman"
  ></img>
</div>
<div className="hidden dark:block">
  <img
    src="/blog/2022-12-08-zitadel-as-sso-provider-for-selfhosting-01-dark.png"
    alt="Final architecture courtesy of Mohammed Osman"
  ></img>
</div>

There are two major stages in this tutorial: creating a ZITADEL account and configuring Nextcloud as an OIDC client, and then creating a self-hosted Nextcloud container and integrating that into ZITADEL.

## Create a ZITADEL Account and Configure Nextcloud as an OIDC Client

To begin, you’ll need to set up your self-hosted ZITADEL instance. Fortunately, you can do this easily using Docker.

To begin, use [ZITADEL's Docker Compose guide](/docs/guides/deploy/compose) to set up Docker. During the set up, you should receive another email from ZITADEL. Open the email and click **Finish Initialization**. You'll receive a prompt to create a new password for your ZITADEL instance. Create it and then select **Next**.

> **Please note:** The password you created earlier differs from the password you just created. The password you specified earlier in this tutorial is for the ZITADEL customer portal, and the password you just created here is for the ZITADEL instance.

Select **Skip** to skip creating multifactor authentication and navigate back to the instance overview page.

In the instance UI console, click on the **Projects** tab. Then click **Create New Project** to set up a new OIDC provider:

![Projects menu](/blog/2022-12-08-zitadel-as-sso-provider-for-selfhosting-01.png)

Give your project a name (here, it's "my-first-zitadel-project") and click **Continue**. ZITADEL will now create your project and redirect you to the project settings page.

After you've created your ZITADEL project, you'll need to create an OIDC client app for the Nextcloud app you'll create later. In ZITADEL, an application represents a software that initiates the authorization flow, such as web and mobile apps. To start, click **New** to create a new application and fill in your application details. Here, the name is "cloud-next-app", and the application type is "Web" since Nextcloud runs as a web application.

Once filled out, select **Continue**. You'll be prompted to choose an authentication method: select **CODE**. PKCE is recommended for mobile and static clients. Then select **Continue**.

Now you need to define the redirect URLs for the Nextcloud application (which you'll configure later).

For **Redirect URIs**, put `<http://localhost:6060/apps/sociallogin/custom_oidc/ZITADEL>` and select **+**. For **Post Logout URIs**, put `<http://localhost:6060/>`; then hit **+** > **Continue**. You should see a confirmation screen with your options. Review them and click **Create**:

![Project settings confirmation](/blog/2022-12-08-zitadel-as-sso-provider-for-selfhosting-02.png)

At this point, you'll be presented with a **ClientId** and **ClientSecret**. Please take note of them as you'll need them later:

![ClientId and ClientSecret](/blog/2022-12-08-zitadel-as-sso-provider-for-selfhosting-03.png)

Once noted, select **Close** and then **Redirect Settings** on the left-hand side of your screen.

Since you'll deploy Nextcloud locally on a [Docker](https://www.docker.com/) container without HTTPS, you need to indicate to ZITADEL that this configuration is meant for development mode. Enable the **Development Mode** and click **Save**:

![Enable **Development Mode**](/blog/2022-12-08-zitadel-as-sso-provider-for-selfhosting-04.png)

> ** Please note:** In a real production scenario, you should not use this. Your application should be hosted using HTTPS.

In the final step of this stage, you need to copy the base address of your ZITADEL
instance. This address will be used by the OIDC client (Nextcloud, in
this case) to perform the authentication.

Click **Urls** on the left of the current page and take note of the **authServiceUrl**. In this instance, it's `https://my-first-zitadel-instance-l8ehm3.zitadel.cloud`.

At this point, you've successfully set up ZITADEL as your OIDC server.

### Create a Self-Hosted Nextcloud Container and Integrate to ZITADEL

In order to create a self-hosted Nextcloud container and integrate it with ZITADEL, you need to install Nextcloud as a hosted Docker container and set up your admin user.

To do this, go to [**Get Docker**](https://docs.docker.com/get-docker/) to download and install Docker according to your current operating system. Please refer to the official [Docker documentation](https://www.docker.com/get-started/) for more information. If you already have Docker installed, you can skip this step.

> ** Please note:** In a real production scenario, you'll host the Nextcloud container in a cloud provider, [Kubernetes](https://kubernetes.io/) cluster, or any production-grade deployment.

In the command terminal, type `docker run -d -p 6060:80 nextcloud` to download and run the Nextcloud Docker image. This will map port 6060 in your computer to port 80 Nextcloud Docker container, where the web application runs.

In the command terminal, type `docker container ls` to verify that the Docker container is running. You should see something like this:

![Nextcloud Docker container running](/blog/2022-12-08-zitadel-as-sso-provider-for-selfhosting-05.png)

Open a browser window and navigate to [http://localhost:6060/](http://localhost:6060/) to access Nextcloud. Since this is a first-time setup, you need to create an admin username and password. Fill out these details and scroll down and click **Install**. Nextcloud will take a few seconds to prepare your application.

You should receive a prompt asking if you want to add some recommended apps to Nextcloud. Go ahead and click **Cancel**. Then an introductory splash window to Nextcloud will pop up. Close it by clicking **X** at the top right inside the browser window. Then you should see the Nextcloud dashboard.

Since an OIDC login isn't available by default in Nextcloud, you need to add an app to your self-hosted Nextcloud service in order to enable it. You can think of apps in Nextcloud similar to extensions in Chrome since they add additional functionalities to your application.

Click the icon in the top-right corner of your dashboard and then click **+ Apps**:

![Access apps in Nextcloud](/blog/2022-12-08-zitadel-as-sso-provider-for-selfhosting-06.png)

In the left menu, click **Social & communication** to find apps in that category. From there, search for an app called Social login, click **Download**, and then click **Enable**. In a few seconds, this action installs the Social login app in your Nextcloud self-hosted instance and enables Nextcloud to log in via OIDC.

Click on the top-right icon in the dashboard and then click **Settings**.

On the left of the screen, you should see a **Social login** tab under the **Administration section**. This means that the Social login app was successfully installed to your Nextcloud instance:

![Social login app added](/blog/2022-12-08-zitadel-as-sso-provider-for-selfhosting-07.jpg.jpg)

After you've added the **Social login** application to your Nextcloud instance, it's time to configure it to use ZITADEL as an OIDC provider. Click on **Social login**; then next to **Custom OpenID Connect**, click the **+** sign. This will enable you to add a custom OIDC provider (which, in this case, is ZITADEL).

Fill in the following details and leave any unmentioned field as it is:

- **Internal name:** This is the internal provider's name within Nextcloud, and it's not visible externally (in this example, ZITADEL was used).
- **Title:** This is the provider name exposed externally during the login process (again, ZITADEL was used).
- **Authorize url:** This represents the authorization endpoint URL. It consists of the ZITADEL instance URL you noted earlier with `/oauth/v2/authorize` (`https://my-first-zitadel-instance-l8ehm3.zitadel.cloud/oauth/v2/authorize`).
- **Token url:** This represents the token endpoint URL. It consists of the ZITADEL instance URL you noted with the `/oauth/v2/token` (here, it's `https://my-first-zitadel-instance-l8ehm3.zitadel.cloud/oauth/v2/token`).
- **Client Id:** This is the OIDC client ID you noted previously.
- **Client Secret:** This is the OIDC client secret you also noted earlier.
- **Scope:** Type "openid" to indicate that it is an OIDC protocol.
- **Default group:** Select **admin**. This means that the authenticated user from ZITADEL will have admin permissions. In a real-world scenario, you'd assign the authenticated users less powerful permission.

![Sample OIDC settings](/blog/2022-12-08-zitadel-as-sso-provider-for-selfhosting-08.jpg.jpg)

Then hit **Save**.

After configuring ZITADEL as an OIDC provider, it's time to test it. In the Nextcloud dashboard, click the icon in the top-right corner and then click **Log out** to log out from the current admin user session, and you'll be automatically redirected to the login page.

You should now see a new button that says **Log in with ZITADEL**. Click on it and enter the ZITADEL login name you noted previously; then click **Next**.

Next, enter the ZITADEL instance password (not the customer portal password) and click **Next**. ZITADEL should redirect you to the Nextcloud dashboard.

Congratulations! You've managed to access your self-hosted Nextcloud instance using ZITADEL as an OIDC provider.

## Conclusion

In this tutorial, you learned what an SSO is and how it benefits businesses by improving user experience, reducing costs, and contributing to IT security. You also learned how to set up your self-hosted ZITADEL instance as an OIDC provider. Then, you learned how to set up a Nextcloud self-hosted instance, and you delegated its access to ZITADEL.

[ZITADEL](/) is an open source identity management platform that provides you with a wide range of features like OpenID Connect, SAML 2.0, OAuth 2, FIDO2, OTP, and an unlimited audit trail. With ZITADEL, you can solve all your authentication and authorization needs. Check out our repo and give us a [GitHub star](https://github.com/zitadel/zitadel). We appreciate the feedback.

_This article was contributed by [Mohammed Osman](https://portal.draft.dev/writers/recvOT7Hsq96gfwnR)._


In this tutorial, you'll learn what benefits SSO brings to the table. You'll learn how to delegate access from a self-hosted Nextcloud service to ZITADEL as an SSO provider

Use ZITADEL as SSO provider for self-hosting


Delegated access management lets you offer increased flexibility over the services you provide. 
In this self-service model, your clients can grant rights to their users independently of your interaction, benefiting them and you.

Allowing business customers to handle role management themselves lets them work faster with less of your support. They don't need you to approve individual users on their behalf.

However, granting access is complex, and delegating it needs to be done safely. There are all kinds of pitfalls to worry about if you attempt to do it yourself. Bringing in external expertise is one way to ensure you get it right. In this guide, you'll learn how to simplify delegated access management and self-service.

## Why You Need Delegated Access Management and Self-Service

Delegating access management and providing self-service to your clients can help you in several situations. For example, often, you need highly granular role management, with permissions granted for specific projects and specific types of action. If you're working with staff in another organization, you can't easily manage this yourself.

If that organization has to go through your company every time it wants to change someone’s role or the data they have access to, it will take them time and slow their onboarding procedures, ultimately making working with you less attractive.

Delegating access management also helps mitigate insider threats. Farming out permissions may seem like a security risk, but you're really reducing the number of people that deal with any particular set of permissions. In addition, you're giving control to those that use them.

By reducing the amount of communication and the number of people involved, there's less chance for someone to leak information or act maliciously. And as your client base increases, so does the amount of admin involved in communication. The more you can automate or pass off to your clients, the better.

## How to Simplify Delegated Access Management and Self-Service with ZITADEL

There are several things to think about, when implementing delegated access management and providing self-service capabilities to your users, including roles and permissions, delegated role management, and service consolidation. 

ZITADEL allows you to do all of this and more, handling most of the heavy lifting for you. It makes delegated access management and self service simple. Its APIs integrate with your business processes letting you automate your clients services.

Let's take a more in-depth look at how it can help you:

### Roles and Permissions

There are many types of permission users need. In addition to viewing files or other resources, users may be allowed to create or edit documents or delete files. Furthermore, some users are allowed to grant these permissions to others. Any of these permissions can be limited to specific resource sets. 

To reduce complexity, permissions are often grouped into roles. Roles are a means of managing user access rights and usually come with a default set of permissions. Instead of figuring out exactly which permissions to give an individual, you can grant them a role instead. Your apps then associate permissions with roles, rather than individuals.
Authorizations state which users have which roles and are often referred to as user grants.



Though users are typically human, they can also include machine agents, known as service users. For example, if you use a service to sync databases, the service might access databases on another domain by logging in as a service user.

[ZITADEL](https://zitadel.com/docs/guides/manage/console/projects#grant-a-project) lets you grant selected roles to an organization. The organization can then create authorizations for its users independently, and this is referred to as self-service.

### Delegated Role Management

Delegating role management means you grant another group permission to assign or change roles. You don't need to grant all the permissions you have, but a limited selection allows you to create hierarchical relationships that don't require your involvement to administer.

A simple example of this role delegation would be in blogging software. Everyone has permission to view the blog. Editors get permission to make changes and grant rights to writers. Writers have permission to edit the documents they are assigned by the editors.

In this setup, there's no need to directly set people's individual permissions; you just assign them a role, and everything is taken care of by the software. Without roles, you’d have to select the specific actions available to each staff member.

However, if you're hosting blogging software for someone else, you need to provide them with permission to hand the roles to users. That could look something like the following:

<div className="dark:hidden">
  <img src="/blog/2022-11-24-delegated-access-management-and-self-service-01-light.png" alt="Image showing the relationship between the host company and blogging team, which gets delegated rights to grant users blog access courtesy of James Konik"></img>
</div>
<div className="hidden dark:block">
  <img src="/blog/2022-11-24-delegated-access-management-and-self-service-01-dark.png" alt="Image showing the relationship between the host company and blogging team, which gets delegated rights to grant users blog access courtesy of James Konik"></img>
</div>

Here, your client is granted rights to assign user roles and can create as many users as they like without having to go through you. You can grant whatever rights you want, granting more or less control depending on your use case.

### Managing Access Providers

There are many services providing authorization and authentication services. It can be hard to manage them all. With ZITADEL, you can enable and configure different services for each organization you work with.

With ZITADEL, you can implement [Auth0](https://auth0.com), [OmniAuth](/docs/guides/integrate/services/gitlab-self-hosted), and other kinds of access methods, such as [Keycloak](https://www.keycloak.org), [Azure Active Directory (Azure AD)](https://azure.microsoft.com/en-us/services/active-directory/), and Google through a single self-service platform.

You can enable single sign-on (SSO), too. SSO lets you access multiple services using a single login. ZITADEL lets you use protocols like [OpenID Connect](https://openid.net/connect/) to provide this functionality.

These options make ZITADEL an ideal way to bring your own identity (BYOI) capabilities to your customers. Combining service consolidation with delegate access management like ZITADEL ensures that your users have the flexibility they need when setting up their organization access rules.

Going through ZITADEL takes away the difficulty of managing multiple services, and the consistent interface means your users don't have to figure out all the different login types.

### Branding and Experience Customization

When dealing with [relationships between multiple organizations](/docs/guides/solution-scenarios/b2b), you need to decide how logins are handled. Do you use a default login screen or redirect users to one with a specific organization's branding?

With ZITADEL, you can configure these relationships on a case-by-case basis for different roles and companies. You can also easily create branding and add logos for each client. And of course, you can adjust it all without having to redevelop your site.

ZITADEL's [multi-tenancy support](/usecases) means you can sell your services to different companies and deliver the specific features they need. These can be tailored to their needs and perhaps support different service tiers that you offer.

As well as branding, different organizations can then use different rules, such as their password policies and multi-authentication requirements. It's easy to customize these using a centralized service provider.

### Benefits of Experience

Without experience in security, it's hard to keep up with the ever-changing technical and regulatory requirements. Given how risky mistakes are, it makes sense to bring in outside help.

Implementing delegated access management and self service is complex. When developing such services, it's easy to overlook this complexity. Many services implement authorization and authentication themselves, but as the scope widens to include delegated access management, this becomes an increasingly bad idea.

For nonspecialists, the chances of making a mistake are significant. The investment and maintenance requirements are also high and easy to underestimate.

By using an experienced service provider to handle these areas, you can focus on business logic and deliver a better product.

### Security Dangers

Small mistakes in authentication and authorization services can have dire consequences. Access control, identification, and authentication are all prominent in the [Open Web Application Security Project (OWASP)](https://owasp.org/www-project-top-ten/) top ten security risks. Hackers are getting ever more sophisticated, and a successful attack can be catastrophic for a business on the receiving end.

To try and prevent attacks as well as develop a secure system in the first place, you have to continually update it as new threats emerge.

You also have to deal with the evolution of your wider platform. Every time you add or change a feature, you risk undermining your existing security measures and opening up a vector of attack.

Using an external service to provide authentication and authorization means you have dedicated experts continually updating their platform to deal with the latest vulnerabilities.

Plugging into a mature system via an API lets you deliver an up-to-date, secure service without the need for continual development investment.

And there are even more issues to think about, including setting up security policies, limiting the impact of [DDoS attacks](https://www.geeksforgeeks.org/what-is-ddos-mitigation/), and configuring the various types of encryption needed to authenticate users. None of these are easy to do.

With authentication and authorization handled for you, your developers are free to focus on your core product. You can concentrate on providing features and evolving your own platform without the added overhead of providing auth to external organizations.

### Scaling

Scaling can create issues, as additional users and support for new platforms put your infrastructure under pressure. ZITADEL supports unlimited users and projects, meaning it won't become a bottleneck.

Simplifying your services through delegated access management means you can use specialized tools to handle authorization and authentication, and these dedicated services can be chosen with scaling in mind.

They also prevent your codebase from getting out of hand as the range of clients, roles, and permissions you handle grows. Carefully partitioning it into a separate service keeps yours leaner and easy to work with.

### Additional Features

Login policies are another way to give your clients control. These can be easily defined from ZITADEL's console. Login policies allow you to set authentication methods for your users and can be changed as your clients' needs evolve. They can do that without having to make code changes. You can also do this on an organizational level. For example, a SaaS provider can set different policies.

You can learn more about ZITADEL's feature set [on its website](/features).

## Conclusion

Access management is a complex topic. Managing permissions and granting access to the right people are enough of a challenge, but the changing security landscape and ever-increasing feature sets make it even harder to keep up.

Fortunately, there are alternatives to doing everything yourself. With the right support, you can provide your clients with self-service capability. In return, they get a wide range of features along with cutting-edge security. They also reduce their costs, letting them focus on what they do best.

[ZITADEL](/) is an open source identity management platform that provides you with a wide range of features like OpenID Connect, SAML 2.0, OAuth 2, FIDO2, OTP, and an unlimited audit trail. With ZITADEL, you can solve all your authentication and authorization needs. Check out our repo and give us a [GitHub star](https://github.com/zitadel/zitadel). We appreciate the feedback.

*This article was contributed by [James Konik](https://portal.draft.dev/writers/recYmhitHbB1gDQDA).*

Granting access is complex, and delegating it needs to be done safely. In this guide, you'll learn how to simplify delegated access management and self-service.

All posts/ #engineering