IAdmManagedDomain

The IAdmManagedDomain interface provides methods for adding and removing managed Active Directory domains from Adaxes. The interface also allows you to check the accessibility of a domain and change the credentials Adaxes uses to perform operations within a domain.

Inheritance: IAdmTop

To use this interface, you need to bind to the object representing the domain in Adaxes. All domains managed by Adaxes are stored in the well-known Managed Domains container in AD LDS.

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

$domainName = "example.com"

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

# Build the ADS path to the managed domain.
$containerPath = $service.Backend.GetConfigurationContainerPath("ManagedDomains")
$containerPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $containerPath
$domainPath = $containerPathObj.CreateChildPath("DC=$domainName")

# Bind to the domain.
$managedDomain = $service.OpenObject($domainPath, $null, $null, 0)
C#
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        const string domainName = "example.com";

        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Build the ADS path to the managed domain.
        string containerPath = service.Backend.GetConfigurationContainerPath(
            "ManagedDomains");
        AdsPath containerPathObj = new AdsPath(containerPath);
        AdsPath domainPath = containerPathObj.CreateChildPath($"DC={domainName}");

        // Bind to the domain.
        IAdmManagedDomain managedDomain = (IAdmManagedDomain)service.OpenObject(
            domainPath.ToString(), null, null, 0);
    }
}

Methods

  • Method

  • Description

  • Register()

  • Registers an Active Directory domain in Adaxes or changes the credentials used to access the domain if it is already managed.

  • Unregister()

  • Removes a managed domain from Adaxes.

  • ValidateServiceAccount()

  • Validates whether the account with the specified credentials can be used as a service account for the managed domain.

Properties

  • Property

  • Description

  • DomainType

  • Gets or sets the directory type of the managed domain.

  • DisplayName

  • Gets or sets the display name of the managed domain.

  • Status

  • Gets the domain status.

  • LogonName

  • Gets the username of the account that Adaxes uses to perform operations within the domain.

  • SslUsage

  • Gets or sets a value indicating when to use SSL for secure communication with the domain.

Details

Register()

Registers an Active Directory domain in Adaxes or changes the credentials used to access the domain if it is already managed.

void Register(string username, string password)

Parameters

  • username – the username of the account Adaxes will use to perform operations in the domain. Accepted format: user@domain.com or DOMAIN\user.
  • password – the password for the provided account.

Remarks

When the username and password parameters are set to null, the credentials of the Adaxes service account are used. The service account is specified during the installation of the Adaxes service.

Examples

The following code sample registers an Active Directory domain in Adaxes.

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

$domainName = "example.com"
$username = "administrator@example.com"
$password = "secret"

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

# Bind to the 'Managed Domains' container.
$containerPath = $service.Backend.GetConfigurationContainerPath("ManagedDomains")
$container = $service.OpenObject($containerPath, $null, $null, 0)

# Create a new managed domain.
$managedDomain = $container.Create("adm-ManagedDomain", "DC=$domainName")
$managedDomain.SetInfo()

# Provide logon information.
$managedDomain.Register($username, $password)
C#
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        const string domainName = "example.com";
        const string username = "administrator@example.com";
        const string password = "secret";

        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the 'Managed Domains' container.
        string containerPath = service.Backend.GetConfigurationContainerPath("ManagedDomains");
        IADsContainer container = (IADsContainer)service.OpenObject(
            containerPath, null, null, 0);

        // Create a new managed domain.
        IAdmManagedDomain managedDomain = (IAdmManagedDomain)container.Create(
            "adm-ManagedDomain", $"DC={domainName}");
        managedDomain.SetInfo();

        // Provide logon information.
        managedDomain.Register(username, password);
    }
}

The following code sample changes the credentials for a managed Active Directory domain.

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

$domainName = "example.com"
$username = "administrator@example.com"
$password = "secret"

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

# Build the ADS path to the managed domain.
$containerPath = $service.Backend.GetConfigurationContainerPath("ManagedDomains")
$containerPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $containerPath
$domainPath = $containerPathObj.CreateChildPath("DC=$domainName")

# Bind to the domain.
$managedDomain = $service.OpenObject($domainPath, $null, $null, 0)

# Provide logon information.
$managedDomain.Register($username, $password)
C#
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        const string domainName = "example.com";
        const string username = "administrator@example.com";
        const string password = "secret";

        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");
        
        // Build the ADS path to the managed domain.
        string containerPath = service.Backend.GetConfigurationContainerPath("ManagedDomains");
        AdsPath containerPathObj = new AdsPath(containerPath);
        AdsPath domainPath = containerPathObj.CreateChildPath($"DC={domainName}");

        // Bind to the domain.
        IAdmManagedDomain managedDomain = (IAdmManagedDomain)service.OpenObject(
            domainPath.ToString(), null, null, 0);
        
        // Provide logon information.
        managedDomain.Register(username, password);
    }
}

Unregister()

Removes a managed domain from Adaxes.

void Unregister()

Examples

The following code sample removes a domain from Adaxes.

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

$domainName = "example.com"

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

# Build the ADS path to the managed domain.
$containerPath = $service.Backend.GetConfigurationContainerPath("ManagedDomains")
$containerPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $containerPath
$domainPath = $containerPathObj.CreateChildPath("DC=$domainName")

# Bind to the domain.
$managedDomain = $service.OpenObject($domainPath, $null, $null, 0)

# Remove the domain.
$managedDomain.Unregister()
C#
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        const string domainName = "example.com";

        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Build the ADS path to the managed domain.
        string containerPath = service.Backend.GetConfigurationContainerPath("ManagedDomains");
        AdsPath containerPathObj = new AdsPath(containerPath);
        AdsPath domainPath = containerPathObj.CreateChildPath($"DC={domainName}");

        // Bind to the domain.
        IAdmManagedDomain managedDomain = (IAdmManagedDomain)service.OpenObject(
            domainPath.ToString(), null, null, 0);

        // Remove the domain.
        managedDomain.Unregister();
    }
}

ValidateServiceAccount()

Validates whether the account with the specified credentials can be used as a service account for the managed domain. If the account can be used, but doesn't have administrator permissions, the method throws the DirectoryComException exception with the ERROR_NO_SUCH_PRIVILEGE error code.

void ValidateServiceAccount(string username, string password)

DomainType

Gets or sets the directory type of the managed domain.

DisplayName

Gets or sets the display name of the managed domain.

  • Type:
  • string
  • Access:
  • Read/Write

Status

Gets the domain status.

Examples

The following code sample outputs the status of all domains managed by Adaxes.

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

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

# Get a list of managed domains.
$managedDomains = $service.GetManagedDomains()

foreach ($domain in $managedDomains)
{
    # Name
    Write-Host "Domain name:" $domain.Name

    # Status
    Write-Host "Domain status:" -NoNewline
    Switch ($domain.Status)
    {
        "ADM_MANAGEDDOMAINSTATUS_INACTIVE"
        {
            Write-Host "The domain is not operational because it is " +
                       "initializing or an internal error has occurred."
        }
        "ADM_MANAGEDDOMAINSTATUS_UNREGISTERED"
        {
            Write-host "The domain is not accessible to the Adaxes service " +
                       "as administrative credentials were not provided."
        }
        "ADM_MANAGEDDOMAINSTATUS_OPERATING"
        {
            Write-Host "The domain is fully operational and accessible " + 
                       "to the Adaxes service."
        }
    }
    Write-Host
}
C#
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Get a list of managed domains.
        IADsCollection managedDomains = service.GetManagedDomains();

        foreach (IAdmManagedDomainInfo domain in managedDomains)
        {
            // Name
            Console.WriteLine("Domain name: {0}", domain.Name);

            // Status
            Console.Write("Domain status: ");
            switch (domain.Status)
            {
                case ADM_MANAGEDDOMAINSTATUS_ENUM.ADM_MANAGEDDOMAINSTATUS_INACTIVE:
                    Console.WriteLine("The domain is not operational because it is " +
                                      "initializing or an internal error has occurred.");
                    break;
                case ADM_MANAGEDDOMAINSTATUS_ENUM.ADM_MANAGEDDOMAINSTATUS_UNREGISTERED:
                    Console.WriteLine("The domain is not accessible to the Adaxes service " +
                                      "as appropriate credentials were not provided.");
                    break;
                case ADM_MANAGEDDOMAINSTATUS_ENUM.ADM_MANAGEDDOMAINSTATUS_OPERATING:
                    Console.WriteLine("The domain is fully operational and " +
                                      "accessible to the Adaxes service.");
                    break;
            }
            Console.WriteLine();
        }
    }
}

LogonName

Gets the username of the account that Adaxes uses to perform operations within the domain.

  • Type:
  • string
  • Access:
  • Read-only

SslUsage

Gets or sets a value indicating when to use SSL for secure communication with the domain.

Requirements

Minimum required version: 2023

See also

© Softerra 2022. All rights reserved.
Send feedback