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 authentication of high-privileged 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).

Note

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.
[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.
$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $admService.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $admService.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 = $admService.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() 

Note

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.
[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.
$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly($serviceHost)

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $admService.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $admService.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 = $admService.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() 

Note

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.
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost" 

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

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $admService.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $admService.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() 

Note

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.
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost" 

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

# Prompt for credentials.
$credential = Get-Credential

# Bind to the REST API configuration container.
$containerPath = $admService.Backend.GetConfigurationContainerPath("ClientAppsContainer")
$container = $admService.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.ObjectGuid) 
            $trustee = $admService.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.ObjectGuid) 
            $trustee = $admService.OpenObject($adsPath, $credential.UserName, `
                $credential.GetNetworkCredential().Password, 0)
            Write-Host "`t" $trustee.Get("distinguishedName")
        }
    }
    "ADM_WEBUI_ACCESSCONTROLTYPE_ALLOWALL"
    {
        Write-Host "Allow everyone"
    }
}

See also