Querying the Management API - authentication

skartknet · May 7, 2025, 11:27pm

Hi all, I’m creating a Vue app in the frontend that queries some endpoints of the Management API. Is that considered and ‘external application’ in regards to the documentation on how to authenticate?

I want the app to get access to the API only if a backend user is logged in and has the right permissions. Do I still need, as per the docs to create an API user? Can’t I use somehow the user’s credentials?

jacob · May 8, 2025, 6:24am

Normal Backoffice users require a manual login; that is to say, the user must manually type in the username and password. Depending on your intended flow, an API user might be easier as it only requires a static API key.

However, if you want a normal login, you must register an extra OpenID provider (with a client_id and redirect_url) that will redirect you back to the website frontend after a successful login.

Take a look here in the source code where Postman and Swagger UI are registered as allowed providers:

github.com/umbraco/Umbraco-CMS

src/Umbraco.Cms.Api.Management/Security/BackOfficeApplicationManager.cs

45148f22a


      
          await CreateOrUpdate(
              DeveloperOpenIddictApplicationDescriptor(
                  "Umbraco Swagger access",
                  Constants.OAuthClientIds.Swagger,
                  backOfficeHostsAsArray.Select(backOfficeUrl => CallbackUrlFor(backOfficeUrl, "/umbraco/swagger/oauth2-redirect.html")).ToArray()),
              cancellationToken);
          
          await CreateOrUpdate(
              DeveloperOpenIddictApplicationDescriptor(
                  "Umbraco Postman access",
                  Constants.OAuthClientIds.Postman,
                  [new Uri("https://oauth.pstmn.io/v1/callback"), new Uri("https://oauth.pstmn.io/v1/browser-callback")]),
              cancellationToken);

skartknet · May 8, 2025, 11:44pm

Hi Jacob. Not sure if I understand your approach . So the issue is that I would like to show an editor in the frontend only to logged in users. I was hoping that I can use the logged in user’ credentias to also query the management API.

So I don’t want to add a custom login process, which is what I understand from your reponse.

update: actually I think I was approaching the problem from the wrong direction. I can just display what I want using Razor instead of Vue.

update 2: which takes me to my next question. On Umbraco 13 we have the UmbracoAuthorizedApiController which is deprecated on v14. Does that mean that all the request need to be done through the Management API, which means we need to use API users?

jacob · May 9, 2025, 5:59am

Your users have to log in somehow, and you need to obtain their access_token after the fact. You can send them to the login screen like normal, but they would end up in the Backoffice afterwards. If you register your own OpenId descriptor, you can set the allowed redirect URL to be back to your frontend. That was my approach.

Great if you can show things with Razor instead. The equivalent to the UmbracoAuthorizedApiController would be ManagementApiControllerBase and an added Authorize filter, like so:

[Authorize(Policy = AuthorizationPolicies.BackOfficeAccess)]
public class MyControllerBase : ManagementApiControllerBase
{}

That hooks your controller up to the .NET authentication, and you can query them using the Backoffice access_token or the token from an API User.

skartknet · May 10, 2025, 5:29am

Awesome, I made it work! Thanks for your help

skartknet · May 10, 2025, 9:00pm

Now I have another question. I’m using the backoffice access_token (taken from localStorage) and all works well, but when it expires, I need to navigate to the backoffice for the token to be re-issued.

I’m trying to use the refresh token in the localStorage that is stored along the access token, but I keep getting a 400. I’m posting the refresh token to the /umbraco/management/api/v1/security/back-office/token endpoint; is that the right enpoint? Is this the right way of getting a new access token?

jacob · May 12, 2025, 7:44am

Great to hear that you made it work. Just to be sure, you are outside of the Backoffice context here, e.g. in your own application/frontend, correct?

If so, I think you are on the right track, although it might be better for you to use the actual login mechanisms rather than using the token found in local storage.
We use the library called @appauth/openid to handle this for us, so I’m not exactly sure what to send to the endpoint. The /token endpoint is correct to use, but I think you need to set the grant_type to "refresh_token" for it to work. Perhaps you can use the same openid library as we do in the Backoffice?

skartknet · May 12, 2025, 11:03am

So what I’m trying to do is to display a visual editor in the frontend for the admins/editors to edit some fields using that instead of the backoffice. That’s why I want to use the credentials of the already-loggedin user.

Similar to the uSkinned Visual Editor.

I tried to post the refresh token to the /token endpoint but I get a response saying that I need the client_id I don’t know where to get the client id from.

EDIT: I figured that the client_id is ‘umbraco-back-office’ but now I’m getting 'token is invalid

This is my payload:

And this the response:

I have checked and the refresh token stored is correct.

EDIT 2: not sure what was wrong before, but it seems to be refreshing the token correctly now

thanks for your help!

jacob · May 12, 2025, 12:01pm

The client IDs are what you register through the BackOfficeApplicationManager, so "umbraco-back-office" is the registered client for the Backoffice.

Note that tokens can only be refreshed once, so if someone else did that on your token, for example if you had a Backoffice tab open in your browser, then you would get a new refresh_token to be used. That might explain why you could not refresh the first time around.
There are mechanisms in the Backoffice to load in new tokens on all open tabs when an authorization event occurs. You should probably have something similar if you plan for users to use your application in more than one tab.

There is actually a browser event, you can listen in on when the Local Storage refreshes with new values - that is what the Backoffice does. If you did that, your app would work with your own refreshes as well as those coming from the Backoffice. Here is an example from the Backoffice:

github.com/umbraco/Umbraco-CMS

src/Umbraco.Web.UI.Client/src/packages/core/auth/auth.context.ts

2b00f15d1


      
          			this.authorizationSignal,
          			() => {
          				// Update the authorization state
          				this.getIsAuthorized();
          			},
          			'_authFlowAuthorizationSignal',
          		);
          
          		// Observe changes to local storage and update the authorization state
          		// This establishes the tab-to-tab communication
          		window.addEventListener('storage', this.#onStorageEvent.bind(this));
          	}
          
          	override destroy(): void {
          		super.destroy();
          		window.removeEventListener('storage', this.#onStorageEvent.bind(this));
          	}
          
          	async #onStorageEvent(evt: StorageEvent) {
          		if (evt.key === UMB_STORAGE_TOKEN_RESPONSE_NAME) {
          			// Close any open auth windows

skartknet · May 13, 2025, 10:51am

wow, that’s great info. Thanks! I’ll give it a try.

system · June 12, 2025, 10:52am

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.