Restrict access to objects

You can restrict access to certain objects to make it impossible to perform any operations on them using REST API, even if the authenticated user has sufficient permissions.

Out of the box, only Adaxes service administrators have the rights to configure REST API. Other users can be granted such rights using a security role with the Write all properties permission assigned over Configuration objects.

Change settings

 Restrict access by object type {id=objectTypeRestriction}

You can restrict which object types (e.g. Users, Computers) can be accessed via REST API. To do this, execute the following script and restart IIS on the computer where REST API component is installed.

In the script:

  • $serviceHost – the host name of the computer where the Adaxes service is installed.
  • $allowedObjectTypes – an array of object types which should be accessible via REST API.
Adaxes 2023 and newer
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$allowedObjectTypes = @(
    "user",
    "group",
    "organizationalUnit",
    "container",
    "builtinDomain",
    "computer",
    "contact",
    "printQueue"
    # "volume"
    # "adm-RoomMailbox"
    # "adm-EquipmentMailbox"
    # "adm-LinkedMailbox"
) 

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $service.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $service.OpenObject($containerPath, $credential.UserName,`
    $credential.GetNetworkCredential().Password, 0)
$restApi = $container.RestApi

$config = $restApi.ToJson("{elements: ['BrowsingFilter']}") | ConvertFrom-Json 
$browsingFilter = $config.browsingFilter

# Restrict object types.
$objectTypeList = @()
foreach ($objectType in $allowedObjectTypes)
{
    $objectTypeList += @{objectType = $objectType}
}
$browsingFilter.objectTypes = $objectTypeList

# Save settings.
$config.browsingFilter = $browsingFilter
$restApi.FromJson("{elements: ['BrowsingFilter']}", ($config | ConvertTo-Json -Depth 100))
Adaxes 2021.1
using namespace Softerra.Adaxes.Management.WebUI.Browsing
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost" 
$allowedObjectTypes = @(
    "user",
    "group",
    "organizationalUnit",
    "container",
    "builtinDomain",
    "computer",
    "contact",
    "printQueue"
    # "volume"
    # "adm-RoomMailbox"
    # "adm-EquipmentMailbox"
    # "adm-LinkedMailbox"
) 

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $service.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $service.OpenObject($containerPath, $credential.UserName,`
    $credential.GetNetworkCredential().Password, 0)
$restApi = $container.RestApi

# Restrict object types.
$filterOptions = $restApi.FilterOptionsSettings
$objectTypeList = @()
foreach ($objectType in $allowedObjectTypes)
{
    $objectTypeSettings = [AdmWebUIBrowsingObjectTypeSettings]::new($objectType, $false, -1)
    $objectTypeList += $objectTypeSettings
}

# Save settings.
$filterOptions.ObjectTypes = $objectTypeList
$restApi.FilterOptionsSettings = $filterOptions
$restApi.SetInfo()

After executing the script, restart IIS on the computer where REST API component is installed.

 Restrict access using criteria {id=criteriaRestriction}

You can prevent access to objects that don't match your criteria. It is possible to specify common criteria for all object types and separate criteria for particular object types. Only objects that match common and type-specific criteria will be available via REST API. To restrict access using criteria, execute the following script and restart IIS on the computer where REST API component is installed.

In the script:

  • $serviceHost – the host name of the computer where the Adaxes service is installed.
  • $criteria – the criteria for restricting objects. For details on how to build criteria, see How to build criteria. Specify an empty criteria to allow all objects. Use the wildcard object type (*) to specify common criteria.

If you want to specify criteria for an object type, it must be present in the list allowed object types.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"

# Specify criteria.
$criteria = New-AdmCriteria
$criteria.AddType("*", {description -empty $false}) # Common: objects with non-empty description
$criteria.AddType("user", {accountDisabled -eq $false}) # Users: account enabled
$criteria.AddType("group", {groupType -eq "security"}) # Groups: security groups

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $service.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $service.OpenObject($containerPath, $credential.UserName,`
    $credential.GetNetworkCredential().Password, 0)
$restApi = $container.RestApi

$config = $restApi.ToJson("{elements: ['BrowsingFilter']}") | ConvertFrom-Json 
$browsingFilter = $config.browsingFilter

# Set object-specific criteria.
foreach ($objectType in $browsingFilter.objectTypes)
{
    $name = $objectType.objectType
    if ($criteria[$name])
    {
        $objectType.criteria = @{ enabled = $true; item = $criteria[$name].ToDto() }
    }
    else
    {
        $objectType.criteria.enabled = $false
    }
}

# Set common criteria.
if ($criteria["*"])
{
    $browsingFilter.commonCriteria = @{ enabled = $true; item = $criteria["*"].ToDto() }
}
else
{
    $browsingFilter.commonCriteria.enabled = $false
}

# Save settings.
$config.browsingFilter = $browsingFilter
$restApi.FromJson("{elements: ['BrowsingFilter']}", ($config | ConvertTo-Json -Depth 100))

After executing the script, restart IIS on the computer where REST API component is installed.

 Restrict access using an LDAP filter (Adaxes 2021.1 only) {id=ldapFilterRestriction}

In Adaxes 2021.1, you can restrict access to objects that don't match an LDAP filter. To do this, execute the following script and restart IIS on the computer where REST API component is installed.

LDAP filter restriction and object type restriction can be used simultaneously.

In the script:

  • $serviceHost – the host name of the computer where the Adaxes service is installed.
  • $myFilter – the LDAP filter to apply. To disable LDAP filter restriction, specify $null.
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost" 
$myFilter = "(&(sAMAccountType=805306368)(!(department=IT)))" 

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $service.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $service.OpenObject($containerPath, $credential.UserName,`
    $credential.GetNetworkCredential().Password, 0)
$restApi = $container.RestApi

# Set the LDAP filter restrictions.
$filterOptions = $restApi.FilterOptionsSettings
$filteroptions.FilterEnabled = if ($null -eq $myFilter) {$false} else {$true}
$filterOptions.Filter = $myFilter

# Save settings.
$restApi.FilterOptionsSettings = $filterOptions
$restApi.SetInfo()

After executing the script, restart IIS on the computer where REST API component is installed.

View current settings

Execute the following script. In the script:

  • $serviceHost – the host name of the computer where the Adaxes service is installed.

You can paste the JSON criteria returned by the script into the criteria editor in Adaxes UI to get a visual representation.

Adaxes 2023 and newer
using namespace Softerra.Adaxes.Directory.Criteria
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $service.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $service.OpenObject($containerPath, $credential.UserName,`
    $credential.GetNetworkCredential().Password, 0)
$restApi = $container.RestApi

$config = $restApi.ToJson("{elements: ['BrowsingFilter']}") | ConvertFrom-Json 
$browsingFilter = $config.browsingFilter

function CreateOutputItem($typeText, $criteriaItem)
{
    if ($criteriaItem)
    {
        $compoundItem = (New-AdmCriteria).CreateCompound()
        $compoundItem.FromJson($null, ($criteriaItem | ConvertTo-Json -Depth 100))
        $formatter = New-Object CriteriaFormatter
        $formatter.Init($service)
        $options = [CriteriaFormattingOptions]::ValueReferencesAllowed
        $criteriaText = $formatter.GetDescription($compoundItem, $null, $options, $null, $null)
    }
    else
    {
        $criteriaText = "<none>"
    }
    return [PSCustomObject]@{ "Object type" = $typeText; "Criteria" = $criteriaText }
}

# Object types
$objectTypesOutput = @()
foreach ($type in $browsingFilter.objectTypes)
{
    if ($type.criteria.enabled)
    {
        $objectTypesOutput += CreateOutputItem $type.objectType $type.criteria.item
    }
    else
    {
        $objectTypesOutput += CreateOutputItem $type.objectType $null
    }
}

# Common criteria
if ($browsingFilter.commonCriteria.enabled)
{
    $commonOutput = CreateOutputItem "Common criteria:" $browsingFilter.commonCriteria.item
}
else
{
    $commonOutput = CreateOutputItem "Common criteria:" $null
}

# Output
$objectTypesOutput | Sort-Object -Property "Object type" | Format-Table
$commonOutput | Format-Table -HideTableHeaders
Adaxes 2021.1
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost" 

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $service.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $service.OpenObject($containerPath, $credential.UserName,`
    $credential.GetNetworkCredential().Password, 0)
$restApi = $container.RestApi

# Object types
$allowedObjectTypes = $filterOptions.ObjectTypes
Write-Host "The following object types can be accessed:"
foreach ($entry in $allowedObjectTypes)
{ 
    Write-Host "`t" $entry.ObjectType 
}

# LDAP filter
$filterOptions = $restApi.FilterOptionsSettings
if ($filterOptions.FilterEnabled)
{ 
    Write-Host "The following LDAP filter restriction is enabled:" $filterOptions.Filter 
}
else 
{ 
    Write-Host "LDAP filter restriction is disabled"
}

See also

© Softerra 2022. All rights reserved.
Send feedback