Restrict access to REST API

You can configure which users or groups can authenticate to REST API. For example, this setting can be used as an additional security measure to block the authentication of high-privilege accounts, or allow only a single dedicated service account to authenticate. Access control can operate in the following modes:

  • Allow only specific users or group members to authenticate.
  • Deny specific users or group members to authenticate.
  • Allow everyone to authenticate (default).

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

Execute one of the following scripts and restart IIS on the computer where the REST API component is installed.

 Allow only specific users or groups

In the script:

  • $serviceHost – the host name of the computer where the Adaxes service is installed.
  • $allowAuthOf – an array of distinguished names (DNs) of users and groups which should be allowed to authenticate.
  • $replace – if set to $true, the script will replace the current list of users who are allowed to authenticate with the supplied DNs.
Adaxes 2023 and newer
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$allowAuthOf = @(
    "CN=John Smith,CN=Users,DC=example,DC=com",
    "CN=My group,OU=Groups,DC=example,DC=com"
)
$replace = $true  

# 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: ['AccessControlForUsers']}") | ConvertFrom-Json

# Set access control mode.
$config.accessControlForUsers.type = "AllowSpecific"

# Create access control list from supplied DNs.
$accessListNew = @()
foreach ($trustee in $allowAuthOf)
{
    $objectReference = @{
        "referenceType" = 0;
        "key" = $trustee
    }
    $accessListNew += $objectReference
}

# Preserve existing restrictions.
if (-not $replace)
{
    $accessListCurrent = $config.accessControlForUsers.allowedSpecificItems
    foreach ($trustee in $accessListCurrent)
    {
        # Skip if already in new list.
        if ($allowAuthof.Contains($trustee.'$$refObjectInfo'.dn)) {continue}

        $objectReference = @{
            "referenceType" = 0;
            "key" = $trustee.'$$refObjectInfo'.dn
        }
        $accessListNew += $objectReference
    }
}

# Save settings.
$config.accessControlForUsers.allowedSpecificItems = $accessListNew
$restApi.FromJson("{elements: ['AccessControlForUsers']}", ($config | ConvertTo-Json -Depth 10))
Adaxes 2021.1
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost" 
$allowAuthOf = @(
    "CN=John Smith,CN=Users,DC=example,DC=com",
    "CN=My group,OU=Groups,DC=example,DC=com"
) 
$replace = $false 

# 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
$accessControl = $restApi.AccessControlForUsers

# Set access control mode.
$accessControl.AccessControlType = "ADM_WEBUI_ACCESSCONTROLTYPE_ALLOWSPECIFIC"

# Create access control list from supplied DNs.
$accessList = @()
foreach ($dn in $allowAuthOf)
{
    $trustee = $service.OpenObject("Adaxes://$dn", $credential.UserName, `
        $credential.GetNetworkCredential().Password, 0)
    $guid = [Guid]$trustee.Get("objectGuid")
    $objRef = [Softerra.Adaxes.Adsi.AdmObjectReference]::CreateFromGuid($guid)
    $accessList += $objRef
}
if (-not $replace)
{
    # Preserve existing restrictions.
    $accessList += $accessControl.AllowedSpecificItems
}

# Save settings.
$accessControl.AllowedSpecificItems = $accessList | Select-Object -Unique
$restApi.AccessControlForUsers = $accessControl
$restApi.SetInfo()

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

 Deny specific users or groups

In the script:

  • $serviceHost – the host name of the computer where the Adaxes service is installed.
  • $denyAuthOf – an array of distinguished names (DNs) of users and groups which should be denied authentication.
  • $replace – if set to $true, the script will replace the current list of users who are denied authentication with the supplied DNs.
Adaxes 2023 and newer
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$denyAuthOf = @(
    "CN=John Smith,CN=Users,DC=example,DC=com",
    "CN=My group,OU=Groups,DC=example,DC=com"
)
$replace = $true  

# 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: ['AccessControlForUsers']}") | ConvertFrom-Json

# Set access control mode.
$config.accessControlForUsers.type = "DenySpecific"

# Create access control list from supplied DNs.
$accessListNew = @()
foreach ($trustee in $denyAuthOf)
{
    $objectReference = @{
        "referenceType" = 0;
        "key" = $trustee
    }
    $accessListNew += $objectReference
}

# Preserve existing restrictions.
if (-not $replace)
{
    $accessListCurrent = $config.accessControlForUsers.deniedSpecificItems
    foreach ($trustee in $accessListCurrent)
    {
        # Skip if already in new list.
        if ($denyAuthOf.Contains($trustee.'$$refObjectInfo'.dn)) {continue}

        $objectReference = @{
            "referenceType" = 0;
            "key" = $trustee.'$$refObjectInfo'.dn
        }
        $accessListNew += $objectReference
    }
}

# Save settings.
$config.accessControlForUsers.deniedSpecificItems = $accessListNew
$restApi.FromJson("{elements: ['AccessControlForUsers']}", ($config | ConvertTo-Json -Depth 10))
Adaxes 2021.1
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost" 
$denyAuthOf = @(
    "CN=John Smith,CN=Users,DC=example,DC=com",
    "CN=My group,OU=Groups,DC=example,DC=com"
) 
$replace = $true 

# 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
$accessControl = $restApi.AccessControlForUsers

# Set access control mode.
$accessControl.AccessControlType = "ADM_WEBUI_ACCESSCONTROLTYPE_DENYSPECIFIC"

# Create access control list from supplied DNs.
$accessList = @()
foreach ($dn in $denyAuthOf)
{
    $trustee = $service.OpenObject("Adaxes://$dn", $credential.UserName, `
        $credential.GetNetworkCredential().Password, 0)
    $guid = [Guid]$trustee.Get("objectGuid")
    $objRef = [Softerra.Adaxes.Adsi.AdmObjectReference]::CreateFromGuid($guid)
    $accessList += $objRef
}
if (-not $replace)
{
    # Preserve existing restrictions.
    $accessList += $accessControl.DeniedSpecificItems
}

# Save settings.
$accessControl.DeniedSpecificItems = $accessList | Select-Object -Unique
$restApi.AccessControlForUsers = $accessControl
$restApi.SetInfo()

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

 Allow everyone

In the script:

  • $serviceHost – the host name of the computer where Adaxes service is installed.
Adaxes 2023 and newer
[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: ['AccessControlForUsers']}") | ConvertFrom-Json

# Set access control mode.
$config.accessControlForUsers.type = "AllowAll"

# Save settings.
$restApi.FromJson("{elements: ['AccessControlForUsers']}", ($config | ConvertTo-Json -Depth 10))
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
$accessControl = $restApi.AccessControlForUsers

# Set access control mode.
$accessControl.AccessControlType = "ADM_WEBUI_ACCESSCONTROLTYPE_ALLOWALL"

# Save settings.
$restApi.AccessControlForUsers = $accessControl
$restApi.SetInfo()

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

View current settings

Execute the following script. In the script:

  • $serviceHost – the host name of the computer where Adaxes service is installed.
Adaxes 2023 and newer
[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: ['AccessControlForUsers']}") | ConvertFrom-Json

# Select access control list based on current access mode.
switch ($config.accessControlForUsers.type)
{
    "0" # AllowAll
    {
        Write-Host "Allow everyone"
    }
    "1" # AllowSpecific
    {
        Write-Host "Allow the following users or groups:"
        $accessList = $config.accessControlForUsers.allowedSpecificItems
        foreach ($item in $accessList)
        {
            $dn = $item.'$$refObjectInfo'.dn
            Write-Host "`t" $dn
        }
    }
    "2" # DenySpecific
    {
        Write-Host "Deny the following users or groups:"
        $accessList = $config.accessControlForUsers.deniedSpecificItems
        foreach ($item in $accessList)
        {
            $dn = $item.'$$refObjectInfo'.dn
            Write-Host "`t" $dn
        }
    }
}
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
$accessControl = $restApi.AccessControlForUsers

# Select access control list based on current access mode.
switch ($accessControl.AccessControlType)
{
    "ADM_WEBUI_ACCESSCONTROLTYPE_ALLOWSPECIFIC"
    {
        Write-Host "Allow the following users or groups:"
        $accessList = $accessControl.AllowedSpecificItems
        foreach ($item in $accessList)
        {
            $adsPath = [Softerra.Adaxes.Adsi.AdmObjectReference]::ToAdsPath($item) 
            $trustee = $service.OpenObject($adsPath, $credential.UserName, `
                $credential.GetNetworkCredential().Password, 0)
            Write-Host "`t" $trustee.Get("distinguishedName")
        }
    }
    "ADM_WEBUI_ACCESSCONTROLTYPE_DENYSPECIFIC"
    {
        Write-Host "Deny the following users or groups:"
        $accessList = $accessControl.DeniedSpecificItems
        foreach ($item in $accessList)
        {
            $adsPath = [Softerra.Adaxes.Adsi.AdmObjectReference]::ToAdsPath($item) 
            $trustee = $service.OpenObject($adsPath, $credential.UserName, `
                $credential.GetNetworkCredential().Password, 0)
            Write-Host "`t" $trustee.Get("distinguishedName")
        }
    }
    "ADM_WEBUI_ACCESSCONTROLTYPE_ALLOWALL"
    {
        Write-Host "Allow everyone"
    }
}

See also

© Softerra 2022. All rights reserved.
Send feedback