commit b82f94a105562ec7d52b08031b9da3801bcc39f7 Author: João Pedro Toledo Goncalves Date: Wed Oct 15 00:52:07 2025 +0000 Adicionar # Manual de Uso: Script de Provisionamento de Usuários (cria-usuario-unico.ps1) diff --git a/%23 Manual de Uso%3A Script de Provisionamento de Usu%C3%A1rios %28cria-usuario-unico.ps1%29.-.md b/%23 Manual de Uso%3A Script de Provisionamento de Usu%C3%A1rios %28cria-usuario-unico.ps1%29.-.md new file mode 100644 index 0000000..815269f --- /dev/null +++ b/%23 Manual de Uso%3A Script de Provisionamento de Usu%C3%A1rios %28cria-usuario-unico.ps1%29.-.md @@ -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. \ No newline at end of file