From e25f4a7eaff33bc91135d12bf37ee6028d1e7054 Mon Sep 17 00:00:00 2001 From: Jacob Overgaard <752371+iOvergaard@users.noreply.github.com> Date: Fri, 28 Jun 2024 09:02:49 +0200 Subject: [PATCH] docs: merge authentication.md into README.md and let people know they should report issues on Umbraco-CMS --- .github/README.md | 30 +++++++++++++++---- docs/authentication.md | 66 ------------------------------------------ 2 files changed, 25 insertions(+), 71 deletions(-) delete mode 100644 docs/authentication.md diff --git a/.github/README.md b/.github/README.md index 728513b60c..c8ee810d64 100644 --- a/.github/README.md +++ b/.github/README.md @@ -29,9 +29,6 @@ The development environment is the default environment and is used when running ### Run against a local Umbraco instance -> **Note** -> Make sure you have followed the [Authentication guide](https://github.com/umbraco/Umbraco.CMS.Backoffice/blob/main/docs/authentication.md) before continuing. - If you have a local Umbraco instance running, you can use the development environment to run against it by overriding the API URL and bypassing the mock-service-worker in the frontend client. Create a `.env.local` file and set the following variables: @@ -41,14 +38,37 @@ VITE_UMBRACO_API_URL=https://localhost:44339 # This will be the URL to your Umbr VITE_UMBRACO_USE_MSW=off # Indicate that you want all API calls to bypass MSW (mock-service-worker) ``` +Open this file in an editor: `src/Umbraco.Web.UI/appsettings.Development.json` and add this to the `Umbraco:CMS:Security` section to override the backoffice host: + +```json +"Umbraco": { + "CMS": { + "Security":{ + "BackOfficeHost": "http://localhost:5173", + "AuthorizeCallbackPathName": "/oauth_complete", + "AuthorizeCallbackLogoutPathName": "/logout", + "AuthorizeCallbackErrorPathName": "/error", + }, + }, +} +``` + +Now start the vite server: `npm run dev:server` in your backoffice folder and open the http://localhost:5173 URL in your browser. + ### Storybook Storybook is also being built and deployed automatically on the Main branch, including a preview URL on each pull request. See it in action on this [Azure Static Web App](https://ambitious-stone-0033b3603.1.azurestaticapps.net/). +You can test the Storybook locally by running `npm run storybook`. This will start the Storybook server and open a browser window with the Storybook UI. + +Storybook is an excellent tool to test out UI components in isolation and to document them. It is also a great way to test the responsiveness and accessibility of the components. + ## Contributing -We accept contributions to this project. However be aware that we are mainly working on a private backlog, so not everyone will be immediately obvious. If you want to get started on contributing, please read the [contribute space](https://github.com/umbraco/Umbraco.CMS.Backoffice/contribute) where you will be able to find the guidelines on how to contribute as well as a list of good first issues. +We accept contributions to this project. However be aware that we are mainly working on a private backlog, so not everything will be immediately obvious. If you want to get started on contributing, please read the [contributing guidelines](./CONTRIBUTING.md). + +A list of issues can be found on the [Umbraco-CMS Issue Tracker](https://github.com/umbraco/Umbraco-CMS/issues). Many of them are marked as `community/up-for-grabs` which means they are up for grabs for anyone to work on. ## Documentation -The documentation can be found on [Umbraco Docs](https://docs.umbraco.com/umbraco-backoffice/). The documentation is a work in progress. +The documentation can be found on [Umbraco Docs](https://docs.umbraco.com/umbraco-cms). diff --git a/docs/authentication.md b/docs/authentication.md deleted file mode 100644 index a713a9a19e..0000000000 --- a/docs/authentication.md +++ /dev/null @@ -1,66 +0,0 @@ -# Authentication - -## What is this? - -You can now authorize against the Management API using OpenID Connect. Most endpoints will soon require a token, albeit they are open for now. - -## How does it work? - -You need to authorize against the Management API using OpenID Connect if you want to access protected endpoints running on a real Umbraco instance. This will give you a token that you can use to access the API. The token is stored in local storage and will be used for all subsequent requests. - -If you are running the backoffice locally, you can use the `VITE_UMBRACO_USE_MSW` environment variable to bypass the OpenID Connect flow and use mocked responses instead by setting it to `on` in the `.env.local` file. - -## How to use - -There are two ways to use this: - -### Running directly in the Umbraco-CMS repository - -1. Checkout the `v14/dev` branch of [Umbraco-CMS](https://github.com/umbraco/Umbraco-cms/tree/v14/dev) -2. Run `git submodule update --init` to initialize and pull down the backoffice repository - 1. If you are using a Git GUI client, you might need to do this manually -3. Go to src/Umbraco.Web.UI or switch default startup project to "Umbraco.Web.UI" -4. Start the backend server: `dotnet run` or run the project from your IDE -5. Access https://localhost:44339/umbraco and complete the installation of Umbraco -6. You should see the log in screen after installation -7. Log in using the credentials you provided during installation - -### Running with Vite - -1. Perform steps 1 to 5 from before -2. Open this file in an editor: `src/Umbraco.Web.UI/appsettings.Development.json` -3. Add this to the Umbraco.CMS section to override the backoffice host: - -```json -"Umbraco": { - "CMS": { - "Security":{ - "BackOfficeHost": "http://localhost:5173", - "AuthorizeCallbackPathName": "/oauth_complete", - "AuthorizeCallbackLogoutPathName": "/logout", - "AuthorizeCallbackErrorPathName": "/error", - }, - }, - [...] -} -``` - -4. Set Vite to use Umbraco API by copying the ".env" file to ".env.local" and setting the following: - -``` -VITE_UMBRACO_USE_MSW=off -VITE_UMBRACO_API_URL=https://localhost:44339 -``` - -5. Start the vite server: `npm run dev` in your backoffice folder -6. Check that you are sent to the login page -7. Log in - -## To test a secure endpoint - -All Management API endpoints are secure and require a token except for the status and installer endpoints. If you want to mark a custom endpoint as secure, you can add the `[Authorize]` attribute to the controller or action. This will require you to be logged in to access the endpoint. - -## What does not work yet - -- If your session expires or your token is revoked, you will start getting 401 network errors, which for now only will be shown as a notification in the UI - we need to figure out how to send you back to log in -- We do not _yet_ poll to see if the token is still valid or check how long before you are logged out, so you won't be notified before trying to perform actions that require a token