joao.goncalves
/
automacao-identidade-ad
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Atualizar # Manual de Uso: Script de Provisionamento de Usuários (cria-usuario-unico.ps1)

João Pedro Toledo Goncalves 2025-10-15 13:04:04 +00:00
parent b82f94a105
commit 26ca4a55f9
1 changed files with 67 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

181
%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.
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.