IAdmManagedDomain

The IAdmManagedDomain interface provides methods for adding and removing managed 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 the IAdmManagedDomain interface, you need to bind to the object representing the domain in Adaxes. All domains managed by Adaxes are located on the Adaxes Configuration Server (AD LDS). To bind to a domain object, you need to specify its ADS path consisting of the domain name specified as DC=domainName and the path to the Managed Domains container, where domainName is the fully qualified name of the domain (e.g. example.com).

 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 ADS path to the managed domain
$managedDomainsPath = $service.Backend.GetConfigurationContainerPath("ManagedDomains")
$managedDomainsPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $managedDomainsPath
$managedDomainPath = $managedDomainsPathObj.CreateChildPath("DC=$domainName")

# Bind to the domain
$managedDomain = $service.OpenObject($managedDomainPath, $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 ADS path to the managed domain
        string managedDomainsPath = service.Backend.GetConfigurationContainerPath(
            "ManagedDomains");
        AdsPath managedDomainsPathObj = new AdsPath(managedDomainsPath);
        AdsPath managedDomainPath = managedDomainsPathObj.CreateChildPath("DC=" + domainName);

        // Bind to the domain
        IAdmManagedDomain managedDomain = (IAdmManagedDomain)service.OpenObject(managedDomainPath.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 - Specifies the username of the account used by Adaxes to perform operations within the domain. The username should be provided in the user@domain.com or DOMAIN\user format.
  • password - Specifies the password to use with the username provided.

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 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
$managedDomainsPath = $service.Backend.GetConfigurationContainerPath("ManagedDomains")
$managedDomainsContainer = $service.OpenObject($managedDomainsPath, $null, $null, 0)

# Create a new managed domain
$managedDomain = $managedDomainsContainer.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 passowrd = "secret";

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

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

        // Create a new managed domain
        IAdmManagedDomain managedDomain = (IAdmManagedDomain)managedDomainsContainer.Create(
            "adm-ManagedDomain", "DC=" + domainName);
        managedDomain.SetInfo();

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

The following code sample changes the credentials used 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 ADS path to the managed domain
$managedDomainsPath = $service.Backend.GetConfigurationContainerPath("ManagedDomains")
$managedDomainsPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $managedDomainsPath
$managedDomainPath = $managedDomainsPathObj.CreateChildPath("DC=$domainName")

# Bind to the domain
$managedDomain = $service.OpenObject($managedDomainPath, $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 passowrd = "secret";

        // Connect to the Adaxes service
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");
        
        // Build ADS path to the managed domain
        string managedDomainsPath = service.Backend.GetConfigurationContainerPath(
            "ManagedDomains");
        AdsPath managedDomainsPathObj = new AdsPath(managedDomainsPath);
        AdsPath managedDomainPath = managedDomainsPathObj.CreateChildPath("DC=" + domainName);

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

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 ADS path to the managed domain
$managedDomainsPath = $service.Backend.GetConfigurationContainerPath("ManagedDomains")
$managedDomainsPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $managedDomainsPath
$managedDomainPath = $managedDomainsPathObj.CreateChildPath("DC=$domainName")

# Bind to the domain
$managedDomain = $service.OpenObject($managedDomainPath, $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 ADS path to the managed domain
        string managedDomainsPath = service.Backend.GetConfigurationContainerPath(
            "ManagedDomains");
        AdsPath managedDomainsPathObj = new AdsPath(managedDomainsPath);
        AdsPath managedDomainPath = managedDomainsPathObj.CreateChildPath("DC=" + domainName);

        // Bind to the domain
        IAdmManagedDomain managedDomain = (IAdmManagedDomain)service.OpenObject(
            managedDomainPath.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 to manage the domain, but doesn't have administrator permissions, the method throws the DirectoryComException exception with error code ERROR_NO_SUCH_PRIVILEGE.

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