Umbraco-CMS/src/Umbraco.Web.UI.Client/docs/authentication.md

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
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:

"Umbraco": {
	"CMS": {
		"Security":{
			"BackOfficeHost": "http://localhost:5173",
			"AuthorizeCallbackPathName": "/"
		},
	},
	[...]
}

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