Adicionar # Manual de Uso: Script de Provisionamento de Usuários (cria-usuario-unico.ps1)
commit
b82f94a105
179
%23 Manual de Uso%3A Script de Provisionamento de Usu%C3%A1rios %28cria-usuario-unico.ps1%29.-.md
Normal file
179
%23 Manual de Uso%3A Script de Provisionamento de Usu%C3%A1rios %28cria-usuario-unico.ps1%29.-.md
Normal file
|
|
@ -0,0 +1,179 @@
|
||||||
|
## 1. Visão Geral
|
||||||
|
|
||||||
|
Este script é um componente central do **Módulo 2: Portal do Gestor** do projeto "Plataforma Unificada de Trabalho Digital". Sua principal função é automatizar o processo de criação de novos usuários de forma padronizada e segura, interagindo com dois ambientes Active Directory distintos: o AD principal (cliente) e o AD do servidor de e-mails (Exchange).
|
||||||
|
|
||||||
|
O script foi projetado para ser executado sem interação manual e oferece as seguintes funcionalidades:
|
||||||
|
- **Criação de usuário único** através de parâmetros diretos.
|
||||||
|
- **Criação de usuários em massa** via importação de arquivo `.csv`.
|
||||||
|
- **Validações robustas** para garantir a integridade dos dados antes da criação (unicidade de login, UPN válido, OU existente, etc.).
|
||||||
|
- **Geração de senha temporária** segura.
|
||||||
|
- **Logging detalhado** de todas as ações, sucessos e falhas em um arquivo de texto local.
|
||||||
|
|
||||||
|
## 2. Pré-requisitos
|
||||||
|
|
||||||
|
Antes de executar o script, garanta que o ambiente atende aos seguintes requisitos:
|
||||||
|
|
||||||
|
* **PowerShell 5.1 ou superior.**
|
||||||
|
* **Módulos do PowerShell:**
|
||||||
|
* `ActiveDirectory`: Deve estar instalado na máquina que executará o script (parte das Ferramentas de Administração de Servidor Remoto - RSAT).
|
||||||
|
* **Ferramentas de Gerenciamento do Exchange:** Necessárias para o cmdlet `Enable-Mailbox`.
|
||||||
|
* **Permissões:** A conta de serviço utilizada para executar o script (fornecida via `Get-Credential`) precisa de permissões no Active Directory para:
|
||||||
|
* Ler as propriedades da floresta (`Get-ADForest`).
|
||||||
|
* Criar e modificar objetos de usuário nas OUs de destino.
|
||||||
|
* Habilitar caixas de correio no Exchange.
|
||||||
|
* **PowerShell Remoting (WinRM):** Deve estar habilitado nos Domain Controllers para que o logging remoto no Windows Event Log funcione corretamente.
|
||||||
|
|
||||||
|
## 3. Estrutura do Arquivo CSV
|
||||||
|
|
||||||
|
Para a criação em massa, é necessário um arquivo `.csv` com uma estrutura específica. A primeira linha do arquivo **deve** ser o cabeçalho.
|
||||||
|
|
||||||
|
### 3.1. Atributos Obrigatórios
|
||||||
|
|
||||||
|
Estes campos são exigidos pelo script e devem estar presentes no cabeçalho do CSV para cada usuário.
|
||||||
|
|
||||||
|
| Cabeçalho | Descrição | Exemplo |
|
||||||
|
| ----------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
|
||||||
|
| `SamAccountName` | O nome de logon do usuário (curto, pré-Windows 2000). Máximo de 20 caracteres. | `joao.silva` |
|
||||||
|
| `GivenName` | O primeiro nome do usuário. | `João` |
|
||||||
|
| `Surname` | O sobrenome do usuário. | `Silva` |
|
||||||
|
| `Name` | O nome completo de exibição do usuário. | `"João da Silva"` |
|
||||||
|
| `UserPrincipalName` | O logon principal do usuário, que deve ser idêntico ao e-mail. | `joao.silva@empresa.com.br` |
|
||||||
|
| `Path` | O *Distinguished Name* (DN) completo da Unidade Organizacional (OU) onde a conta será criada. | `"OU=Funcionarios,OU=EmpresaX,DC=exch,DC=local"` |
|
||||||
|
|
||||||
|
### 3.2. Atributos Opcionais (Variações)
|
||||||
|
|
||||||
|
O script pode ser facilmente estendido para incluir mais atributos do Active Directory. Campos como Departamento, Cargo e Gestor são altamente recomendados para enriquecer os dados e facilitar outras automações, conforme o dossiê do projeto.
|
||||||
|
|
||||||
|
| Cabeçalho | Atributo AD | Descrição | Exemplo |
|
||||||
|
| -------------- | ------------- | --------------------------------------------------------------------------------- | ------------------------------- |
|
||||||
|
| `Department` | `department` | O departamento do usuário (ex: "TI", "Financeiro"). | `Financeiro` |
|
||||||
|
| `Title` | `title` | O cargo do usuário (ex: "Analista de Sistemas"). | `Analista Financeiro` |
|
||||||
|
| `Manager` | `manager` | O `SamAccountName` do gestor direto do usuário. O script irá procurar o DN dele. | `gestor.area` |
|
||||||
|
| `EmployeeID` | `employeeID` | O número de matrícula ou ID único do colaborador, vindo do sistema de RH. | `95481` |
|
||||||
|
|
||||||
|
> **IMPORTANTE:** Para que o script processe esses atributos opcionais, uma pequena modificação é necessária. Veja a seção "Estendendo o Script".
|
||||||
|
|
||||||
|
### 3.3. Arquivo de Exemplo: `importacao_usuarios.csv`
|
||||||
|
|
||||||
|
Este arquivo de exemplo demonstra o uso de atributos obrigatórios e opcionais. Note que alguns usuários não possuem todos os dados opcionais, e o script saberá lidar com isso.
|
||||||
|
|
||||||
|
```csv
|
||||||
|
SamAccountName,GivenName,Surname,Name,UserPrincipalName,Path,Department,Title,Manager,EmployeeID
|
||||||
|
ana.silva,Ana,Silva,"Ana Silva","ana.silva@grupopralog.com.br","OU=Usuarios,OU=GrupoPralog,DC=exch,DC=local",Financeiro,"Analista Financeiro","joana.gestora","10234"
|
||||||
|
bruno.costa,Bruno,Costa,"Bruno Costa","bruno.costa@enseg.com.br","OU=Usuarios,OU=Enseg,DC=exch,DC=local",Operacional,"Técnico de Segurança","","10235"
|
||||||
|
carla.souza,Carla,Souza,"Carla de Souza","carla.souza@grupopralog.com.br","OU=Vendas,OU=GrupoPralog,DC=exch,DC=local",Comercial,Vendedora,"felipe.lider","10236"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. Como Usar
|
||||||
|
|
||||||
|
### 4.1. Criação de Usuário Único
|
||||||
|
|
||||||
|
Útil para testes ou para ser chamado por uma API.
|
||||||
|
|
||||||
|
1. **Prepare as credenciais:**
|
||||||
|
```powershell
|
||||||
|
$clientCred = Get-Credential
|
||||||
|
$exchangeCred = Get-Credential
|
||||||
|
```
|
||||||
|
2. **Execute o script com todos os parâmetros:**
|
||||||
|
```powershell
|
||||||
|
.\New-UnifiedADUser.ps1 -SamAccountName 'teste.user' -GivenName 'Usuario' -Surname 'Teste' -Name "Usuario Teste" -UserPrincipalName 'teste.user@itguys.com.br' -Path "OU=Usuarios,DC=exch,DC=local" -ClientADServer "192.168.1.10" -ClientADCredential $clientCred -ExchangeADServer "192.168.10.20" -ExchangeADCredential $exchangeCred
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2. Criação em Massa via CSV
|
||||||
|
|
||||||
|
O método principal para provisionamento de múltiplos colaboradores.
|
||||||
|
|
||||||
|
1. **Prepare as credenciais:**
|
||||||
|
```powershell
|
||||||
|
$clientCred = Get-Credential
|
||||||
|
$exchangeCred = Get-Credential
|
||||||
|
```
|
||||||
|
2. **Execute o script com o parâmetro `-CsvPath`:**
|
||||||
|
```powershell
|
||||||
|
.\New-UnifiedADUser.ps1 -CsvPath "C:\caminho\para\importacao_usuarios.csv" -ClientADServer "192.168.1.10" -ClientADCredential $clientCred -ExchangeADServer "192.168.10.20" -ExchangeADCredential $exchangeCred
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. Logs e Tratamento de Erros
|
||||||
|
|
||||||
|
O script gera um arquivo de log diário chamado `New-UnifiedADUser-Log-AAAA-MM-DD.txt` no mesmo diretório onde é executado.
|
||||||
|
|
||||||
|
- **Sucesso:** Cada etapa bem-sucedida é registrada com o nível `[INFO]`.
|
||||||
|
- **Falha:** Qualquer falha de validação ou de criação é registrada com o nível `[ERROR]`, incluindo uma mensagem detalhada do motivo.
|
||||||
|
|
||||||
|
Ao importar um CSV, se uma linha falhar na validação, o erro será logado, e o script continuará para a próxima linha, garantindo que o processo não seja interrompido por um único registro inválido.
|
||||||
|
|
||||||
|
## 6. Estendendo o Script para Atributos Opcionais
|
||||||
|
|
||||||
|
Para que o script utilize os atributos opcionais do CSV (Department, Title, Manager, etc.), adicione os seguintes trechos no arquivo `New-UnifiedADUser.ps1`:
|
||||||
|
|
||||||
|
1. **Na seção `param(...)`**, adicione os parâmetros para o modo de usuário único:
|
||||||
|
```powershell
|
||||||
|
# ... após o parâmetro -Path
|
||||||
|
[Parameter(Mandatory = $false, ParameterSetName = 'SingleUser')]
|
||||||
|
[string]$Department,
|
||||||
|
|
||||||
|
[Parameter(Mandatory = $false, ParameterSetName = 'SingleUser')]
|
||||||
|
[string]$Title,
|
||||||
|
|
||||||
|
[Parameter(Mandatory = $false, ParameterSetName = 'SingleUser')]
|
||||||
|
[string]$Manager,
|
||||||
|
|
||||||
|
[Parameter(Mandatory = $false, ParameterSetName = 'SingleUser')]
|
||||||
|
[string]$EmployeeID,
|
||||||
|
# ... antes do parâmetro -CsvPath
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Na seção `switch ($PSCmdlet.ParameterSetName)`**, no bloco `'SingleUser'`, adicione os novos campos ao objeto:
|
||||||
|
```powershell
|
||||||
|
# ...
|
||||||
|
'SingleUser' {
|
||||||
|
$usersToProcess += [PSCustomObject]@{
|
||||||
|
SamAccountName = $SamAccountName
|
||||||
|
GivenName = $GivenName
|
||||||
|
# ...
|
||||||
|
Path = $Path
|
||||||
|
Department = $Department # NOVO
|
||||||
|
Title = $Title # NOVO
|
||||||
|
Manager = $Manager # NOVO
|
||||||
|
EmployeeID = $EmployeeID # NOVO
|
||||||
|
}
|
||||||
|
break
|
||||||
|
}
|
||||||
|
# ...
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Dentro do bloco `try { ... }` da criação do usuário**, modifique a `$userParams` para incluir os novos atributos de forma condicional:
|
||||||
|
```powershell
|
||||||
|
# ... dentro do bloco try, após a definição de $securePassword
|
||||||
|
$userParams = @{
|
||||||
|
SamAccountName = $u_sam
|
||||||
|
# ... outros parâmetros ...
|
||||||
|
ChangePasswordAtLogon = $true
|
||||||
|
# Remova Server e Credential daqui
|
||||||
|
}
|
||||||
|
|
||||||
|
# Adicione os parâmetros de conexão
|
||||||
|
$userParams.Add('Server', $ClientADServer)
|
||||||
|
$userParams.Add('Credential', $ClientADCredential)
|
||||||
|
|
||||||
|
# Adiciona os atributos opcionais SOMENTE se eles existirem no CSV/parâmetros
|
||||||
|
if (-not [string]::IsNullOrWhiteSpace($user.Department)) { $userParams.Add('Department', $user.Department) }
|
||||||
|
if (-not [string]::IsNullOrWhiteSpace($user.Title)) { $userParams.Add('Title', $user.Title) }
|
||||||
|
if (-not [string]::IsNullOrWhiteSpace($user.EmployeeID)) { $userParams.Add('EmployeeID', $user.EmployeeID) }
|
||||||
|
if (-not [string]::IsNullOrWhiteSpace($user.Manager)) {
|
||||||
|
$managerUser = Get-ADUser -Filter "SamAccountName -eq '$($user.Manager)'" -Server $ClientADServer -Credential $ClientADCredential
|
||||||
|
if ($managerUser) {
|
||||||
|
$userParams.Add('Manager', $managerUser.DistinguishedName)
|
||||||
|
} else {
|
||||||
|
Write-Log -Level 'WARN' -Message "Gestor '$($user.Manager)' não encontrado para o usuário '$u_sam'. O campo não será preenchido."
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Write-Log -Level 'INFO' -Message "Tentando criar a conta '$u_sam'..." -TargetADServer $ClientADServer
|
||||||
|
|
||||||
|
# Use splatting para passar os parâmetros
|
||||||
|
New-ADUser @userParams -ErrorAction Stop
|
||||||
|
# ... resto do script
|
||||||
|
```
|
||||||
|
Com essas alterações, o script se torna ainda mais poderoso e alinhado com as necessidades de automação do seu projeto.
|
||||||
Loading…
Reference in New Issue