ホーム › Networking.ActiveDirectory › DsWriteAccountSpnW

DsWriteAccountSpnW

関数

アカウントオブジェクトにSPNを書き込む(Unicode版)。

DLLNTDSAPI.dll文字セットUnicode (-W)呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// NTDSAPI.dll  (Unicode / -W)
#include <windows.h>

DWORD DsWriteAccountSpnW(
    HANDLE hDS,
    DS_SPN_WRITE_OP Operation,
    LPCWSTR pszAccount,
    DWORD cSpn,
    LPCWSTR* rpszSpn
);

パラメーター

名前	型	方向	説明
hDS	HANDLE	in	DSBind 関数または DSBindWithCred 関数から取得したディレクトリサービスハンドルを格納します。
Operation	DS_SPN_WRITE_OP	in	DsWriteAccountSpn が実行する操作を指定する DS_SPN_WRITE_OP の値のいずれかを格納します。
pszAccount	LPCWSTR	in	Active Directory Domain Services 内のユーザーオブジェクトまたはコンピューターオブジェクトの識別名を指定する、null で終わる定数文字列へのポインターです。呼び出し元は、このオブジェクトの servicePrincipalName プロパティへの書き込みアクセス権を持っている必要があります。
cSpn	DWORD	in	rpszSpn に含まれる SPN の数を指定します。この値が 0 で、かつ Operation に DS_SPN_REPLACE_SPN_OP が含まれる場合、この関数は指定されたアカウントの servicePrincipalName 属性からすべての値を削除します。
rpszSpn	LPCWSTR*	in	pszAccount パラメーターで識別されるアカウントに追加する、またはそのアカウントから削除する SPN を指定する、null で終わる定数文字列の配列へのポインターです。サービスの SPN を構成するには DsGetSpn 関数を使用します。

戻り値の型: DWORD

公式ドキュメント

Active Directory Domain Services 内の指定したユーザーアカウントオブジェクトまたはコンピューターアカウントオブジェクトの servicePrincipalName 属性に、サービスプリンシパル名 (SPN) の配列を書き込みます。(Unicode)

戻り値

成功した場合は ERROR_SUCCESS を返します。失敗した場合は、Win32、RPC、またはディレクトリサービスのエラーを返します。

解説(Remarks)

DsWriteAccountSpn 関数は、1 つ以上のサービスインスタンスの SPN を登録します。SPN は、信頼された認証サービスと組み合わせて、クライアントがサービスを認証するために使用します。アプリケーションやサービスが他のサービスを識別する SPN を不正に登録するセキュリティ攻撃を防ぐため、ユーザーアカウントおよびコンピューターアカウントの既定の DACL では、ほとんどの場合ドメイン管理者のみが SPN を登録できるようになっています。

このルールの例外の 1 つとして、LocalSystem アカウントで実行されているサービスは、SPN に指定されたホストが、そのサービスを実行しているコンピューターの DNS 名または NetBIOS 名である場合に限り、"ServiceClass/Host:Port" という形式の単純な SPN を DsWriteAccountSpn を呼び出して登録できます。

もう 1 つの例外として、コンピューターアカウントの既定の DACL では、一定の制約の下で、呼び出し元が自分自身に対して SPN を登録することが許可されています。たとえば、コンピューターアカウントは、自身のコンピューター名に基づく "host/<computername>" という形式の SPN を持つことができます。コンピューター名が SPN に含まれているため、この SPN は許可されます。

DSA が任意の SPN の書き込みを許可するように構成されている場合、上記のルールはいずれも適用されません。ただし、これはセキュリティを低下させるため推奨されません。

DsWriteAccountSpn に渡された SPN は、実際には pszAccount で指定されたコンピューターオブジェクトの Service-Principal-Name 属性に追加されます。この呼び出しは、アカウントオブジェクトが格納されているドメインコントローラーに対して RPC を使用して行われるため、そのアカウントで許可される SPN に関するポリシーを安全に適用できます。LDAP を使用して SPN プロパティに直接書き込むことは許可されておらず、すべての書き込みはこの RPC 呼び出しを経由する必要があります。LDAP を使用した読み取りは許可されています。

SPN の設定に必要なアクセス許可

アカウントに任意の SPN を書き込むには、書き込みを行う側に "Write ServicePrincipalName" 権限が必要ですが、この権限はアカウントを作成したユーザーには既定では付与されません。アカウントを作成したユーザーには "Write validated SPN" 権限 (マシンアカウントにのみ存在します) が付与されます。

以下は、マシンアカウントに対するユーザーごとの権限の概要です。

ユーザーの種類	権限
アカウントを作成したユーザー	Write validated SPN
Account Operators	Write SPN および Write Validated SPN
Authenticated Users	なし
(自分自身)	Write Validated SPN

ユーザーアカウントには "Validated SPN" プロパティも "Write SPN" 権限も存在しません。代わりに、"Write public information" プロパティセットによって、任意の SPN を作成する機能が付与されます。

メモ

ntdsapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして DsWriteAccountSpn を定義します。エンコーディング中立のエイリアスと、エンコーディング中立でないコードを混在させて使用すると、不一致が生じ、コンパイルエラーや実行時エラーの原因となる可能性があります。詳細については、関数プロトタイプの規則を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// NTDSAPI.dll  (Unicode / -W)
#include <windows.h>

DWORD DsWriteAccountSpnW(
    HANDLE hDS,
    DS_SPN_WRITE_OP Operation,
    LPCWSTR pszAccount,
    DWORD cSpn,
    LPCWSTR* rpszSpn
);

[DllImport("NTDSAPI.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern uint DsWriteAccountSpnW(
    IntPtr hDS,   // HANDLE
    int Operation,   // DS_SPN_WRITE_OP
    [MarshalAs(UnmanagedType.LPWStr)] string pszAccount,   // LPCWSTR
    uint cSpn,   // DWORD
    IntPtr rpszSpn   // LPCWSTR*
);

<DllImport("NTDSAPI.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function DsWriteAccountSpnW(
    hDS As IntPtr,   ' HANDLE
    Operation As Integer,   ' DS_SPN_WRITE_OP
    <MarshalAs(UnmanagedType.LPWStr)> pszAccount As String,   ' LPCWSTR
    cSpn As UInteger,   ' DWORD
    rpszSpn As IntPtr   ' LPCWSTR*
) As UInteger
End Function

' hDS : HANDLE
' Operation : DS_SPN_WRITE_OP
' pszAccount : LPCWSTR
' cSpn : DWORD
' rpszSpn : LPCWSTR*
Declare PtrSafe Function DsWriteAccountSpnW Lib "ntdsapi" ( _
    ByVal hDS As LongPtr, _
    ByVal Operation As Long, _
    ByVal pszAccount As LongPtr, _
    ByVal cSpn As Long, _
    ByVal rpszSpn As LongPtr) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

DsWriteAccountSpnW = ctypes.windll.ntdsapi.DsWriteAccountSpnW
DsWriteAccountSpnW.restype = wintypes.DWORD
DsWriteAccountSpnW.argtypes = [
    wintypes.HANDLE,  # hDS : HANDLE
    ctypes.c_int,  # Operation : DS_SPN_WRITE_OP
    wintypes.LPCWSTR,  # pszAccount : LPCWSTR
    wintypes.DWORD,  # cSpn : DWORD
    ctypes.c_void_p,  # rpszSpn : LPCWSTR*
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('NTDSAPI.dll')
DsWriteAccountSpnW = Fiddle::Function.new(
  lib['DsWriteAccountSpnW'],
  [
    Fiddle::TYPE_VOIDP,  # hDS : HANDLE
    Fiddle::TYPE_INT,  # Operation : DS_SPN_WRITE_OP
    Fiddle::TYPE_VOIDP,  # pszAccount : LPCWSTR
    -Fiddle::TYPE_INT,  # cSpn : DWORD
    Fiddle::TYPE_VOIDP,  # rpszSpn : LPCWSTR*
  ],
  -Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "ntdsapi")]
extern "system" {
    fn DsWriteAccountSpnW(
        hDS: *mut core::ffi::c_void,  // HANDLE
        Operation: i32,  // DS_SPN_WRITE_OP
        pszAccount: *const u16,  // LPCWSTR
        cSpn: u32,  // DWORD
        rpszSpn: *const *const u16  // LPCWSTR*
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("NTDSAPI.dll", CharSet = CharSet.Unicode)]
public static extern uint DsWriteAccountSpnW(IntPtr hDS, int Operation, [MarshalAs(UnmanagedType.LPWStr)] string pszAccount, uint cSpn, IntPtr rpszSpn);
"@
$api = Add-Type -MemberDefinition $sig -Name 'NTDSAPI_DsWriteAccountSpnW' -Namespace Win32 -PassThru
# $api::DsWriteAccountSpnW(hDS, Operation, pszAccount, cSpn, rpszSpn)

#uselib "NTDSAPI.dll"
#func global DsWriteAccountSpnW "DsWriteAccountSpnW" wptr, wptr, wptr, wptr, wptr
; DsWriteAccountSpnW hDS, Operation, pszAccount, cSpn, varptr(rpszSpn)   ; 戻り値は stat
; hDS : HANDLE -> "wptr"
; Operation : DS_SPN_WRITE_OP -> "wptr"
; pszAccount : LPCWSTR -> "wptr"
; cSpn : DWORD -> "wptr"
; rpszSpn : LPCWSTR* -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "NTDSAPI.dll"
#cfunc global DsWriteAccountSpnW "DsWriteAccountSpnW" sptr, int, wstr, int, var
; res = DsWriteAccountSpnW(hDS, Operation, pszAccount, cSpn, rpszSpn)
; hDS : HANDLE -> "sptr"
; Operation : DS_SPN_WRITE_OP -> "int"
; pszAccount : LPCWSTR -> "wstr"
; cSpn : DWORD -> "int"
; rpszSpn : LPCWSTR* -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "NTDSAPI.dll"
#cfunc global DsWriteAccountSpnW "DsWriteAccountSpnW" sptr, int, wstr, int, sptr
; res = DsWriteAccountSpnW(hDS, Operation, pszAccount, cSpn, varptr(rpszSpn))
; hDS : HANDLE -> "sptr"
; Operation : DS_SPN_WRITE_OP -> "int"
; pszAccount : LPCWSTR -> "wstr"
; cSpn : DWORD -> "int"
; rpszSpn : LPCWSTR* -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。