# SCEPmanClient

SCEPmanClient es un módulo de PowerShell diseñado para interactuar con la API REST de SCEPman. Al ser independiente de la plataforma y compatible con Windows PowerShell v5, puedes usar este módulo para solicitar certificados para todos los casos de uso para los que se puede usar la API REST:

* Emisión automática de certificados de servidor
* Certificados de cliente para dispositivos no administrados
* Inscripción de certificados en dispositivos Linux

## Instalación

El módulo SCEPmanClient está disponible en la PowerShell Gallery y se puede instalar usando el siguiente comando:

```powershell
Install-Module -Name SCEPmanClient
```

{% hint style="info" %}
Sigue la guía de Microsoft sobre cómo instalar PowerShell en [Linux](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux?view=powershell-7.5) o [MacOS](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-macos?view=powershell-7.5).
{% endhint %}

## Requisitos previos

Para que el módulo funcione como se espera, deberás añadir una pequeña modificación a tu implementación de SCEPman:

{% stepper %}
{% step %}

### Agregar URL de la página principal

Agregar la URL del App Service de SCEPman: Navega a la `Branding & Properties` sección del registro de la aplicación. Agrega la URL del App Service de SCEPman al campo URL de la página principal:

<figure><img src="https://4115997120-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LoGejQeUQcw7lqnQ3WX%2Fuploads%2FpvtsVJmycjyIgaQh2sHd%2Fimage.png?alt=media&#x26;token=9b9a7a21-4516-4718-9e32-346b39f9775a" alt=""><figcaption></figcaption></figure>

Esto es necesario para que el módulo pueda buscar automáticamente el client id del App Registration, que se necesita para la obtención del token de acceso.
{% endstep %}

{% step %}

### Permitir que Azure PowerShell interactúe con el App Registration

En el App Registration, navega a *Exponer una API* y crea un ámbito personalizado que pueda usarse para autorizar el client Id `1950a258-227b-4e31-a9cf-717495945fc2` (Microsoft Azure PowerShell)

<figure><img src="https://4115997120-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LoGejQeUQcw7lqnQ3WX%2Fuploads%2F46u0uC5d4K6YAQ3zh7YO%2Fimage.png?alt=media&#x26;token=82a318d0-5b3c-442a-887d-a064ff5e19be" alt=""><figcaption><p>Información de ejemplo para un ámbito de API personalizado</p></figcaption></figure>

Después de crear un ámbito de API, la aplicación Azure PowerShell puede autorizarse:

<figure><img src="https://4115997120-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LoGejQeUQcw7lqnQ3WX%2Fuploads%2Fp3C0zdof95GBMKox19RZ%2Fimage.png?alt=media&#x26;token=bc916c87-9233-4f11-82b1-33307e241e08" alt=""><figcaption><p>Aplicación Microsoft Azure PowerShell autorizada</p></figcaption></figure>
{% endstep %}

{% step %}

### Habilitar el endpoint EST

{% endstep %}
{% endstepper %}

## Permisos

SCEPman tiene distintos roles que permitirán inscribir distintos tipos de certificados. Puedes asignarlos en la *SCEPman-api* Enterprise Application (nombre predeterminado):

#### CSR DB Requesters

Este rol solo se puede asignar a service principals (por ejemplo, App Registrations) de forma predeterminada y permite solicitar certificados con subjects y usos arbitrarios.

{% content-ref url="api-enrollment" %}
[api-enrollment](https://docs.scepman.com/es/administracion-de-certificados/api-certificates/api-enrollment)
{% endcontent-ref %}

#### CSR Self Service

Este rol se puede asignar a usuarios y permitirá inscribir certificados con las siguientes restricciones:

* Solo EKU de ClientAuth
* Los certificados de usuario deben coincidir con el UPN del usuario en el subject o en el nombre alternativo del subject UPN
* Los certificados de dispositivo deben tener un subject o SAN que SCEPman pueda asociar a un objeto de dispositivo propiedad del usuario autenticado

{% content-ref url="self-service-enrollment" %}
[self-service-enrollment](https://docs.scepman.com/es/administracion-de-certificados/api-certificates/self-service-enrollment)
{% endcontent-ref %}

## Ejemplos de uso

### Usar autenticación de Azure

#### Autenticación interactiva

Al solicitar un nuevo certificado sin especificar el mecanismo de autenticación, el usuario se autenticará de forma interactiva de manera predeterminada. Usando el `-SubjectFromUserContext` parámetro, el subject y el SAN UPN del certificado se completarán automáticamente según el contexto del usuario que haya iniciado sesión:

```powershell
New-SCEPmanCertificate -Url 'scepman.contoso.com' -SubjectFromUserContext -SaveToStore CurrentUser
```

#### Inicio de sesión del dispositivo

Si quieres solicitar un nuevo certificado en un sistema sin entorno de escritorio, puedes usar el `-DeviceCode` parámetro para realizar la autenticación real en otra sesión:

```powershell
New-SCEPmanCertificate -Url 'scepman.contoso.com' -DeviceCode -SubjectFromUserContext -SaveToFolder /home/user/certificates
```

#### Autenticación con Service Principal

En escenarios totalmente automatizados, un App Registration puede usarse para la autenticación. En este caso no será posible inferir el subject a partir del contexto autenticado.

El uso de splatting de parámetros también hará que la ejecución sea más legible:

```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
```

### Autenticarse usando certificados

Una vez que se ha emitido un certificado usando un contexto autenticado, podemos usarlo para renovarlo sin proporcionar de nuevo ningún contexto.

#### CertificateBySubject

*Interactuar con los almacenes de claves solo es posible en Windows*

Al proporcionar el `CertificateBySubject` parámetro, el módulo intentará automáticamente encontrar un certificado adecuado para la renovación en los almacenes de claves *CurrentUser* y *LocalMachine* .

El valor introducido se comparará con expresiones regulares contra los subjects de todos los certificados disponibles.

```powershell
New-SCEPmanCertificate -CertificateBySubject 'WebServer' -SaveToStore 'LocalMachine'
```

#### Proporcionar un certificado específico

```powershell
$Certificate = Get-ChildItem Cert:\LocalMachine\My | Where-Object Thumbprint -eq '9B08EA68B16773CEF3C49D5D95BE50B784638984'

New-SCEPmanCertificate -Certificate $Certificate -SaveToStore LocalMachine
```

#### CertificateFromFile

En sistemas Linux, la renovación de un certificado puede realizarse pasando las rutas de un certificado existente y su clave privada.

```powershell
New-SCEPmanCertificate -CertificateFromFile '~/certs/myCert.pem' -KeyFromFile '~/certs/myKey.key' -SaveToFolder '~/certs'
```

Cuando uses una clave privada cifrada, se te pedirá la contraseña. También puedes pasar directamente la contraseña de la clave usando el `PlainTextPassword` parámetro.

#### Usar SCEPman con un Azure Web Application Firewall

Con los perfiles SSL habilitados, el WAF terminará las conexiones TLS. Esto a su vez romperá las renovaciones de certificados usando EST, ya que el procedimiento depende de mTLS para la autenticación. En este caso, el `UseSCEPRenewal` parámetro puede usarse para realizar en su lugar una renovación de certificado que cumpla con el protocolo SCEP.

```powershell
New-SCEPmanCertificate -CertificateBySubject 'WebServer' -SaveToStore 'LocalMachine' -UseSCEPRenewal
```

Ten en cuenta que esto requiere configuración adicional de SCEPman con respecto al endpoint SCEP estático:

* AppConfig:StaticValidation:Enabled : true
* AppConfig:StaticValidation:AllowRenewals : true
* AppConfig:StaticValidation:ReenrollmentAllowedCertificateTypes: Static (dependiendo de los tipos destinados a la renovación)