はじめてのOkta Workforce Identity [第10回] API Access Managementって一体なんだ？
目次
本ブログ記事では、Okta Workforce Identityのライセンスの一つである「API Access Management (以降、API-AM)」がどういうものなのかを解説したいと思います。
Oktaの価格表を見ると、「API Access Management」と書かれたものがありますが、「これって何モノ？」と思いながらも、「まぁ、今のところAPI要件ってそんなにないし、まぁいいか。」と、ひとまず放置している方も多いのではないかと思います。
しかし、日本においても様々なSaaSが日々登場してきており、それらSaaS間のAPI連携は今後ますます増えていくと考えられますので、このAPI-AMがどんなものなのかは早めに理解しておくに越したことはありません。
ということで、本ブログ記事ではAPI-AMについて解説します。
以降の解説は、以下のブログ記事の内容を実施済み (理解済み) の前提で進めていきます。
・はじめてのOkta Workforce Identity トライアル環境の構築
・はじめてのOkta Workforce Identity [第1回] ユーザーと認証器の関係を紐解く
・はじめてのOkta Workforce Identity [第2回] 多要素認証を紐解く
・はじめてのOkta Workforce Identity [第6回] APIってどうやって使うの？ (トークン編)
・はじめてのOkta Workforce Identity [第7回] APIってどうやって使うの？ (OAuth 2.0 認可コード編)
・はじめてのOkta Workforce Identity [第8回] APIってどうやって使うの？ (OAuth 2.0 Client Credentials編)
・はじめてのOkta Workforce Identity [第9回] OpenID Connectってなんだ？
API-AMライセンスはどんなときに必要なのか？
API-AMは、「OAuth2.0の認可サーバ / OIDCのOpenID Provider」を新たに追加したい場合に必要となるライセンスです。
この説明だけですと、それがどういう時なのかがピンと来ないと思いますが、最大のポイントは、「どこにあるリソースサーバを使うのか？」です。
Okta Workforce Identityのリソースサーバを使うだけなら、API-AMライセンスは要らない
Okta Workforce IdentityのリソースサーバへAPIでアクセスする場合は、「デフォルトの認可サーバ」を利用するので、標準機能として使えます ＝ 有償ライセンス (API-AM) は必要ありません (下図 (1)) 。
この「デフォルトの認可サーバ」のことを「Org Authorization Server (以降、Org AS)」と呼びます。
[第7回]、[第8回]、[第9回] で利用したのは、この「Org AS」です。
但し、「Org AS」は、以下のように設定の柔軟性がやや乏しいです。
■ アクセストークンのクレーム (claim) は変更できませんので、デフォルトのまま利用する必要があります (上図 (2)) 。
■ スコープ (scope) も、デフォルトで用意されているものから選択することはできますが、独自のスコープを追加することはできません (上図 (2)) 。
■ 一方で「Org AS」は、[第9回] での動作確認の通り、OpenID Connect (以降、OIDC) のOpenID Providerとして利用することはできます (上図 (3)) 。
OIDCの場合は、アクセストークンと違って設定の柔軟性が少しあり、IDトークンのクレームに、どのユーザー属性を持たせるかの指定もできます。
「Org AS」の場合の、IDトークンへのクレーム追加方法については、こちらをご参照ください。
しかし、指定はできるものの、Thin ID Tokenの場合には、追加したユーザー属性をIDトークン内に含めることができないので、その代わりとしてuserinfoエンドポイントから取得することになります。 ( 詳しくは、[第9回] の「userinfoエンドポイント」をご参照ください。)
「それの何が困るのか？」と思われるかもしれません。
困る理由は、追加したユーザー属性のクレームがIDトークンに含まれていれば、1度のアクションで取得できるのに、わざわざuserinfoエンドポイントにアクセスして取得する、というアクションを追加で行う必要があるので、アプリケーションのパフォーマンスに影響するためです。
また、userinfo エンドポイントのレートリミットがボトルネックになり得るため、その考慮も必要になります。
(一方、API-AMライセンスがあれば、Thin ID Tokenの場合でも、独自に追加したクレームをIDトークンに含められるようになります。)
外部のリソースサーバを使うなら、API-AMライセンスが必要になる
外部のリソースサーバへAPIでアクセスする場合は、「Org AS」の代わりに、新たに「カスタムが可能な認可サーバ」を追加して利用する必要があります。
API-AMライセンスは、この「カスタムが可能な認可サーバ」を追加するために必要なライセンスです (下図 (1)) 。
この「カスタムが可能な認可サーバ」のことを「Custom Authorization Server (以降、Custom AS)」と呼びます。
既述の「Org AS」では、アクセストークンのクレームの追加 / 変更ができないので、その影響による一番大きい制限は、aud (audience) クレーム値 ＝「 このアクセストークンを誰が受け取るのか？」の指定ができない ( ＝ audクレーム値が、下図でいうところの https://xxxxx.okta.com に固定される) ことです。
(audクレームがどのような意味を持つのかについては、[第9回] をご参照ください。)
API-AMライセンスによって、新たに「Custom AS」を追加でき、以下が可能になります。
■ アクセストークンのクレーム (claim) の追加/変更ができるようになります(上図 (2))。
クレームの追加/変更ができるので、audクレーム値も外部リソースサーバ (上図でいうところの https://strorager.xyz ) に変更できます。
■ 独自のスコープ (scope) も追加できるようになります (上図 (2)) 。
■ また、「Custom AS」においても「Org AS」と同様に、OIDCのOpenID Providerとしても利用できます (上図 (3)) 。
IDトークンのクレームにどのユーザー属性を持たせるかの指定ができ、Org ASと違って、Thin ID Tokenの場合でもそれらをIDトークンに含めることができるのもAPI-AMの利点です。
その設定方法は後述します (Org ASの設定方法とは異なります) 。
まとめますと、以下のようになります。
Custom ASがOAuth 2.0として動作する設定
では、実際にAPI-AMを設定してみましょう。
Okta Workforce Identityのトライアル環境は、API-AMライセンスが有効になっていますので、トライアル環境を使って動作を確認できます。
「Custom AS」には、「Custom Default Authorization Server (以降、Custom Default AS)」という、デフォルトで用意されたカスタム可能な認可サーバが存在しますので、それを使って動作を確認することにします。
まずは、OAuth 2.0 として動作する設定だけ行います。
(OIDCも同時に設定すると、少し複雑になるような気がしましたので。)
Custom Default AS が OAuth 2.0として動作する流れ
以下のような流れを想定します。
インターネット検索で調べたところでは、即座にテストに使えそうなOAuth 2.0のリソースサーバが見つからなかったので、リソースサーバ (https://storager.xyz) は存在するものと仮定し、後述の動作確認は、クライアント (Postman) がアクセストークンを受け取るところまでにします。
(a) リソースサーバである storager.xyz は、スコープとして少なくとも photo.read と photo.save を持っているという前提で、クライアント (Postman) から、その2つを要求することにします。
(b) Org ASの場合には暗黙的に行われる認可のステップですが、Custom ASでは目に見える形にできるので、そのように設定します。
(c) クライアントが受け取ったアクセストークンが、以下のクレーム値を持っていることを確認します。
■ aud (audience) クレーム ＝ https://storager.xyz
■ sub (subject) クレーム ＝ [email protected]
(↑デフォルトで、この状態になるように設定されています。)
■ scp (scope) クレーム ＝ photo.read と photo.save
■ (新規に追加する) groupクレーム ＝ Everyone、 その他所属グループ
Custom Default ASが OAuth 2.0として動作する設定
[第7回] で設定した「 認可コードグラント＋PKCEの設定」をベースとして使い、それに対して Custom Default ASを追加で設定します。
Custom Default ASは、「セキュリティ」→「API」→「認可サーバー」タブで表示された、名前に「default」と書かれたものが該当します。
名前の「default」または末尾の鉛筆マークをクリックしてください。
「設定」タブで、「編集」をクリックし、オーディエンス (＝Audクレーム) に「https://storager.xyz」と入力して、保存することで、以下の状態になります。
「スコープ」タブで、「スコープを追加」をクリックします。
表示された「スコープを追加」画面で、以下のように入力して、「作成」をクリックします。
■ 名前＝ photo.read
■ ユーザーの同意 ＝ オプション
■ サービスをブロック ＝ チェックを外す。
同様の方法で、「photo.save」も追加してください。
「クレーム」タブをクリックします。
subがデフォルトで指定されていることが分かります。
「クレームを追加」をクリックします。
表示された「クレームを追加」画面で、以下のように入力して、「作成」をクリックします。
■ 名前＝ group
■ トークンタイプに含める ＝ アクセストークン
■ 値タイプ ＝ グループ
■ フィルター ＝ 「正規表現に一致」を選択して、値に「.*」(「ドット」と「アスタリスク」)
「アクセスポリシー」タブは、必ず何らかのポリシーが設定されている必要がありますが、Custom Default AS の場合は事前設定が存在するので、このまま使います。(カスタマイズしてもOKです。)
「トークンのプレビュー」タブで、払い出されるアクセストークンの内容を見ることができます。
Postmanの設定と動作確認
Postmanの設定も、[第7回] で設定した「 認可コードグラント＋PKCEの設定」をベースに、以下の画像の通り、3箇所 (赤文字の部分) を変更します。
■ Auth URL (認可エンドポイント)
■ Access Token URL (トークンエンドポイント)
■ Scope (スコープ)
===== << Tips >> =====
「Custom Default AS」は、「Org AS」とは異なる、別の認可サーバなので、認可エンドポイントとトークンエンドポイントのURLが変わります。
===================
設定ができたら、一番下にある「Get New Access Token」をクリックします。
Okta Workforce Identityの認証画面が表示されますので、リソースオーナー ([email protected]) で認証を行います。
認証が成功すると、以下のように、クライアント (Postman) が認可サーバに要求したスコープに対して、リソースオーナーの意思を確認する画面 ＝ 「認可」を求める画面が表示されます。
(Org ASの場合には、認可は暗黙的に行われるため、表示されなかった画面です。)
「Allow Access」をクリックします。
===== << Tips >> =====
一度、上記の「Allow Access」を行うと、それ以降、もう一度 Postman から同様の処理を行っても、この「認可」の画面が表示されなくなると思います。
これは、Okta Workforce Identity側が、このユーザーが認可したことをキャッシュしているためです。
再度この画面を表示したい場合は、以下の「その他アクション」→「ユーザーセッションを消去」を実行してから、Postmanで同様の処理を実施してみてください。
===================
クライアント (Postman) が取得したアクセストークンをコピーします。
コピーしたアクセストークンを、下記のサイトにペーストしてください。
表示された画面のPAYLOADを確認すると、以下のような値が取得できていると思います。
★マークの4つのクレーム (aud、sub、scp、group) に、期待した値が入っていると思います。
Custom ASがOIDCとして動作する設定
続いて、API-AMを使って、OIDCの設定も行ってみましょう。
Custom Default ASがOIDCとして動作する流れ
以下のような流れを想定します。
(a) クライアント (Postman) から発行される認可リクエストのスコープに、openid と profile を追加します。
(b) クライアントが受け取ったIDトークンが、以下のクレーム値を持っていることを確認します。
■ aud (audience) クレーム ＝ クラアントID
■ sub (subject) クレーム ＝ End-Userの識別子
■ preferred_usernameクレーム ＝ [email protected]
■ (新規に追加する) groupsクレーム ＝ Everyone、 その他所属グループ
Custom Default AS が OIDCとして動作する設定
現時点で、すでにOIDCとして動作する状態になっていますが、API-AMを使うことで、アクセストークンと同様にIDトークンでも比較的簡単にクレームの追加ができるようになっているので、それを試してみましょう。
「クレーム」タブで、「クレームの追加」をクリックします。
表示された「クレームを追加」画面で、以下のように入力して、「作成」をクリックします。
■ 名前＝ groups
(↑アクセストークンのクレームと同じ名称は使えないので、こちらは末尾に「s」を追加)
■ トークンタイプに含める ＝ IDトークン
■ 値タイプ ＝ グループ
■ フィルター ＝ 「正規表現に一致」を選択して、値に「.*」(「ドット」と「アスタリスク」)
「トークンのプレビュー」タブで、払い出されるIDトークンの内容を見ることができます。
(IDトークンの場合は、下記画面の「スコープ」に openid を指定して下さい。)
Postmanの設定と動作確認
Postmanの設定は、「Configure New Token」のスコープに、openid と profile を追加するだけです。
設定ができたら、一番下にある「Get New Access Token」をクリックします。
この後、OAuth 2.0 の場合と同様の認証が行われます。
クライアント (Postman) が取得したIDトークンをコピーします。
コピーしたIDトークンを、下記のサイトにペーストしてください。
表示された画面のPayloadを確認すると、以下のような値が取得できていると思います。
★マークの aud、sub、preferred_username クレームは、クライアント が要求した openid と profile クレームによって取得された値ですが、それらに加えて、独自に追加した groups も取得できていると思います。
[参考]:
https://help.okta.com/oie/ja-jp/content/topics/security/api_access.htm
https://developer.okta.com/docs/concepts/auth-servers/
まとめ
本ブログ記事では、API Access Managementライセンスがどういうものなのかについて解説してみました。
以下3つの点にご注意いただければ、API-AMライセンスの要否で大きく間違うことはないと思います。
(以下のご要件に対しては、API-AMライセンスが必要です。)
■ 外部のOAuth2.0 リソースサーバへアクセスしたい。
■ アクセストークンに含めるクレーム (claim) やスコープ (scope) を追加/変更したい。
■ IDトークンのクレーム (claim) に、希望するユーザー属性を含めたい。
==========
Okta Workforce Identityでは、認証の強化だけに留まらず、管理者が行うユーザーの登録/変更/削除に関わる業務の自動化や、人事管理システムや既設ディレクトリなどとの柔軟な連携も可能です。
Oktaでは、これらの機能を体感頂くことができる「Okta Essentials」トレーニングをご用意しています。(日本語でのトレーニングもご用意しています。)
このトレーニングは全体像を体系的にご理解頂ける内容となっていますので、是非ともご活用ください。
Follow 岸本 卓也
