IdM実験室: Azure ADを拡張してOpenID Connect for Identity Assuranceに対応させる

こんにちは、富士榮です。

先日、OpenID ConnectのID保証に関する拡張仕様である「OpenID Connect for Identity Assurance」について紹介しましたが、実際に仕様を理解するためには実装してみるのが一番、ということでAzure Active Directoryを拡張して実装してみようと思います。（尚、現状は完成している訳ではありません。軽く動作を確認してみた程度です）

Azure ADに足りないもの

OpenID Connect for Identity Assuranceを実装する上で、Azure ADに足りないものは最低限でも以下の通りです。

Authorizationエンドポイントがclaimsパラメータを受け付ける機能
verified_claims等の属性をid_tokenやuserInfoエンドポイントから返す機能

逆に、Azure ADでも以下について当然ですが出来ます。

認証
ユーザデータを保持するデータベース
アプリケーション（Client）管理

実装に向けた戦略

ということで、以下の戦略で拡張してみることにしました。

Azure ADのエンドポイントをラップするWebアプリを用意し、request/responseの整形を行う
認証、データ保持、アプリケーション管理はAzure ADの機能を使う
OpenID Connect for Identity Assuranceで拡張された属性（verified_claims関係）はAzure ADのスキーマを拡張する

こんな感じの仕組みになるはずです。

いざ実装

準備１：Azure ADのスキーマを拡張する

Azure ADにはスキーマ拡張を行う機能がありますので、今回はこの機能を使ってAzure AD上にID保証に関する情報、ID保証済みの属性を保存できるようにします。

Azure ADのスキーマ拡張に関するドキュメントはこちら

https://docs.microsoft.com/ja-jp/graph/extensibility-overview

OpenID Connect for Identity Assuranceでは「verified_claims」というエレメントの定義がされており、配下に「verification」と「claims」というエレメントが存在します。

verification : IDの検証をどのように行ったのか？の記録

trust_framework : どんなルールによってIDの確認・検証をしたのか。例えば犯罪収益移転防止法や携帯電話不正利用法などの、本人確認を行った際の根拠法やルールを指定します
Evidence : ID確認時に利用した証拠（エビデンス）を指定します。免許証などですね。

type : エビデンスの種類を指定します。id_document（証明書類）、utility_bill（公共料金の領収書）、qes（欧州限定ですがeIDASの電子証明書）がありますが、ここではid_documentを使いました。
method : typeで指定したエビデンスをどのように確認したのか？を指定します。例えば対面で確認した場合は「Physical In-Person Proofing」ということで「pipp」という値を設定します。
document : typeにid_documentを指定した場合に、具体的に何の証明書類を使ったのか？を指定します。例えば日本の免許証なら「jp_drivers_license」を指定します。
issuer : 証明書を発行した機関に関する情報を指定します。

name : 機関名
country : 機関の属する国

date_of_issuance : 証明書類の発行日を指定します。
date_of_expiry : 証明書の有効期限を指定します。

claims : 検証された属性（ここは要求された属性を普通に指定します）

given_name : 検証済みの名
family_name : 検証済みの姓
など

この形でAzure ADの属性を拡張出来ればいいのですが、上記ドキュメントにもある通り、拡張できる属性の型はStringやInteger、DateTimeなどに限定され入れ子の構造や配列構造が取れません。本来なら複数のエビデンスを使ったID証明などもあり得ますが、現状はデータをフラットで持つしかありませんので諦めます。

具体的な方法は以下の通りです。

Directory.AccessAsUser.Allをスコープに指定してaccess_tokenを取得する
https://graph.microsoft.com/v1.0/schemaExtensionsに拡張したいスキーマの構造（JSON）をPOSTする
成功したら他のクライアントからでも参照可能な様にスキーマをアクティベーションする（status属性をPATCHでActiveに更新する）

今回、以下の2つの拡張属性を作りました。

verification
verifiedClaims

それぞれのPOSTしたデータはこちらです。

- verification

{
    "id":"verification",
    "description": "verification extension for OpenID Connect for Identity Assurance",
    "targetTypes": [
        "User"
    ],
    "properties": [
        {
            "name": "verificationId",
            "type": "String"
        },
        {
            "name": "trustframework",
            "type": "String"
        },
        {
            "name": "evidenceType",
            "type": "String"
        },
        {
            "name": "evidenceMethod",
            "type": "String"
        },
        {
            "name": "evidenceDocumentType",
            "type": "String"
        },
        {
            "name": "evidenceDocumentIssuerName",
            "type": "String"
        },
        {
            "name": "evidenceDocumentIssuerCountry",
            "type": "String"
        },
        {
            "name": "evidenceNumber",
            "type": "String"
        },
        {
            "name": "evidenceDateOfIssurance",
            "type": "DateTime"
        },
        {
            "name": "evidenceDateOfExpiry",
            "type": "DateTime"
        }
    ]
}

- verifiedClaims

{
    "id": "verifiedClaims",
    "description": "verified claims extension for OpenID Connect for Identity Assurance",
    "targetTypes": [
        "User"
    ],
    "properties": [
        {
            "name": "verificationId",
            "type": "String"
        },
        {
            "name": "givenName",
            "type": "String"
        },
        {
            "name": "familyName",
            "type": "String"
        }
    ]
}

ちなみに、拡張スキーマの単位でid（属性名となります）をつけることが出来ますが、.net、.comなど限られたTLDでカスタムドメインをAzure ADに追加している場合は、[カスタムドメイン名]_[拡張属性名]という名前で属性を作ることが出来ますが、カスタムドメインを持っていない場合は「ext][8桁のランダム文字列]_[拡張属性名]という形で属性名が払い出されます。

当然ですが、この拡張属性に値を入れた状態のユーザを用意しておく必要があります。この辺りはGraph APIを使って値のセットをしてください。

準備２：Azure ADをラップするWebサービスを作る

ココが本番です。といってもやることはシンプルです。
（本来はちゃんと実装しないと危険ですので注意してください。本ポストにサンプルコードが出てきますが、かなり手抜きなのであくまで参考として捉えてください）

Authorizationエンドポイント

clientからの要求の中でAzure ADが受け取ってくれないclaimsパラメータをパースして保持します。後からレスポンスを作るときに何が要求されていたのかを判断するために使います。
※テスト実装では決めうち実装なので実際には保持していません

router.get('/authorize', (req, res) => {
    // get claims from request
    var _claims = req.query.claims;
    // redirect to Azure AD
    var target = lib.addQueryTo(conf.AAD_AuthZ, {
            response_type: 'code',
            scope: 'openid User.Read',
            client_id: req.query.client_id,
            state: req.query.state,
            redirect_uri: req.query.redirect_uri });
    res.redirect(target);
});

Tokenエンドポイント

codeを受け取ってAzure ADのTokenエンドポイントへ渡してaccess_token、id_tokenを受け取ります。
id_tokenには当然verified_claimsが含まれていないので、一度id_tokenをほどき、必要に応じてaccess_tokenを使ってMicrosoft Graphで追加の属性を取得、id_tokenを生成してclientへ返却します。
※テスト実装ではPKCEに対応させていませんので、code横取りをして実装しています。本来はclientとPKCEに使う情報を共有しないと横取り出来ないので、ここはちゃんと考えないとダメです。

router.post('/token', async (req,res) => {
    try{
        let response_from_aad_token = await request({
            url: conf.AAD_Token,
            method: "POST",
            form: {
                grant_type: 'authorization_code',
                code: req.body.code,
                client_id: req.body.client_id,
                client_secret: req.body.client_secret,
                redirect_uri: req.body.redirect_uri
            },
            json: true
        })
        console.log(response_from_aad_token);
        // extract response and re-generate id_token with verified claims
        let decoded_jwt = jwt.decode(response_from_aad_token.id_token)

        // get additional claims using graph api
        let response_from_graph = await request({
            url: conf.AAD_Graph + "/v1.0/me?$select=id,userPrincipalName," + conf.AAD_ExtPrefix + "_verifiedClaims," + conf.AAD_ExtPrefix + "_verification",
            method: "GET",
            headers: {
                'Authorization': 'Bearer ' + response_from_aad_token.access_token,
                'Content-Type': 'application/json'
            }
        })
        console.log(response_from_graph);
        var user = JSON.parse(response_from_graph);
        // get properties from user object
        for (var prop in user){
            if(prop.includes('_verification')){
              var _verification = {
                trustframework: user[prop].trustframework,
                evidenceType: user[prop].evidenceType,
                evidenceMethod: user[prop].evidenceMethod,
                evidenceDocumentType: user[prop].evidenceDocumentType,
                evidenceDocumentIssuerName: user[prop].evidenceDocumentIssuerName,
                evidenceDocumentIssuerCountry: user[prop].evidenceDocumentIssuerCountry,
                evidenceDateOfIssurance: user[prop].evidenceDateOfIssurance,
                evidenceDateOfExpiry: user[prop].evidenceDateOfExpiry
              }
            } else if(prop.includes('_verifiedClaims')){
              var _verifiedClaims = {
                familyName: user[prop].familyName,
                givenName: user[prop].givenName
              }
            }
        }
        // create new jwt.
        var privateKey = fs.readFileSync('./private_key.pem', 'utf-8')
        var new_jwt = null;
        if (typeof _verification !== 'undefined') {
            new_jwt = jwt.sign({
                sub: decoded_jwt.sub,
                iss: 'https://' + req.headers.host,
                aud: decoded_jwt.aud,
                iat: decoded_jwt.iat,
                exp: decoded_jwt.exp,
                email: decoded_jwt.email,
                verified_claims: {
                    verification: {
                        trust_framework: _verification.trustframework,
                        evidence: [
                            {
                                type: _verification.evidenceType,
                                method: _verification.evidenceMethod,
                                document: {
 type: _verification.evidenceDocumentType,
 issuer: {
name: _verification.evidenceDocumentIssuerName,
country: _verification.evidenceDocumentIssuerCountry
 },
 number: _verification.evidenceNumber,
 date_of_issuance: _verification.evidenceDateOfIssurance,
 date_of_expiry: _verification.evidenceDateOfExpiry
                                }
                            }
                        ]
                    },
                    claims: {
                        given_name: _verifiedClaims.givenName,
                        first_name: _verifiedClaims.familyName
                    }
                }
            }, privateKey, { algorithm: 'RS256' });    
        } else {
            new_jwt = jwt.sign({
                sub: decoded_jwt.sub,
                iss: 'https://' + req.headers.host,
                aud: decoded_jwt.aud,
                iat: decoded_jwt.iat,
                exp: decoded_jwt.exp,
                email: decoded_jwt.email,
            }, privateKey, { algorithm: 'RS256' });    
        }
        
        res.send({
            token_type: "bearer",
            scope: "openid",
            expires_in: response_from_aad_token.expires_in,
            access_token: response_from_aad_token.access_token,
            id_token: new_jwt
        });
    } catch(e){
        console.log(e);
    }
});

userInfoエンドポイント

access_tokenを使ってMicrosoft Graphから必要な属性を取得して、整形した上でclientへ返却します
※テスト実装ではここは実装していません。id_tokenにverified_claimsを入れて返却するところまでです。

その他

.well-known/openid-configurationとかjwks_uriは必要に応じて実装します。id_tokenの署名をAzure ADではなくこのWebサービス側で行うので対応した公開鍵などの情報をclientへ公開してあげる必要があります。

とりあえずこんな感じでnode.jsで実装してみています。

実際に動かす

テストするにしてもclientが必要になるので、phpでちょこっと書いておく必要があります。
やるべきことはclaimsパラメータを認証要求に乗せて検証済み属性を要求する、ということだけであとは普通のOpenID Connectのクライアントです。

こんな感じですね。

    // claims生成
    $verificationArray = array(
        'trust_framework'=>'null'
    );
    $claimsArray = array(
        'given_name'=>'null',
        'family_name'=>'null'
    );
    $verified_claimsArray = array(
        'verification'=>$verificationArray,
        'claims'=>$claimsArray
    );
    $id_tokenArray = array(
        'email'=>'null',
        'verified_claims'=>$verified_claimsArray
    );
    $claimsArray = array(
        'id_token'=>$id_tokenArray
    );
    
    // GETパラメータ関係
    $query = http_build_query(array(
        'client_id'=>$client_id,
        'response_type'=>$response_type,
        'redirect_uri'=> $redirect_uri,
        'scope'=>'openid User.Read',
        'state'=>$state,
        'nonce'=>$nonce,
        'claims'=>json_encode($claimsArray)
    ));
    // リクエスト
    header('Location: ' . $authorization_endpoint . '?' . $query );

動かすとこんな感じになります。
node.jsを動かすのにglitchを使っているので起き上がるまでにちょっと時間がかかってますが。。。

ということで、ここまでのソースはこちらにあります。
くれぐれも真似して使わない様にしてください。色々危ないので。
https://github.com/fujie/aad_oidc4ida

IdM実験室

2020年5月16日土曜日

Azure ADを拡張してOpenID Connect for Identity Assuranceに対応させる