diff --git a/docs/docs/examples/introduction.mdx b/docs/docs/examples/introduction.mdx index f9ff8500b6..1e006232c8 100644 --- a/docs/docs/examples/introduction.mdx +++ b/docs/docs/examples/introduction.mdx @@ -2,30 +2,71 @@ title: Overview --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import {Card, CardWrapper} from '../../src/components/card'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { Card, CardWrapper } from "../../src/components/card"; -Get started with ZITADEL quickly by reading a quickstart or by cloning an example from our [ZITADEL examples](https://github.com/zitadel/zitadel-examples) repo. +Get started with ZITADEL quickly by reading a quickstart or by cloning a [ZITADEL example](https://github.com/search?q=topic%3Aexamples+org%3Azitadel) repo. - - - - + + + + + - - + + - + @@ -33,18 +74,33 @@ Get started with ZITADEL quickly by reading a quickstart or by cloning an exampl ## Clone a sample project - - - - + + + + ## Libraries - -| Language | Description | Link | -| ------------ | ---------------------|-------------| -| Go | Go client library for ZITADEL. | [https://github.com/zitadel/zitadel-go](https://github.com/zitadel/zitadel-go) -| .Net | Authentication / Authorization library written in dotnet for the asp.net web application package. | [https://github.com/zitadel/zitadel-net](https://github.com/zitadel/zitadel-net) -| Dart | Dart library for ZITADEL, contains gRPC and API access elements. | [https://github.com/zitadel/zitadel-dart](https://github.com/zitadel/zitadel-dart) | -| Elixir | API Client for the ZITADEL API. | [https://github.com/jshmrtn/zitadel_api](https://github.com/jshmrtn/zitadel_api) | +| Language | Description | Link | +| -------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| Go | Go client library for ZITADEL. | [https://github.com/zitadel/zitadel-go](https://github.com/zitadel/zitadel-go) | +| .Net | Authentication / Authorization library written in dotnet for the asp.net web application package. | [https://github.com/zitadel/zitadel-net](https://github.com/zitadel/zitadel-net) | +| Dart | Dart library for ZITADEL, contains gRPC and API access elements. | [https://github.com/zitadel/zitadel-dart](https://github.com/zitadel/zitadel-dart) | +| Elixir | API Client for the ZITADEL API. | [https://github.com/jshmrtn/zitadel_api](https://github.com/jshmrtn/zitadel_api) | diff --git a/docs/docs/examples/login/nextjs-b2b.md b/docs/docs/examples/login/nextjs-b2b.md new file mode 100644 index 0000000000..51a2e4fdbc --- /dev/null +++ b/docs/docs/examples/login/nextjs-b2b.md @@ -0,0 +1,177 @@ +--- +title: Next.js B2B Scenario +--- + +This is our Zitadel [Next.js](https://nextjs.org/) B2B template. It shows how to authenticate as a user with multiple organizations. The application shows your users roles on the selected organizations, other projects your organization is allowed to use and other users having a grant to use the application. + +If you need more info on B2B use cases consider reading our guide for the [B2B solution scenario](../../guides/solution-scenarios/b2b.mdx). + +> You can follow along with the template code in our [zitadel-nextjs-b2b](https://github.com/zitadel/zitadel-nextjs-b2b) repo. + +![B2B Application](/img/nextjs-b2b/home.png) + +## What does it do? + +Users with `view` role can view granted projects on their organization which were granted by your organization (owning this portal application). +Users with `admin` role can view granted projects and list users of the selected organization who are granted to use the portal application too. + +## Setup Vendor application and users in ZITADEL + +First we need to create an organization that holds the Vendor's users, projects and applications. + +### Vendor Organization + +Navigate to `https://{YourDomain}.zitadel.cloud/ui/console/orgs` (replace {YourDomain}), and click on the button "New". +Toggle the setting "Use your personal account as organization owner". + +Enter the name `Demo-Vendor`, and click "Create". Then click on that organization. + +### Portal Web Application + +To setup this sample you have to create a project and an application in the vendor organization (`Demo-Vendor`) first. + +Open the Console (`https://{YourDomain}.zitadel.cloud/ui/console/projects`) and create a new project. Let's call it `Portal`. + +Then on the project detail page click on new application and enter a name for this app. +Let's call this one `portal-web`. +Select `Web`, continue, `PKCE`, then enter `http://localhost:3000/api/auth/callback/zitadel` for the redirect, and `http://localhost:3000` for the post redirect. Then press on `create`. + +Copy the "Resource Id" of the project `Portal` as you will need this in your environment configuration file later. + +Click on the application `portal-web`. +On the application detail page click on the section under redirect settings and enable `Development Mode`. This will allow you application to work on `localhost:3000`. +To read the user data and roles from ID Token, go to the section Token Settings and make sure both checkboxes, `User roles inside ID Token` and `User Info inside ID Token` are enabled. +Make sure to save your changes. + +Copy the "Resource Id" of the application `portal-web` as you will need this in your environment configuration file later. + +### Roles + +To setup the needed roles for your project, navigate to your `Portal` project, and add the following roles + +| Key | Display Name | Group | Description | +| :----- | :------------ | :---- | ---------------------------------------------------------------------- | +| admin | Administrator | | The administrator, allowed to read granted projects and to user grants | +| reader | Reader | | A user who is allowed to read his organizations granted projects only | + +Now in the `General` section of the Portal project, make sure to enable `Assert Roles on Authentication`. +This makes sure that roles, which is used by the application to enable UI components, are set in your OIDC ID Token. + +### Service User + +To make the application work you need a service user which loads granted-projects and user-grants for you. +In the B2B-Demo organization, navigate to `Users` in navigation of Console, click on `Service Users` and create a new user. +Let's set its username to `nextjs` and its name to `NextJS`. Then press `create`. + +On the detail page of that user, navigate to "Personal Access Tokens" and add a new entry, set an optional expiration date. + +Copy the generated Token as you will need this in your environment configuration file later. + +Go back to the `Portal` project and add the Service User as Manager (top right). +Make sure to select `Project Owner Viewer` as the management role. + +To show granted projects, go to the `Demo-Vendor` organization and add the Service User as `Org Project Permission Editor` Manager. + +## Configuration + +Now clone this project and navigate to its root folder. +Create a file `.env.local` and copy paste the following: + +```text +NEXTAUTH_URL=http://localhost:3000 +NEXT_PUBLIC_ZITADEL_ISSUER=https://{YourDomain}.zitadel.cloud +ZITADEL_API=https://{YourDomain}.zitadel.cloud +ORG_ID={YourOrgId} +PROJECT_ID={YourProjectId} +ZITADEL_CLIENT_ID={YourClientID} +SERVICE_ACCOUNT_ACCESS_TOKEN={YourServiceAccountSecret} +NEXTAUTH_SECRET=randomsecret +``` + +Replace the values as follows + +`NEXTAUTH_URL`: Base url of this demo app (B2B portal); runs per default on [http://localhost:3000](http://localhost:3000) + +`NEXT_PUBLIC_ZITADEL_ISSUER`: The url to your zitadel instance. When using zitadel.cloud for this demo you can find the domain of your ZITADEL instance in the customer portal. You can also find this information by going to your application `portal-web` and click 'Urls' in the navigation. The variable is prefixed with `NEXT_PUBLIC_` such that it can be accessed from the client. + +`ZITADEL_API`: URL of the Management API. Typically the same as `ZITADEL_ISSUER`. + +`ORG_ID`: We will create an organization during later steps. You can find `{YourOrgId}` by selecting the `Demo-Vendor` organization in Console. `{YourOrgId}` is displayed on top of the organization detail page as "Resource Id". + +`PROJECT_ID`: You can find `{YourProjectId}` by clicking on "Projects" in the navigation and select the Project `Portal`. `{YourProjectId}` is displayed on the top as "Resource Id". + +`ZITADEL_CLIENT_ID`: Having the project `Portal` selected, click on the Application `portal-web`. `{YourClientID}` is displayed as a field in the OIDC configuration, labelled "Client ID" and has the format `12345678@portal`. + +`SERVICE_ACCOUNT_ACCESS_TOKEN`: Setup a service user, add a Personal Access Token and copy the secret here (see below). + +## Install and Run + +To run this sample locally you need to install dependencies first. + +Type and execute: + +```bash +yarn install +``` + +then, to run the development server: + +```bash +npm run dev +# or +yarn dev +``` + +and open [http://localhost:3000](http://localhost:3000) with your browser to see the result. + +## Create a customer organization + +### Customer organization + +Create a new organization in Console. Easiest way is to use the organization dropdown on the top left. +Let's call this new organization `Demo-Customer`. + +### Users + +Now switch back to the organization `Demo-Customer` and [create a new user](https://docs.zitadel.com/docs/manuals/user-register) in this organization. +Let's call the first user `Alice Admin`. Create a second user called `Eric Employee`. + +### Manager Role + +We want to enable Alice to assign roles to users in her organization in a self-service manner. +To make this happen, we need give Alice an [Manager Role](https://docs.zitadel.com/docs/concepts/structure/managers) within the Organization `Demo-Customer`. + +Still in the organization `Demo-Customer`, navigate to Organization. Click on the plus on the top right and give `Alice Admin` the Manager Role `Org Owner`. + +Login with your user on the customer organization to validate the setup. + +## Create a project grant + +### Organization Grant + +Switch to the `Demo-Vendor` organization, select Projects in the navigation, and click on `Portal` and then `Grants`. +[Grant all roles of the Project](https://docs.zitadel.com/docs/guides/basics/projects#exercise---grant-a-project) to the organization `demo-customer.{YourDomain}.zitadel.cloud`. + +### Authorization + +As you have guessed, these two users need to be authorized. +On the `Demo-Customer` organization, navigate to Projects and select "Granted Projects" in the sub-navigation. +Select the project portal `Portal` and navigate to "Authorizations". + +Give `Alice Admin` the roles `reader` and `admin`. +`Eric Employee` will get only the role `reader`. + +### Login + +You should be able to login to the Demo Application with `Alice Admin` and see all granted projects. + +You can log out and log in with `Eric Employee` and you should only have access to the granted projects, but not to the Authorizations tab. + +## What next + +You could create another project (eg, `Data Cube`) and grant that project to the customer organization. The granted project should appear after a reload automatically. This gives you an idea of how you could do Service Discovery with ZITADEL. + +You could also build out the code (PRs welcome :wink:) for this application, for example: + +- Create a mock `datacube-web` application and show how SSO between the portal and the application works with ZITADEL. +- Implement a feature in the Authorization tab to assign roles directly from the customer portal. diff --git a/docs/docs/examples/login/nextjs.md b/docs/docs/examples/login/nextjs.md index 0951dd288d..00a6066bce 100644 --- a/docs/docs/examples/login/nextjs.md +++ b/docs/docs/examples/login/nextjs.md @@ -8,25 +8,15 @@ This is our Zitadel [Next.js](https://nextjs.org/) template. It shows how to aut ## Getting Started -First, we start by creating a new NextJS app with `npx create-next-app`, which sets up everything automatically for you. To create a project, run: +### Install dependencies + +To install the dependencies type: ```bash -npx create-next-app --typescript -# or -yarn create next-app --typescript +yarn install ``` -### Install Authentication library - -To keep the template as easy as possible we use [next-auth](https://next-auth.js.org/) as our main authentication library. To install, run: - -```bash -npm i next-auth -# or -yarn add next-auth -``` - -To run the app, type: +then to run the app: ```bash npm run dev diff --git a/docs/docs/guides/solution-scenarios/b2b.mdx b/docs/docs/guides/solution-scenarios/b2b.mdx index 9760d77c99..2c8f1156c4 100644 --- a/docs/docs/guides/solution-scenarios/b2b.mdx +++ b/docs/docs/guides/solution-scenarios/b2b.mdx @@ -2,7 +2,7 @@ title: B2B --- -import { B2B } from '../../../src/components/b2b'; +import { B2B } from "../../../src/components/b2b"; ## Business to Business @@ -13,6 +13,7 @@ In ZITADEL a B2B organization represents a business partner or partner who typic B2B can be a simple scenario where an organization only shares one of its projects with another organization or have a more complex case where an organization is offering a portal application to all its partners with included (self)administration. + ## Sample scenario Octagon is a fictitious company which is used throughout this guide to explain the details and key concepts of such a B2B scenario. @@ -21,9 +22,10 @@ Octagon tries to solve multiple tasks in the banking field. Its portfolio includ ### Portal Application Octagon has a **Portal application** where its employees can access their account and list all applications they are allowed to use. -Employees work for a department within Octagon or for Octagon itself. +Employees work for a department within Octagon or for Octagon itself. Some of the users have enhanced features because they supervise certain teams. Those can onboard new employees and manage their roles and features. Target groups of the application can be split into: + - **Employees:** users who are using the application as a starting point for their work. - **Supervisors:** users who are mainly using the application to manage users and their access of their department. - **Administrators:** this users are able to grant additional organizations or departments and elect supervisors. @@ -39,7 +41,7 @@ In order to define the need of the **Portal Application** some planning consider ### Login You can decide whether a organization is preselected for the login or if the user is redirected to the default login screen. You can send the user to a specific organization by defining the organization in a custom scope. (primary domain) -Settings to the branding or the login options of the organization can be made from the organization section in [Console](https://{your_domain}.zitadel.cloud/ui/console/org). +Settings to the branding or the login options of the organization can be made from the organization section in [Console](https://{your_domain}.zitadel.cloud/ui/console/org). The behaviour of the login branding can be set in your projects detail page. You can choose the branding of the selected organization, the user resource owner, or the projects resource owner. ### Organizations @@ -56,7 +58,7 @@ In our sample scenario, we assume to have the following users: - **Bill:** is employed at Octagon as Administrator of the Portal Application. Bill also uses a Microsoft Account in combination with a Security Key to secure his account. After having determined the constellation of the organizations and its users, all the necessary data (Portal project with roles and app, users, login requirements, identity providers, branding) should be set up in [Console](https://{your_domain}.zitadel.cloud/ui/console/org). -A B2B sample application for NextJS can be found in our [Example Repo](https://github.com/zitadel/zitadel-examples). +A B2B [sample application](https://github.com/zitadel/zitadel-nextjs-b2b). for NextJS can be found [here](../../examples/login/nextjs-b2b). To allow another organization to use a project, a project grant has to be created. Upon creation, roles for a grant can be limited to a subset of the total project roles. @@ -70,7 +72,7 @@ In this scenario, Dimitri and Michael share the same organization Pentagon, wher > Note: Roles are meant for internal business logic and therefore need to be validated separately, none of the users described are allowed to create user grants, at least if they do not own a ZITADEL manager role. -If you made a dashboard where some users are able to create user grants, the Management API to do such operations should be triggered with the personal access token of the users, not with a token of a machine user, to create a meaningful audit log. +If you made a dashboard where some users are able to create user grants, the Management API to do such operations should be triggered with the personal access token of the users, not with a token of a machine user, to create a meaningful audit log. If you had such a use case, ZITADEL manager roles must be assigned to those users. ### Noteworthy @@ -82,4 +84,4 @@ In such a case with this high potential of scalability where user counts can gro - [Creating an organization](../manage/console/organizations) - [Organization Branding](../manage/customize/branding) -- [Authorization](../integrate/oauth-recommended-flows) \ No newline at end of file +- [Authorization](../integrate/oauth-recommended-flows) diff --git a/docs/netlify.toml b/docs/netlify.toml index 939f53f66b..e77bce6989 100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@ -3,7 +3,7 @@ [[redirects]] from = "/proxy/js/script.js" - to = "https://plausible.io/js/plausible.js" + to = "https://plausible.io/js/script.outbound-links.js" status = 200 force = true diff --git a/docs/sidebars.js b/docs/sidebars.js index bc82d64342..bbd2521b3e 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -9,6 +9,7 @@ module.exports = { "examples/login/react", "examples/login/flutter", "examples/login/nextjs", + "examples/login/nextjs-b2b", ], collapsed: false, }, diff --git a/docs/src/css/card.module.css b/docs/src/css/card.module.css index 1a37215a96..315cb02f6a 100644 --- a/docs/src/css/card.module.css +++ b/docs/src/css/card.module.css @@ -29,6 +29,7 @@ background-position: center; padding: 0.5rem 0; pointer-events: none; + box-shadow: none !important; } .fillspace { diff --git a/docs/static/img/nextjs-b2b/home.png b/docs/static/img/nextjs-b2b/home.png new file mode 100644 index 0000000000..966ecddb1f Binary files /dev/null and b/docs/static/img/nextjs-b2b/home.png differ