> For the complete documentation index, see [llms.txt](https://docs.scepman.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scepman.com/pt/gestao-de-certificados/api-certificates/scepmanclient.md).
# SCEPmanClient
SCEPmanClient é um módulo PowerShell destinado a interagir com a API REST do SCEPman. Sendo independente da plataforma e compatível com Windows PowerShell v5, pode usar este módulo para solicitar certificados para todos os casos de utilização para os quais a API REST pode ser usada:
* Emissão automática de certificados de servidor
* Certificados de cliente para dispositivos não geridos
* Inscrição de certificados em dispositivos Linux
## Instalação
O módulo SCEPmanClient está disponível na Galeria do PowerShell e pode ser instalado usando o seguinte comando:
```powershell
Install-Module -Name SCEPmanClient
```
{% hint style="info" %}
Siga o guia da Microsoft sobre como instalar o PowerShell em [Linux](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux?view=powershell-7.5) ou [macOS](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-macos?view=powershell-7.5).
{% endhint %}
## Pré-requisitos
Para que o módulo funcione como esperado, terá de adicionar uma pequena modificação à sua implementação do SCEPman:
{% stepper %}
{% step %}
### Adicionar URL da página inicial
Adicione o URL do App Service do SCEPman: Navegue até à `Branding & Properties` secção do registo da aplicação. Adicione o URL do App Service do SCEPman ao campo URL da página inicial:
Isto é necessário para que o módulo consiga procurar automaticamente o id de cliente dos registos da aplicação, necessário para a obtenção do token de acesso.
{% endstep %}
{% step %}
### Permitir que o Azure PowerShell interaja com o registo da aplicação
No registo da aplicação, navegue até *Expor uma API* e crie um escopo personalizado que possa ser usado para autorizar o id do cliente `1950a258-227b-4e31-a9cf-717495945fc2` (Microsoft Azure PowerShell)
Informações de exemplo para um escopo de API personalizado
Depois de criar um escopo de API, a aplicação Azure PowerShell pode ser autorizada:
Aplicação Microsoft Azure PowerShell autorizada
{% endstep %}
{% step %}
### Ativar o endpoint EST
#### Configuração
*Necessário para renovação de certificado*
Configure o seu SCEPman App Service para aceitar certificados de cliente mTLS. No painel Configuration da seção Settings, verifique se o Client certificate mode em Incoming client certificates está definido como ***Utilizador interativo opcional***.
Não defina o Client certificate mode como Require ou Allow, pois isso quebraria o funcionamento normal do SCEPman nos endpoints SCEP!
#### Variáveis de ambiente
Para usar este cenário, você deve definir as seguintes Variáveis de Ambiente no serviço de aplicativo SCEPman.
#### [AppConfig:DbCSRValidation:Enabled](https://docs.scepman.com/advanced-configuration/application-settings/dbcsr-validation#appconfig-dbcsrvalidation-enabled)
*Necessário para inscrição e renovação de certificado*
Defina esta variável como ***true*** para ativar a validação de solicitações de assinatura de certificado (CSRs).
#### [AppConfig:DbCSRValidation:AllowRenewals](https://docs.scepman.com/advanced-configuration/application-settings/dbcsr-validation#appconfig-dbcsrvalidation-allowrenewals)
*Necessário para renovação de certificado*
Defina esta variável como ***true*** para ativar renovações de certificado.
#### [AppConfig:DbCSRValidation:ReenrollmentAllowedCertificateTypes](https://docs.scepman.com/advanced-configuration/application-settings/dbcsr-validation#appconfig-dbcsrvalidation-reenrollmentallowedcertificatetypes)
*Necessário para renovação de certificado*
Defina esta variável como uma lista separada por vírgulas de tipos de certificado para os quais você deseja permitir a renovação. Consulte a documentação da variável vinculada para ver uma lista de tipos de certificado possíveis.
Exemplo: ***Static,IntuneUser,IntuneDevice***
{% endstep %}
{% endstepper %}
## Permissões
O SCEPman tem diferentes funções que permitirão a inscrição de diferentes tipos de certificados. Pode atribuí-las na *SCEPman-api* Enterprise Application (nome predefinido):
#### CSR DB Requesters
Esta função só é atribuível a Service Principals (por exemplo, registos de aplicação) por predefinição e permite solicitar certificados com assuntos e utilizações arbitrários.
{% content-ref url="/pages/d93fe80282e16b063db56892eb639ba9ec09c676" %}
[Registo por API](/pt/gestao-de-certificados/api-certificates/api-enrollment.md)
{% endcontent-ref %}
#### CSR Self Service
Esta função pode ser atribuída a utilizadores e permitirá a inscrição de certificados com as seguintes restrições:
* Apenas EKU ClientAuth
* Os certificados de utilizador precisam de corresponder ao UPN do utilizador no assunto ou no nome alternativo de assunto UPN
* Os certificados de dispositivo precisam de ter um assunto ou SAN que o SCEPman possa mapear para um objeto de dispositivo pertencente ao utilizador autenticado
{% content-ref url="/pages/1e799ec75d1cb56025eee9c110760d8b59cd3666" %}
[Registo de autosserviço](/pt/gestao-de-certificados/api-certificates/self-service-enrollment.md)
{% endcontent-ref %}
## Exemplos de utilização
### Usar autenticação do Azure
#### Autenticação interativa
Ao solicitar um novo certificado sem especificar o mecanismo de autenticação, o utilizador será autenticado interativamente por predefinição. Ao usar o `-SubjectFromUserContext` parâmetro, o assunto e o SAN UPN do certificado serão preenchidos automaticamente com base no contexto do utilizador com sessão iniciada:
```powershell
New-SCEPmanCertificate -Url 'scepman.contoso.com' -SubjectFromUserContext -SaveToStore CurrentUser
```
#### Início de sessão do dispositivo
Se quiser solicitar um novo certificado num sistema sem qualquer ambiente de trabalho, pode usar o `-DeviceCode` parâmetro para realizar a autenticação efetiva noutra sessão:
```powershell
New-SCEPmanCertificate -Url 'scepman.contoso.com' -DeviceCode -SubjectFromUserContext -SaveToFolder /home/user/certificates
```
#### Autenticação por Service Principal
Em cenários totalmente automatizados, pode ser usado um registo de aplicação para autenticação. Neste caso, não será possível inferir o assunto a partir do contexto autenticado.
A técnica de splatting de parâmetros também tornará a execução mais legível:
```powershell
$Parameters = @{
'Url' = 'scepman.contoso.com'
'ClientId' = '569fbf51-aa63-4b5c-8b26-ebbcfcde2715'
'TenantId' = '8aa3123d-e76c-42e2-ba3c-190cabbec531'
'ClientSecret' = 'csa8Q~aVaWCLZTzswIBGvhxUiEvhptuqEyJugb70'
'Subject' = 'CN=WebServer'
'DNSName' = 'Webserver.domain.local'
'ExtendedKeyUsage' = 'ServerAuth'
'SaveToStore' = 'LocalMachine'
}
New-SCEPmanCertificate @Parameters
```
### Autenticar usando certificados
Uma vez que um certificado tenha sido emitido usando um contexto autenticado, podemos usá-lo para o renovar sem fornecer novamente qualquer contexto.
#### CertificateBySubject
*A interação com armazenamentos de chaves só é possível no Windows*
Ao fornecer o `CertificateBySubject` parâmetro, o módulo tentará automaticamente encontrar um certificado adequado para renovação nos armazenamentos de chaves *CurrentUser* e *LocalMachine* .
O valor introduzido será correspondido por regex com os assuntos em todos os certificados disponíveis.
```powershell
New-SCEPmanCertificate -CertificateBySubject 'WebServer' -SaveToStore 'LocalMachine'
```
#### Fornecer um certificado específico
```powershell
$Certificate = Get-ChildItem Cert:\LocalMachine\My | Where-Object Thumbprint -eq '9B08EA68B16773CEF3C49D5D95BE50B784638984'
New-SCEPmanCertificate -Certificate $Certificate -SaveToStore LocalMachine
```
#### CertificateFromFile
Em sistemas Linux, a renovação de um certificado pode ser efetuada passando os caminhos de um certificado existente e da respetiva chave privada.
```powershell
New-SCEPmanCertificate -CertificateFromFile '~/certs/myCert.pem' -KeyFromFile '~/certs/myKey.key' -SaveToFolder '~/certs'
```
Ao usar uma chave privada encriptada, ser-lhe-á pedido a palavra-passe. Também pode passar diretamente a palavra-passe da chave usando o `PlainTextPassword` parâmetro.
#### Uso do SCEPman com uma Firewall de Aplicações Web do Azure
Com os Perfis SSL ativados, a WAF terminará as ligações TLS. Isto, por sua vez, irá quebrar as renovações de certificados usando EST, uma vez que o procedimento depende de mTLS para autenticação. Neste caso, o `UseSCEPRenewal` parâmetro pode ser usado para, em vez disso, efetuar uma renovação de certificado em conformidade com o protocolo SCEP.
```powershell
New-SCEPmanCertificate -CertificateBySubject 'WebServer' -SaveToStore 'LocalMachine' -UseSCEPRenewal
```
Note que isto requer configuração adicional do SCEPman relativamente ao endpoint SCEP estático:
* AppConfig:StaticValidation:Enabled : true
* AppConfig:StaticValidation:AllowRenewals : true
* AppConfig:StaticValidation:ReenrollmentAllowedCertificateTypes: Static (Dependendo dos tipos previstos para renovação)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.scepman.com/pt/gestao-de-certificados/api-certificates/scepmanclient.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
