Azure ADとDocuSignをSAML連携して新規ユーザーの既定言語をjaにする
はじめに
Azure ADからDocuSignに初めてSAMLでサインインするとユーザーが作成されますが、既定の言語が英語になっているので日本語にするためにSAML Responseをカスタマイズしてみました。
SAML Responseのカスタマイズと実際のResponseの中身を調査できるようになることがゴールです。
初回SAML連携
こちらの記事で詳細に紹介されていますので本ブログでは割愛します。
気を付けるべきところを記載します。
- 開発者アカウントURL(無料)
- SAML設定画面は画面左上のパレット > Admin
- Azure ADに存在するカスタムドメインをDocuSignに追加してDNSで所有確認必要
※追加したドメインのみSSO可能 - HTTP要求 > 認証要求の送信 > POST
追加する属性の確認
Azure ADからWebブラウザを介してDocuSignに渡されるSAML Response内にDocuSignの言語属性を追加します。
属性の値はサービス側に依存するので、例えば新規ユーザーをCSVで一括インポートできる機能があればそのCSVに含める値を調べることで、SAML Responseにどの値を含めばいいかが分かります。
DocuSignの場合は、ユーザーを更新するCSVファイルの作成からLanguageの言語コードで表示言語を制御しているようです。
日本語は「ja」なのでこの値をSAML Responseに含めます。
Azure AD設定
- Azure AD > エンタープライズアプリケーション > DocuSign > シングルサインオン > 属性とクレーム > 編集
- 属性とクレーム > 新しいクレームの追加
- スクリーンショットの値を設定(ソース属性以外は任意の値で構いません)
「""」を忘れずに
名前:language
名前空間:http://schemas.xmlsoap.org/ws/2005/05/identity/claims
ソース:属性
ソース属性:"ja"
- クレーム名に含まれていることを確認
Azure AD側の設定は以上になります。
余談:追加設定
今回は不要な作業ですが、言語属性を特定のグループやゲストのみに追加したい場合は、先ほど作成した要求の条件を変更すれば適用できます。(Microsoft Learn)
グローバルなユーザー環境の場合は必要になるかもしれません。
また、追加する値を関数や正規表現でも設定できます。(Microsoft Learn)
ソースを変換にすることで、UPNのプレフィックスのみ取得できたり、といったことが可能です。
DocuSign設定
- 管理画面 > アクセス管理 > IDプロバイダー > アクション > 設定の管理
- 設定 > カスタム属性 > カスタム属性の追加
- 属性でlanguageを選択し、カスタムの属性名にAzure ADで設定した名前空間/名前(例:http://schemas.xmlsoap.org/ws/2005/05/identity/claims/language)を追加し保存
DocuSign側の設定は以上になります。
実際にサインインしてSAML Responseを確認
DocuSignにユーザーが作成されていないAzure ADのユーザーでサインインしてプロビジョニングの様子を見てみます。
- Google Chromeを起動し、右クリック > 検証で開発者ツールを起動
- ネットワークでログを保存(Preserve log)にチェック
- 開発者ツールを起動しているタブのURL欄にDocuSignサインインURLを入力
※マイアプリポータルを利用している場合、アプリを選択すると新規タブになってしまうのでURLを直接入力してください。 - サインインが成功し、DocuSign上にユーザーが新規作成され言語も日本語になっています。
続いてSAML Responseを解析します。
開発者ツールでsamlと検索し、PayloadにSAML Responseが含まれるものを探し、base64でエンコードされた値を取得します。
このままではResponse内の内容がわからないのでデコードする必要があります。
デコードツールは任意のもので構いませんが、今回はPowerShellを使用します。
コードはこちらの記事を利用します。
$b64txt = "取得したSAML Responseの値"
$byte = [System.Convert]::FromBase64String($b64txt)
$txt = [System.Text.Encoding]::Default.GetString($byte)
echo $txt
実行結果を成形します。(一部抜粋)
<samlp:Response ID="_xxxxx" Version="2.0" IssueInstant="2023-04-17T10:37:50.471Z" Destination="https://account-d.docusign.com/organizations/xxx/saml2/login/xxx" InResponseTo="xxx" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
<AttributeStatement>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
<AttributeValue>Adele</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
<AttributeValue>Vance</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
<AttributeValue>AdeleV@anbutter.dev</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
<AttributeValue>AdeleV@xxx.com</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/language">
<AttributeValue>ja</AttributeValue>
</Attribute>
</AttributeStatement>
</samlp:Response>
AttributeValueでjaを渡しているのが確認できます。
おわりに
SAML Request/Responseを見るとAzure ADの基本的なSAML連携のトラブルシューティングにもなります。
Discussion