Created: 28 Sep 2024, last update: 3 Oct 2024
Managing Sitecore Item Security Rights with the API
When managing content across multiple websites in Sitecore, you may need to set specific item security rights, especially when adding a new role or implementing roles and permissions on existing websites. For instance, assigning permissions to key items like the home page for different roles is a common scenario. While many developers use Sitecore PowerShell to automate this task, did you know you can also manage item rights via the API? In this post, we'll walk through how to do just that.
Setting Item Security with the Authoring GraphQL API
In Sitecore, item security can be managed by updating the __Security field. If you've ever viewed the raw value of this field in the content editor, it might look something like this:
ar|sitecore\Developer|pd|+item:read|pe|+item:write|+item:read|
This string defines various access rights for different roles. Using the Authoring GraphQL API, you can easily modify this field to programmatically control security permissions on any item.
mutation UpdateItem {
updateItem(
input: {
version: 1
language: "en"
itemId: "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
fields: [
{ name: "__Security", value: "ar|sitecore\\Developer|pe|+item:write|" }
]
}
) {
item {
itemId
name
path
}
}
}
Reading Item Security with the API
Just like any other field, the __Security field can be retrieved through the Authoring GraphQL API. However, note that this field is not available in the Edge API and is not indexed in the SOLR Sitecore master index. This means you won't be able to search for or filter items based on security settings in a search query with the API.
In addition to reading the __Security field itself, the Authoring GraphQL API also provides an access property. This property allows you to determine if the current user has specific permissions such as read, write, delete, or rename on the item. You can even check if the user can move the item to a different location in the content tree.
query {
item(where: { path: "/sitecore/content/Home" }) {
name
itemId
security : field(name:"__Security") {
value
}
access {
canWrite
canDelete
canRename
}
}
}
One important thing to keep in mind: the __Security field is a shared field. This means that the security settings apply across all language versions of the item. When querying for an item via the Authoring API, it’s optional to specify a language. If no language is provided, the API will return the item in the first language that contains a version. This behavior seems to follow the default language order you see in the Sitecore content editor’s language selector.
Example: Updating Security Rights for the Home Item Across Multiple Sites
If you're working with multiple sites in Sitecore and need to update the home item security across all of them, SitecoreCommander provides an excellent example. It shows how to iterate through all sites and update the security for the home item. This approach can easily be extended to include other items as well.
Sitecore Commander Example
SitecoreCommander and Visual Studio, providing a powerful scripting and automation framework for managing Sitecore environments. It allows developers and administrators to execute complex scripts and manage long-running tasks efficiently within Sitecore.
//Example iterate through all sites and update the security of the home item
var sites = GetEdgeSites.Get(env, CancellationToken.None);
foreach (var site in sites.Result)
{
var homeItem = await GetItem.GetSitecoreItem(env, CancellationToken.None, site.rootPath);
if (homeItem != null)
{
Console.WriteLine("set right for site " + site.name);
var updated = await UpdateItemSecurity.UpdateItem(env, CancellationToken.None, homeItem.id, "ar|sitecore\\Developer|pd|+item:read|pe|+item:write|+item:read|", "en");
}
}
