Função NetProvisionComputerAccount (lmjoin.h)
A função NetProvisionComputerAccount provisiona uma conta de computador para uso posterior em uma operação de junção de domínio offline.
Sintaxe
NET_API_STATUS NET_API_FUNCTION NetProvisionComputerAccount(
[in] LPCWSTR lpDomain,
[in] LPCWSTR lpMachineName,
[in, optional] LPCWSTR lpMachineAccountOU,
[in, optional] LPCWSTR lpDcName,
[in] DWORD dwOptions,
[out, optional] PBYTE *pProvisionBinData,
[out, optional] DWORD *pdwProvisionBinDataSize,
[out, optional] LPWSTR *pProvisionTextData
);
Parâmetros
[in] lpDomain
Um ponteiro para uma cadeia de caracteres terminada em NULL que especifica o nome do domínio em que a conta do computador é criada.
[in] lpMachineName
Um ponteiro para uma cadeia de caracteres terminada em NULL que especifica o nome curto do computador do qual o atributo da conta de computador sAMAccountName é derivado acrescentando um '$'. Esse parâmetro deve conter um nome de computador DNS ou NetBIOS válido.
[in, optional] lpMachineAccountOU
Um ponteiro opcional para uma cadeia de caracteres terminada em NULL que contém o nome do formato RFC 1779 da UO (unidade organizacional) em que a conta de computador será criada. Se você especificar esse parâmetro, a cadeia de caracteres deverá conter um caminho completo, por exemplo, OU=testOU,DC=domain,DC=Domain,DC=com. Caso contrário, esse parâmetro deve ser NULL.
Se esse parâmetro for NULL, o contêiner de objeto de computador conhecido será usado conforme publicado no domínio.
[in, optional] lpDcName
Um ponteiro opcional para uma cadeia de caracteres terminada em NULL que contém o nome do controlador de domínio a ser direcionado.
[in] dwOptions
Um conjunto de sinalizadores de bits que definem opções de provisionamento. Esse parâmetro pode ser um ou mais dos seguintes valores definidos no arquivo de cabeçalho Lmjoin.h .
| Valor | Significado |
|---|---|
|
Se o chamador exigir a criação da conta por privilégio, essa opção causará uma nova tentativa de falha usando funções de criação de conta, permitindo a interoperabilidade com controladores de domínio em execução em versões anteriores do Windows.
Não há suporte para lpMachineAccountOU ao usar o suporte a privilégios de nível inferior. |
|
Se a conta nomeada já existir, será feita uma tentativa de reutilizar a conta existente.
Essa opção requer credenciais suficientes para essa operação (Administrador de Domínio ou o proprietário do objeto). |
|
Use a senha da conta de computador padrão, que é o nome do computador em letras minúsculas. Isso é em grande parte para dar suporte ao modelo de junção não seguro mais antigo em que a conta pré-criada normalmente usava essa senha padrão.
Nota Os aplicativos devem evitar usar essa opção, se possível. Essa opção, bem como a função NetJoinDomain com dwOptions definidas como NETSETUP_JOIN_UNSECURE para junção não seguro, só devem ser usadas em versões anteriores do Windows.
|
|
Não tente localizar a conta em nenhum controlador de domínio no domínio. Essa opção torna a operação mais rápida, mas só deve ser usada quando o chamador tiver certeza de que uma conta com o mesmo nome não foi criada recentemente.
Essa opção só é válida quando o parâmetro lpDcName é especificado. Quando os pré-requisitos são atendidos, essa opção permite provisionamento mais rápido útil para cenários como processamento em lote. |
|
Essa opção recupera todos os certificados raiz da Autoridade de Certificação no computador local e os adiciona ao pacote de provisionamento quando nenhum nome de modelo de certificado é fornecido como parte do pacote de provisionamento (o membro aCertTemplateNames do struct NETSETUP_PROVISIONING_PARAMS passado no parâmetro pProvisioningParams para a função NetCreateProvisioningPackage é NULL).
Nota Esse sinalizador só tem suporte na função NetCreateProvisioningPackage em Windows 8, Windows Server 2012 e posterior.
|
[out, optional] pProvisionBinData
Um ponteiro opcional que receberá o blob binário opaco de metadados serializados exigido pela função NetRequestOfflineDomainJoin para concluir uma junção de domínio offline, se a função NetProvisionComputerAccount for concluída com êxito. Os dados são retornados como um buffer binário opaco que pode ser passado para a função NetRequestOfflineDomainJoin .
Se esse parâmetro for NULL, o parâmetro pProvisionTextData não deverá ser NULL. Se esse parâmetro não for NULL, o parâmetro pProvisionTextData deverá ser NULL.
[out, optional] pdwProvisionBinDataSize
Um ponteiro para um valor que recebe o tamanho, em bytes, do buffer retornado no parâmetro pProvisionBinData .
Esse parâmetro não deverá ser NULL se o parâmetro pProvisionBinData não for NULL. Esse parâmetro deve ser NULL quando o parâmetro pProvisionBinData for NULL.
[out, optional] pProvisionTextData
Um ponteiro opcional que receberá o blob binário opaco de metadados serializados exigido pela função NetRequestOfflineDomainJoin para concluir uma junção de domínio offline, se a função NetProvisionComputerAccount for concluída com êxito. Os dados são retornados no formulário de cadeia de caracteres para inserção em um arquivo de resposta de instalação autônoma.
Se esse parâmetro for NULL, o parâmetro pProvisionBinData não deverá ser NULL. Se esse parâmetro não for NULL, o parâmetro pProvisionBinData deverá ser NULL.
Retornar valor
Se a função for bem-sucedida, o valor retornado será NERR_Success.
Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de erro ou um dos códigos de erro do sistema.
| Código de retorno | Descrição |
|---|---|
|
Acesso negado. Esse erro será retornado se o chamador não tiver privilégios suficientes para concluir a operação. |
|
Esta operação só é permitida para o Controlador de Domínio Primário do domínio. Esse erro será retornado se um nome de controlador de domínio tiver sido especificado no parâmetro lpDcName , mas o computador especificado não puder ser validado como um controlador de domínio para o domínio de destino especificado no parâmetro lpDomain . |
|
Um parâmetro está incorreto. Esse erro será retornado se o parâmetro lpDomain ou lpMachineName for NULL. Esse erro também será retornado se os parâmetros pProvisionBinData e pProvisionTextData forem NULL. |
|
O domínio especificado não existia. |
|
A solicitação não terá suporte. Esse erro será retornado se o parâmetro lpMachineAccountOU tiver sido especificado e o controlador de domínio estiver em execução em versões anteriores do Windows que não dão suporte a esse parâmetro. |
|
O controlador de domínio especificado não atende ao requisito de versão para essa operação. |
|
Essa operação requer um controlador de domínio que dê suporte a LDAP. |
|
A conta já existe no domínio e o bit NETSETUP_PROVISION_REUSE_ACCOUNT não foi especificado no parâmetro dwOptions . |
|
O serviço estação de trabalho não foi iniciado. |
|
Uma chamada de procedimento remoto já está em andamento para esse thread. |
|
Não há suporte para a sequência de protocolo de chamada de procedimento remoto. |
Comentários
A função NetProvisionComputerAccount tem suporte no Windows 7 e no Windows Server 2008 R2 para operações de junção offline. No Windows 8 ou no Windows Server 2008 R2, é recomendável que a função NetCreateProvisioningPackage seja usada em vez da função NetProvisionComputerAccount.
A função NetProvisionComputerAccount é usada para provisionar uma conta de computador para uso posterior em uma operação de junção de domínio offline usando a função NetRequestOfflineDomainJoin . O cenário de junção de domínio offline usa essas funções da seguinte maneira:
- NetProvisionComputerAccount é uma função de provisionamento que é chamada pela primeira vez para executar as operações de rede necessárias para criar e configurar o objeto de computador no Active Directory. A saída do NetProvisionComputerAccount é um blob binário opaco de metadados serializados usado para a próxima etapa.
- NetRequestOfflineDomainJoin, uma função de inicialização de imagem, é chamada para injetar a saída da função de provisionamento NetProvisionComputerAccount em uma imagem do sistema operacional Windows a ser usada durante a instalação.
A função NetProvisionComputerAccount criará ou reutilizará a conta do computador no domínio, coletará todos os metadados necessários e a retornará em um blob binário com versão opaca ou como texto para inserção em um arquivo de resposta de instalação autônoma. O blob binário opaco pode ser consumido pela operação de solicitação de junção de domínio offline que fornece toda a entrada necessária para concluir a junção de domínio durante a primeira inicialização sem nenhuma operação de rede (somente atualizações de estado local).
Observação de segurança: O blob retornado pela função NetProvisionComputerAccount contém dados muito confidenciais. Ela deve ser tratada com segurança como uma senha de texto sem formatação. O blob contém a senha da conta do computador e outras informações sobre o domínio, incluindo o nome de domínio, o nome de um controlador de domínio e a SID (ID de segurança) do domínio. Se o blob estiver sendo transportado fisicamente ou pela rede, deve-se tomar cuidado para transportá-lo com segurança. O design não faz nenhuma provisão para proteger esses dados. Esse problema existe hoje com arquivos de resposta de instalação autônoma que podem conter vários segredos, incluindo senhas de usuário de domínio. O chamador deve proteger o blob e os arquivos de instalação autônoma. As soluções para esse problema são variadas. Por exemplo, uma chave pré-trocada pode ser usada para criptografar uma sessão entre o consumidor e a entidade de provisionamento, permitindo uma transferência segura do blob opaco.
O blob opaco retornado no parâmetro pProvisionBinData pela função NetProvisionComputerAccount tem controle de versão para permitir cenários de interoperabilidade e de serviço entre diferentes versões do Windows (cliente de junção, computador de provisionamento e controlador de domínio). O cenário de junção offline atualmente não limita o tempo de vida do blob retornado pela função NetProvisionComputerAccount .
Para junções de domínio offline, o acesso marcar executado depende da configuração do domínio. A criação de conta de computador está habilitada usando três métodos:
- Os administradores de domínio têm direitos para criar contas de computador.
- O SD em um contêiner pode delegar os direitos para criar contas de computador.
- Por padrão, os usuários autenticados podem criar contas de computador por privilégio. Os usuários autenticados estão limitados à criação de um número limitado de contas especificadas como uma cota no domínio (o valor padrão é 10). Para obter mais informações, consulte o atributo ms-DS-MachineAccountQuota no esquema do Active Directory.
A função NetProvisionComputerAccount funciona apenas com um controlador de domínio gravável e não funciona em um controlador de domínio somente leitura. Depois que o provisionamento é feito em um controlador de domínio gravável e a conta é replicada para um controlador de domínio somente leitura, as outras partes da operação de ingresso no domínio offline não exigem acesso a um controlador de domínio.
Se a função NetProvisionComputerAccount for bem-sucedida, o ponteiro no parâmetro pProvisionBinData ou pProvisionTextData (dependendo de qual parâmetro não era NULL) será retornado com os dados serializados para uso em uma operação de junção offline ou como texto em um arquivo de instalação autônoma.
Para obter mais informações sobre operações de ingresso no domínio offline, consulte o Guia passo a passo de ingresso no domínio offline.
A junção (e desassociamento) de um computador a um domínio usando NetJoinDomain e NetUnjoinDomain só pode ser executada por um membro do grupo local Administradores no computador de destino. Observe que o administrador de domínio pode definir requisitos adicionais para ingressar no domínio usando delegação e atribuição de privilégios.
Requisitos
| Cliente mínimo com suporte | Windows 7 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 R2 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | lmjoin.h (inclua Lm.h) |
| Biblioteca | Netapi32.lib |
| DLL | Netapi32.dll |
Confira também
Funções de gerenciamento de rede
Visão geral do gerenciamento de rede