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 index 815269f..0573d6e 100644 --- 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 @@ -1,13 +1,13 @@ ## 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). +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, completa 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. +- **Suporte a mais de 25 atributos** do Active Directory, cobrindo identidade, contato, organização e perfil. +- **Criação de usuário único** através de parâmetros diretos ou **criação em massa** via importação de arquivo `.csv`. +- **Validações robustas e sequenciais** para garantir a integridade dos dados antes da criação (parâmetros de conexão, campos críticos, unicidade de login/UPN, OU existente, etc.). +- **Geração de senha temporária** segura para o novo usuário. +- **Logging detalhado** de todas as ações, sucessos e falhas em um arquivo de texto local para fins de auditoria. ## 2. Pré-requisitos @@ -25,65 +25,88 @@ Antes de executar o script, garanta que o ambiente atende aos seguintes requisit ## 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. +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. O script é flexível: se uma coluna opcional não existir no seu CSV, ela será simplesmente ignorada. -### 3.1. Atributos Obrigatórios +### 3.1. Atributos Críticos Obrigatórios -Estes campos são exigidos pelo script e devem estar presentes no cabeçalho do CSV para cada usuário. +Estes campos são exigidos pelo script para cada usuário. Se alguma dessas colunas estiver vazia em uma linha do CSV, essa linha será ignorada e um erro será registrado no log. | Cabeçalho | Descrição | Exemplo | | ----------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -| `SamAccountName` | O nome de logon do usuário (curto, pré-Windows 2000). Máximo de 20 caracteres. | `joao.silva` | +| `SamAccountName` | O nome de logon do usuário (curto, pré-Windows 2000). **Único na floresta.** | `joao.silva` | +| `UserPrincipalName` | O logon principal do usuário (e-mail). **Único na floresta.** | `joao.silva@empresa.com.br` | | `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"` | +| `Path` | O *Distinguished Name* (DN) completo da OU onde a conta será criada. | `"OU=Funcionarios,OU=EmpresaX,DC=exch,DC=local"` | -### 3.2. Atributos Opcionais (Variações) +### 3.2. Atributos Opcionais Suportados -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. +As colunas a seguir são opcionais. Se a coluna não existir ou o valor estiver em branco, o script simplesmente não preencherá o campo correspondente no Active Directory. -| 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` | +#### Organização +| Cabeçalho | Descrição | Exemplo | +| ---------------- | --------------------------------------------------------------------------------- | ------------------------------- | +| `Title` | O cargo do usuário (ex: "Analista de Sistemas"). | `Analista Financeiro` | +| `Department` | O departamento do usuário (ex: "TI", "Financeiro"). | `Financeiro` | +| `Company` | O nome da empresa do usuário. | `Grupo Pralog` | +| `Manager` | O `SamAccountName` do gestor direto do usuário. O script irá procurar o DN dele. | `gestor.area` | +| `EmployeeID` | O número de matrícula (ID) único do colaborador, vindo do sistema de RH. | `95481` | +| `EmployeeNumber` | O número funcional do colaborador. | `A-95481` | -> **IMPORTANTE:** Para que o script processe esses atributos opcionais, uma pequena modificação é necessária. Veja a seção "Estendendo o Script". +#### Contato e Endereço +| Cabeçalho | Descrição | Exemplo | +| ----------------- | ------------------------------------------ | ----------------------- | +| `OfficePhone` | O telefone comercial principal. | `+55 21 3344-5566` | +| `MobilePhone` | O telefone celular do usuário. | `+55 21 99999-8888` | +| `EmailAddress` | O endereço de e-mail de resposta principal.| `contato@empresa.com.br`| +| `StreetAddress` | O endereço (rua e número). | `Rua Principal, 123` | +| `City` | A cidade. | `Rio de Janeiro` | +| `State` | O estado ou província. | `RJ` | +| `PostalCode` | O código postal (CEP). | `22000-000` | +| `Country` | O país (código de 2 letras, ex: 'BR'). | `BR` | -### 3.3. Arquivo de Exemplo: `importacao_usuarios.csv` +#### Perfil e Atributos Customizados +| Cabeçalho | Descrição | Exemplo | +| --------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | +| `Description` | Uma breve descrição sobre o usuário ou sua função. | `Analista responsável por contas a pagar.` | +| `Office` | O nome do escritório ou localidade física. | `Matriz RJ` | +| `HomePage` | A URL para a página pessoal ou perfil do LinkedIn do usuário. | `https://linkedin.com/in/joaosilva` | +| `ProxyAddresses` | E-mails secundários (aliases), **separados por ponto-e-vírgula (`;`)**. | `alias1@empresa.com;alias2@empresa.com` | +| `extensionAttribute1` | Atributo personalizado 1 (ex: Centro de Custo). | `FIN-RJ-01` | +| `extensionAttribute2` | Atributo personalizado 2 (ex: ID de Projeto). | `PROJETO-X` | -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. +#### Controle da Conta +| Cabeçalho | Descrição | Exemplo (`True` ou `False`) / Data | +| ----------------------- | ----------------------------------------------------------------------------------- | ---------------------------------- | +| `PasswordNeverExpires` | Se `True`, a senha do usuário nunca expira. | `False` | +| `CannotChangePassword` | Se `True`, impede que o próprio usuário altere sua senha. | `False` | +| `AccountExpirationDate` | Define uma data para a conta ser desativada automaticamente (formato `dd/MM/aaaa`). | `31/12/2025` | + +### 3.3. Arquivo de Exemplo Completo: `importacao_geral.csv` ```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" +SamAccountName,UserPrincipalName,GivenName,Surname,Name,Path,Title,Department,Company,Manager,EmployeeID,EmployeeNumber,OfficePhone,MobilePhone,EmailAddress,StreetAddress,City,State,PostalCode,Country,Description,Office,HomePage,PasswordNeverExpires,CannotChangePassword,AccountExpirationDate,extensionAttribute1,extensionAttribute2,ProxyAddresses +ana.silva,ana.silva@grupopralog.com.br,Ana,Silva,"Ana Clara Silva","OU=Financeiro,OU=GrupoPralog,DC=exch,DC=local",Financeiro,"Analista Financeiro Sênior",Grupo Pralog,gestor.financeiro,10234,A-10234,"+55 21 3344-5566","+55 21 99999-8888",ana.silva@grupopralog.com.br,"Rua Principal, 123","Rio de Janeiro",RJ,"22000-000",BR,"Analista responsável pelas contas a pagar.","Rio de Janeiro","[https://portal.grupopralog.com.br](https://portal.grupopralog.com.br)",False,False,,"FIN-RJ-01","PROJETO-X","financeiro@grupopralog.com.br;contas.pagar@grupopralog.com.br" +bruno.temporario,bruno.temporario@enseg.com.br,Bruno,Costa,"Bruno Costa (Temp)","OU=Temporarios,OU=Enseg,DC=exch,DC=local",Operacional,"Técnico Temporário",Enseg,,T-90876,,,,,,"São Paulo",SP,"01000-000",BR,"Prestador de serviço para o projeto Y.",São Paulo,,False,True,"31/12/2025","OPE-SP-05",,"" ``` ## 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:** +2. **Execute o script com 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 + .\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" -Title "Analista de Testes" -Department "QA" -OfficePhone "+55 11 5555-4444" -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 @@ -91,89 +114,19 @@ O método principal para provisionamento de múltiplos colaboradores. ``` 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 + .\New-UnifiedADUser.ps1 -CsvPath "C:\caminho\para\importacao_geral.csv" -ClientADServer "192.168.1.10" -ClientADCredential $clientCred -ExchangeADServer "192.168.10.20" -ExchangeADCredential $exchangeCred ``` -## 5. Logs e Tratamento de Erros +## 5. Validações, 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. +O script possui múltiplas camadas de validação para garantir a robustez do processo. -- **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. +- **Validação de Conexão:** O script falha imediatamente se os parâmetros de servidor ou credenciais estiverem vazios, evitando a execução parcial. +- **Validação de Dados por Usuário:** Para cada linha do CSV (ou para o usuário único), o script verifica: + - Se todos os **6 campos críticos obrigatórios** estão preenchidos. + - Se o `SamAccountName` e o `UserPrincipalName` propostos **já não existem** no Active Directory. + - Se a `Path` (OU) de destino é válida e existe. + - Se o sufixo do `UserPrincipalName` (domínio) é válido na floresta. +- **Logs:** Todas as operações, sucessos, avisos (como um gestor não encontrado) e erros são gravados em um arquivo de log diário chamado `New-UnifiedADUser-Log-AAAA-MM-DD.txt`. -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 +Se uma linha do CSV falhar em qualquer validação, um erro detalhado é logado, e o script continua para a próxima linha, garantindo que o processo em massa não seja interrompido. \ No newline at end of file