Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Edit: Multi-Application Dashboard #234

Merged
merged 1 commit into from
Nov 21, 2024
Merged

Edit: Multi-Application Dashboard #234

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 38 additions & 19 deletions astro/src/content/docs/extend/examples/multi-application-dashboard.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,69 +11,87 @@
import IconButton from 'src/components/icon/Icon.astro';
import InlineUIElement from 'src/components/InlineUIElement.astro';

## Introduction
## Overview

If you're using FusionAuth to manage many applications, you might want to provide your users with a central list of applications, so they know what's available. For example, Google does this for its apps.

![Google app selector](/img/docs/extend/examples/multi-application-dashboard/googleGrid.png)

In this guide you'll learn to make a similar page — a dashboard linking to all the applications in a FusionAuth tenant.
In this guide, you'll learn to make a similar page — a dashboard linking to all the applications in a FusionAuth tenant.

In the language of authentication, FusionAuth is an identity provider (IdP) and your applications and websites are the service providers (SP). One way to authenticate a user from a central dashboard is to use identity provider initiated login. In other words, the dashboard will log the user in, and then redirect them to the selected app. In short, a service provider application will receive a login that it didn't initiate itself. This has security complexities and dangers.
In the language of authentication, FusionAuth is an identity provider (IdP) and your applications and websites are the service providers (SPs). One way to authenticate a user from a central dashboard is to use an identity-provider-initiated login. In other words, the dashboard will log the user in, and then redirect them to the selected app. In short, a service provider application will receive a login that it didn't initiate itself. This has security complexities and dangers.

A simpler and safer way, that you'll use in this guide, is to make each application link in the dashboard do nothing but point to the application's login page. From that point onwards, authentication follows the standard OAuth authorization code flow.
This guide will demonstrate a simpler and safer way to authenticate users from a central dashboard by making each application link in the dashboard point to the application's login page. From that point onwards, authentication follows the standard OAuth Authorization Code Flow.

Check failure on line 24 in astro/src/content/docs/extend/examples/multi-application-dashboard.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'onwards'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'onwards'?", "location": {"path": "astro/src/content/docs/extend/examples/multi-application-dashboard.mdx", "range": {"start": {"line": 24, "column": 204}}}, "severity": "ERROR"}

The next sections of this guide will show you how to make a dashboard for two existing FusionAuth applications in the same tenant. All this requires is customizing the theme for the index landing page of the FusionAuth site. The guide will first show you how to install FusionAuth and make two simple web application web servers. If you already have a FusionAuth installation with existing applications, you can skip ahead to the section that creates the dashboard.
The next section of this guide will show you how to make a dashboard for two existing FusionAuth applications in the same tenant. All this requires is customizing the theme for the index landing page of the FusionAuth site. The guide will first show you how to install FusionAuth and make two simple web application web servers. If you already have a FusionAuth installation with existing applications, you can skip ahead to the section that creates the dashboard.

If you want to follow along with the full guide, you will need Docker installed.

## Download The Example Repository And Run FusionAuth

Use `git clone` to clone the repository at https://github.com/fusionauth/fusionauth-example-multiapp-dashboard, or download it and unzip. Open a terminal in the directory containing the repository files.
Use `git clone` to clone the repository at https://github.com/fusionauth/fusionauth-example-multiapp-dashboard, or download and unzip it.

Open a terminal in the directory containing the repository files.

Run the command below to start FusionAuth.

- Run the command below to start FusionAuth.
```sh
docker compose up
```

<Aside type="note">
If you have completed any FusionAuth tutorials before, you might first have to delete any existing FusionAuth containers with the same name, as well as the database volumes. Run the command below to do that.
If you have completed any FusionAuth tutorials before, you might need to first delete any existing FusionAuth containers with the same name and the database volumes. Run the command below to do that.

```sh
docker ps rm fa faDb; docker compose down -v
```
</Aside>

- Leave FusionAuth running. In a new terminal, run the commands below to start a web server for an app that uses FusionAuth for authentication. The app is called Changebank, and is available at http://localhost:3000. (To learn how to make a simple Node app that uses FusionAuth, read the [quickstart](/docs/quickstarts/quickstart-javascript-express-web)).
Leave FusionAuth running.

In a new terminal, run the commands below to start a web server for the Changebank app, which uses FusionAuth for authentication.

```sh
cd bankApp
docker run --platform=linux/amd64 --rm -v ".:/app" -w "/app" node:23-alpine3.19 sh -c "npm install"
docker run --platform=linux/amd64 --rm --network faNetwork -p 3000:3000 -v ".:/app" -w "/app" -e "PORT=3000" node:23-alpine3.19 sh -c "npm run start"
```
- In a third terminal, run the commands below to start a web server for a the second app that uses FusionAuth for authentication. The app is called Changeinsurance, and is available at http://localhost:3001.

The Changebank app is available at http://localhost:3000.

To learn how to make a simple Node.js app that uses FusionAuth, read the [quickstart](/docs/quickstarts/quickstart-javascript-express-web).

In a third terminal, run the commands below to start a web server for a second app that uses FusionAuth for authentication. The app is called Changeinsurance, and is available at http://localhost:3001.

```sh
cd insuranceApp
docker run --platform=linux/amd64 --rm -v ".:/app" -w "/app" node:23-alpine3.19 sh -c "npm install"
docker run --platform=linux/amd64 --rm --network faNetwork -p 3001:3001 -v ".:/app" -w "/app" -e "PORT=3001" node:23-alpine3.19 sh -c "npm run start"
```

Before making the dashboard, check that you can log in to all three applications. Either use an incognito browser window or don't enable [Keep me signed in](/docs/lifecycle/authenticate-users/logout-session-management#fusionauth-sso) when logging in, otherwise you won't see the login form in the rest of this guide:
Before making the dashboard, check that you can log in to all three applications. Either use an incognito browser window or don't enable [Keep me signed in](/docs/lifecycle/authenticate-users/logout-session-management#fusionauth-sso) when logging in, otherwise, you won't see the login form in the rest of this guide:
- Browse to FusionAuth at http://localhost:9011/admin and log in with `[email protected]` and `password`.
![Changebank](/img/docs/extend/examples/multi-application-dashboard/fa.png)
![FusionAuth](/img/docs/extend/examples/multi-application-dashboard/fa.png)
- Browse to Changebank at http://localhost:3000 and log in with the same username and password.
![Changebank](/img/docs/extend/examples/multi-application-dashboard/changebank.png)
- Browse to Changeinsurance at http://localhost:3001 and log in with the same username and password.
![Changeinsurance](/img/docs/extend/examples/multi-application-dashboard/changeinsurance.png)

If you enabled <InlineUIElement>Keep me signed in</InlineUIElement>, logging out of an application won't log you of FusionAuth. It will only delete the session of the application. Next time you try to log in, FusionAuth will see the FusionAuth authentication cookie in your browser and automatically log you in.
If you enabled <InlineUIElement>Keep me signed in</InlineUIElement>, logging out of an application won't log you out of FusionAuth. It will only delete the session of the application. Next time you try to log in, FusionAuth will see the FusionAuth authentication cookie in your browser and automatically log you in.

## Make A Dashboard

Look at the current FusionAuth landing page at http://localhost:9011. In this section you are going to change it to display links to the two banking app web servers that you started in the previous section.
Look at the current FusionAuth landing page at http://localhost:9011.

In this section, you will change the FusionAuth landing page to display links to the two banking app web servers you started in the previous section.

Log in to your [FusionAuth web interface](http://localhost:9011/admin) and browse to <Breadcrumb>Customizations -> Themes</Breadcrumb>.

Notice there are three themes in the list. The first two are the default FusionAuth themes. The last one, <InlineUIElement>Bank theme</InlineUIElement>, was added by `kickstart.json` when you ran Docker compose. Read about Kickstart [here](/docs/get-started/download-and-install/development/kickstart).

- Log in to your [FusionAuth web interface](http://localhost:9011/admin).
- Browse to <Breadcrumb>Customizations -> Themes</Breadcrumb>. Notice there are three themes in the list. The first two are the default FusionAuth themes. The last one, <InlineUIElement>Bank theme</InlineUIElement>, was added by `kickstart.json` when running Docker compose. Read about Kickstart [here](/docs/get-started/download-and-install/development/kickstart).
- Click the <IconButton name="edit" /> edit button in the Bank theme row's action column.
- Select the <InlineUIElement>Index</InlineUIElement> page (fourth item in the list on the left).
- Paste the code below into the text box and click the <IconButton name="save" /> save button at the top right.
- Paste the code below into the text box.
```html
[#ftl/]
[#-- @ftlvariable name="tenant" type="io.fusionauth.domain.Tenant" --]
Expand Down Expand Up @@ -127,8 +145,9 @@
[/@helpers.body]
[/@helpers.html]
```
- Click the <IconButton name="save" /> save button at the top right.

Beside a little CSS for styling, the code above has only two changes, adding hyperlink `<a href="http://localhost:3000/account">Changebank</a>` elements for the two applications. Note that the links don't point to the login page of the target application — instead they point to the logged-in main page. If the user isn't logged in to FusionAuth, then they will be automatically redirected to the app's login page. But if they are already logged in, they will be taken straight to the app and can get to work. This saves the user time. (If you want to see how this authentication check in the app works, look at `bankApp/routes/index.js` in the sample repository you downloaded).
Besides a little CSS for styling, the code above has only two changes: Adding hyperlink `<a href="http://localhost:3000/account">Changebank</a>` elements for the two applications. Note that the links don't point to the login page of the target application. Instead, they point to the logged-in main page. If the user isn't logged in to FusionAuth, they will be automatically redirected to the app's login page. If they are already logged in, they will be taken straight to the app. This saves the user time. (To see how this authentication check in the app works, look at `bankApp/routes/index.js` in the sample repository you downloaded.)

To see the new landing page, browse to http://localhost:9011.
![FusionAuth app dashboard](/img/docs/extend/examples/multi-application-dashboard/dashboard.png)
Expand All @@ -144,4 +163,4 @@

## Next Steps

To make a dashboard for your FusionAuth instance, all you have to do is make links in a custom theme for the FusionAuth landing page similar to the ones shown above. [FusionAuth themes](/docs/customize/look-and-feel/) use a template language called FTL. Read more about it [here](https://freemarker.apache.org/index.html).
To make a dashboard for your FusionAuth instance, all you need to do is make links in a custom theme for the FusionAuth landing page similar to the ones shown above. [FusionAuth themes](/docs/customize/look-and-feel/) use a template language called FTL. Read more about it [here](https://freemarker.apache.org/index.html).
Loading