# SCEPmanClient

SCEPmanClient は、SCEPman の REST API と対話することを目的とした PowerShell モジュールです。プラットフォームに依存せず、Windows PowerShell v5 と互換性があるため、このモジュールを使用して、REST API で利用可能なすべてのユースケース向けに証明書を要求できます。

* サーバー証明書の自動発行
* 管理対象外デバイス用のクライアント証明書
* Linux デバイスへの証明書の登録

## インストール

SCEPmanClient モジュールは PowerShell Gallery から利用でき、次のコマンドを使用してインストールできます。

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

{% hint style="info" %}
PowerShell を次にインストールする方法については、Microsoft のガイドに従ってください [Linux](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux?view=powershell-7.5) または [MacOS](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-macos?view=powershell-7.5).
{% endhint %}

## 前提条件

モジュールが期待どおりに機能するためには、SCEPman のデプロイに小さな変更を追加する必要があります。

{% stepper %}
{% step %}

### ホーム ページ URL を追加

SCEPman の App Service URL を追加します: 次へ移動します `Branding & Properties` アプリ登録のセクション。ホーム ページ URL フィールドに SCEPman の App Service URL を追加します:

<figure><img src="https://114237723-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>

これは、モジュールがアクセス トークン取得に必要な App Registrations のクライアント ID を自動的に検索できるようにするために必要です。
{% endstep %}

{% step %}

### Azure PowerShell が App Registration と対話できるようにする

App Registration で、次へ移動します *Expose an API* そして、クライアント ID を認可するために使用できるカスタム スコープを作成します `1950a258-227b-4e31-a9cf-717495945fc2` (Microsoft Azure PowerShell)

<figure><img src="https://114237723-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>カスタム API スコープの情報例</p></figcaption></figure>

API スコープを作成した後、Azure PowerShell アプリケーションを認可できます。

<figure><img src="https://114237723-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>認可された Microsoft Azure PowerShell アプリケーション</p></figcaption></figure>
{% endstep %}

{% step %}

### EST エンドポイントを有効化

{% endstep %}
{% endstepper %}

## アクセス許可

SCEPman には、異なる種類の証明書の登録を許可するさまざまなロールがあります。これらは次の *SCEPman-api* （既定の名前）Enterprise Application:

#### CSR DB Requesters

このロールは、既定では Service Principals（たとえば App Registrations）にのみ割り当て可能で、任意のサブジェクトおよび用途を持つ証明書を要求できます。

{% content-ref url="api-enrollment" %}
[api-enrollment](https://docs.scepman.com/ja/zheng-ming-shu-guan-li/api-certificates/api-enrollment)
{% endcontent-ref %}

#### CSR セルフサービス

このロールはユーザーに割り当てることができ、以下の制限付きで証明書の登録を許可します。

* ClientAuth EKU のみ
* ユーザー証明書は、サブジェクトまたは UPN subject alternative name のいずれかで、ユーザーの UPN と一致している必要があります
* デバイス証明書は、SCEPman が認証されたユーザーによって所有されるデバイス オブジェクトにマップできるサブジェクトまたは SAN を持っている必要があります

{% content-ref url="self-service-enrollment" %}
[self-service-enrollment](https://docs.scepman.com/ja/zheng-ming-shu-guan-li/api-certificates/self-service-enrollment)
{% endcontent-ref %}

## 使用例

### Azure 認証を使用する

#### 対話型認証

認証メカニズムを指定せずに新しい証明書を要求する場合、既定ではユーザーは対話的に認証されます。次を使用することで `-SubjectFromUserContext` パラメーター、証明書のサブジェクトおよび UPN SAN は、ログインしているユーザーのコンテキストに基づいて自動的に設定されます:

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

#### デバイス ログイン

デスクトップ環境のないシステムで新しい証明書を要求したい場合は、次を使用できます `-DeviceCode` パラメーターを使用して、別のセッションで実際の認証を実行します:

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

#### Service Principal 認証

完全に自動化されたシナリオでは、認証に App Registration を使用できます。この場合、認証されたコンテキストからサブジェクトを推測することはできません。

パラメーター スプラッティングを使用すると、実行もより読みやすくなります:

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

### 証明書を使用して認証する

認証されたコンテキストを使用して証明書が発行されると、以後はコンテキストを再度提供しなくても、それを使用して更新できます。

#### CertificateBySubject

*キーストアとの対話は Windows でのみ可能です*

次のものを指定すると `CertificateBySubject` パラメーター、モジュールは自動的に更新に適した証明書を次の中から見つけようとします *CurrentUser* および *LocalMachine* キーストア。

入力された値は、利用可能なすべての証明書のサブジェクトに対して regex 一致が行われます。

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

#### 特定の証明書を指定する

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

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

#### CertificateFromFile

Linux システムでは、既存の証明書とその秘密鍵のパスを渡すことで証明書の更新を実行できます。

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

暗号化された秘密鍵を使用する場合、パスワードの入力を求められます。また、次を使用して鍵のパスワードを直接渡すこともできます `PlainTextPassword` パラメーター。

#### Azure Web Application Firewall で SCEPman を使用する

SSL Profiles が有効になっている場合、WAF は TLS 接続を終端します。これにより、EST を使用した証明書の更新は機能しなくなります。これは、この手順が認証に mTLS に依存しているためです。この場合、 `UseSCEPRenewal` パラメーターを使用して、代わりに SCEP プロトコルに準拠した証明書更新を実行できます。

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

これには、静的 SCEP エンドポイントに関する追加の SCEPman 構成が必要であることに注意してください:

* AppConfig:StaticValidation:Enabled : true
* AppConfig:StaticValidation:AllowRenewals : true
* AppConfig:StaticValidation:ReenrollmentAllowedCertificateTypes: Static（更新対象の種類によって異なります）