クライアントの設定項目

Table of Contents

クライアントの設定項目

デベロッパーコンソールを用いてクライアントアプリケーションの設定をおこなうことができます。ここでは、各設定項目について説明します。

なお、Authlete 1.x 系の共用サーバー(api.authlete.com)用のデベロッパーコンソール(cd.authlete.com)には存在しない項目も含まれます。

基本情報

クライアント名

クライアントアプリケーションを識別するための名前です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の client_name に相当します。

Authlete の /api/auth/authorization API からのレスポンスには、認可リクエストをおこなったクライアントアプリケーションの情報が含まれています。ここで設定したクライアント名は、その情報の中に含まれるようになるので、認可エンドポイントの実装が /api/auth/authorization API からのレスポンスの内容を参照しながら認可画面を生成する際、ここで設定したクライアント名を参照することができます。

Authlete の /api/client/create API と /api/client/update API は、クライアント名の多言語対応(OpenID Connect Dynamic Client Registration, 2.1. Metadata Languages and Scripts )をサポートしていますが、デベロッパーコンソールは対応していません。

クライアントの説明

クライアントに関する説明です。

Authlete の /api/auth/authorization API からのレスポンスには、認可リクエストをおこなったクライアントアプリケーションの情報が含まれています。ここで設定したクライアントの説明は、その情報の中に含まれるようになるので、認可エンドポイントの実装が /api/auth/authorization API からのレスポンスの内容を参照しながら認可画面を生成する際、ここで設定したクライアントの説明を参照することができます。

クライアント ID の別名有効化

Authlete が割り当てた数値のクライアント ID に加えて、別の任意の文字列をクライアント ID として利用したい場合、この項目を有効にします。

「既存のシステムを Authlete に移行するにあたり、既存のクライアント ID を引き続き利用したい」という要件があれば、この Client ID 別名機能を用いて実現することができます。そのような要件がない場合は、この機能を無効のままにしておいてかまいません。

注意:ここで有効と設定しても、このクライアントが属するサービスの同名の設定項目が有効になっていないと、Client ID 別名機能は動きません。

クライアント ID の別名

Authlete が割り当てた数値のクライアント ID に加えて、別の任意の文字列をクライアント ID として利用したい場合、「クライアント ID の別名有効化」を有効にした上で、この設定項目にクライアント ID の別名を設定します。

クライアント ID の別名は、認可リクエストの client_id パラメーターの値として使用することが可能です。また、認可リクエストの結果として ID トークンの発行が伴う場合、その ID トークンの aud クレームの値はクライアント ID の別名となります。

クライアント ID の別名は、そのクライアントが属するサービス内において一意でなければなりません。

クライアントタイプ

【重要】 クライアントタイプです。クライアントタイプは、RFC 6749, 2.1. Client Types に挙げられている confidential もしくは public のどちらかです。

クライアントが自身の認証に必要な情報(クライアントシークレットや秘密鍵)を秘密に保つことが可能である場合、そのようなクライアントは confidential クライアントと呼ばれます。例えば、社内の閉じたネットワーク環境内に置かれて安全に守られたクライアントで、外部から攻撃を受けてクライアントシークレットを盗まれることはないと期待できるのであれば、それは confidential クライアントとみなすことができます。

一方、クライアントが自身の認証に必要な秘密情報を秘密に保つことが難しい場合、そのようなクライアントは public クライアントと呼ばれます。例えば、マーケットプレースに置かれて誰でもダウンロードできる状態にあるアプリケーション(一般的なスマートフォン用アプリケーション)の場合、ハッカーであればそのアプリケーションの中に埋め込まれたクライアントシークレットを抜き取ることが可能であると予想されるため、秘密情報を秘密に保つことが難しいと言えます。このようなクライアントは、public クライアントと呼ばれます。

クライアントが confidential か public なのかの違いで、要求仕様が変わってきます。例えば、「confidential クライアントはトークンエンドポイントにアクセスする際にクライアント認証が必要だが public クライアントは不要(RFC 6749)」、「public クライアントはリクエストオブジェクトの署名に対称鍵系アルゴリズムを使用してはならない(OpenID Connect)」、といった差異があります。

クライアントタイプに PUBLIC を選択した場合、「トークンエンドポイント / クライアント認証方式」では NONE を選択しておいてください。Authlete 2.0 以降では、NONE 以外が選択されている場合、トークンリクエスト実行時にエラーが発生します。

このように様々な影響があるので、クライアントタイプはよく検討して選択してください。

アプリケーションタイプ

アプリケーションタイプです。未選択、WEB、NATIVE のいずれかを選択することができます。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metada の application_type に相当します。

Authlete の視点から見ると、アプリケーションタイプの選択は、リダイレクト URI の検証動作にしか影響を及ぼしません。WEB もしくは NATIVE を選択した場合、認可リクエストの redirect_uri について、次のような検証が追加で実行されます。

アプリケーションタイプ 追加検証内容
WEB インプリシットフローを使う場合、リダイレクト URI のスキームは https でなければならず、また、ホストは localhost であってはならない。
NATIVE リダイレクト URI として使用可能なのは、カスタムスキームではじまる URI か、もしくは、スキームが http でホストが localhost の URI。https は不可。

リダイレクト URI に対する上記の追加検証が不要の場合は、アプリケーションタイプは未選択のままとしてください。

ロゴの URI

クライアントのロゴ画像の URI です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metada の logo_uri に相当します。

Authlete の /api/client/create API と /api/client/update API は、ロゴ URI の多言語対応(OpenID Connect Dynamic Client Registration, 2.1. Metadata Languages and Scripts )をサポートしていますが、デベロッパーコンソールは対応していません。

連絡先

クライアントの責任者の方々のメールアドレスです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metada の contacts に相当します。

TLS クライアント証明書を紐付けたアクセストークンの使用

OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens の 3. Mutual TLS Client Certificate Bound Access Tokens で定義されている、証明書に紐付いたアクセストークンを使うかどうかの設定です。

この機能を使うと、トークンリクエストの際に用いられたクライアント証明書の情報がアクセストークンに紐付けられます。クライアントアプリケーションは、そのアクセストークンを使って Web API にアクセスするときは、トークンリクエストの際に用いたものと同じクライアント証明書を使ってアクセスしないといけません。そうしないと、アクセスは拒否されます。

アクセストークンをクライアント証明書に紐付けておくと、アクセストークンが漏洩してしまったとしても、簡単には悪用されなくなります。というのは、アクセストークンが手元にあったとしても、そのアクセストークンが発行された際に用いられたクライアント証明書も同時に手元にない限り、Web API アクセスを成功させることができないからです。

この機能を使用する場合、クライアントアプリケーションはトークンエンドポイントとの HTTPS 通信および Web API との HTTPS 通信において、クライアント証明書を提示する必要があります。

Financial-grade API では、Read-Write API 用の認可コード・アクセストークン・リフレッシュトークンはクライアント証明書に紐付いている必要があります。そのため、FAPI の Read and Write API Security Profile を使うためには、本設定を「使用する」にしてください。

注意:この設定項目で「使用する」を選択しても、このクライアントが属するサービスの「TLS クライアント証明書を紐付けたアクセストークンのサポート」の設定が有効になっていないと、アクセストークンをクライアント証明書に紐付ける処理は動きません。

認可

認可種別

このクライアントアプリケーションが使用する認可種別です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metada の grant_types に相当します。

AUTHORIZATION_CODE は、認可エンドポイントで認可コードの発行を受け、それをトークンエンドポイントでアクセストークンと交換するフローです。詳細は RFC 6749, 4.1. Authorization Code Grant で定義されています。最も一般的なフローです。

IMPLICIT は、認可エンドポイントから直接アクセストークンの発行を受けるフローです。詳細は RFC 6749, 4.2. Implicit Grant で定義されています。Web ブラウザ内で動く JavaScript アプリケーションに直接アクセストークンを発行するなどの用途で用いられます。

PASSWORD は、トークンエンドポイントにユーザーの ID とパスワードを提示することでアクセストークンの発行を受けるフローです。詳細は RFC  6749, 4.3. Resource Owner Password Credentials Grant で定義されています。仕様書にも記載がある通り、このフローは何らかの理由で他のフローが利用できない場合のみ使用してください。明確な理由がなければ、商用環境では無効にしておいてください。

CLIENT_CREDENTIALS は、トークンエンドポイントにクライアントアプリケーションの ID とシークレットを提示することでアクセストークンの発行を受けるフローです。詳細は RFC 6749, 4.4. Client Credentials Grant で定義されています。このフローでは、どのユーザーにも紐付かないアクセストークンが発行されます。そのようなアクセストークンの発行を受けたいという明確な理由がなければ、商用環境では無効にしておいてください。

REFRESH_TOKEN は、トークンエンドポイントでリフレッシュトークンを交換するフローです。詳細は RFC 6749, 6. Refreshing an Access Token で定義されています。リフレッシュトークンを用いてアクセストークンを更新することがあるのであれば、本項目を有効にしておいてください。

注意:この設定で使用するとしていても、当該クライアントアプリケーションが属するサービスの「サポートする認可種別」でサポートされていないものは使用することはできません。使用すると、実行時にエラーとなります。

【参考】OAuth 2.0 全フローの図解と動画

応答種別

このクライアントアプリケーションが使用する応答種別です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metada の response_types に相当します。
RFC 6749 では、認可エンドポイントから発行されるトークンは、認可コードもしくはアクセストークンのどちらかでした。しかし、OAuth 2.0 Multiple Response Type Encoding Practices という追加仕様により、(a) 認可コード、(b) ID トークン、(c) アクセストークン、の任意の組み合わせで発行が可能となりました。また、何も発行しないという選択肢(none)も用意されました。

NONECODETOKENID_TOKEN はそれぞれ、このクライアントアプリケーションが認可リクエストの response_type パラメーターの値として単独で none、code、token、id_token を指定する可能性があることを意味します。

CODE_TOKEN は、このクライアントアプリケーションが code token という組み合わせ(順不同)を response_type パラメーターの値とし指定する可能性があることを意味します。以下同様に、CODE_ID_TOKEN は code id_token、ID_TOKEN_TOKEN は id_token token、CODE_ID_TOKEN_TOKEN は code id_token token という組み合わせを指定する可能性があることを意味します。

Financial-grade API (FAPI)の仕様では、更新系 API 用アクセストークンのための認可リクエストでは、response_type として code id_token もしくは code id_token token のどちらかを指定しなければならないと定められているので、CODE_ID_TOKEN と CODE_ID_TOKEN_TOKEN が両方とも無効になっている場合、FAPI 更新系 API 用の認可リクエストは必ず失敗することになってしまうので、注意してください。

注意:この設定で使用するとしていても、当該クライアントアプリケーションが属するサービスの「サポートする応答種別」でサポートされていないものは使用することはできません。使用すると、実行時にエラーとなります。
【参考】OpenID Connect 全フロー解説

リダイレクト URI

【重要】 このクライアントアプリケーションが認可エンドポイントからの応答を受け取るためのリダイレクト URI です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metada の redirect_uris に相当します。

リダイレクト URI に対応する要求仕様は下記のとおりです。

RFC 6749 による要求仕様3.1.2. Redirection Endpoint より)

  • 絶対 URI であること。
  • フラグメント部を含んではならない。

OpenID Connect Core 1.0 による要求仕様3.1.2.1. Authentication Request より)

  • redirect_uri パラメーターは省略できない。
  • 事前登録されたものと完全一致しなければならない。

OpenID Connect Dynamic Client Registration 1.0 による要求仕様2. Client Metadata , application_type より)

  • アプリケーションタイプが web であるクライアントアプリケーションがインプリシットフローを使用する際、そのリダイレクト URI のスキームは https でなければならず、また、ホストは localhost であってはならない。
  • アプリケーションタイプば native であるクライアントアプリケーションは、リダイレクト URI はカスタムスキームではじまるか、もしくはスキームが http でホストが localhost でなければならない。https は不可。

リダイレクト URI を一つも登録していないクライアントアプリケーションからの認可リクエストは、次の全ての条件を満たさない限り失敗します。

  • クライアントタイプが confidential であること。
  • response_type リクエストパラメーターの値が code であること。
  • 認可リクエストに redirect_uri リクエストパラメーターが含まれていること。
  • redirect_uri リクエストパラメーターの値が絶対 URI であり、フラグメント部を含んでいないこと。
  • scope リクエストパラメーターに openid が含まれていないこと。

RFC 6749 では、ある条件下ではリダイレクト URI の部分一致が許容されます(詳細は RFC 6749, 3.1.2.2. Registration Requirements を参照)。しかし、OpenID Connect では完全一致が要求されます。
デベロッパーコンソールでクライアントアプリケーションを作成すると、初期値として「{Authleteサーバー}/api/mock/redirection/{サービスAPIキー}」という URL がリダイレクト URI として登録されます。このリダイレクト URI は、クライアントアプリケーション開発中は便利なのですが、商用時に使うべきものではないのでご留意ください。

トークンエンドポイント / クライアント認証方式

【重要】 このクライアントアプリケーションがトークンエンドポイントで使用するクライアント認証方式です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metada の token_endpoint_auth_method に相当します。

NONE は OpenID Connect Core 1.0, 9. Client Authentication の none に対応しています。これを選択すると、このクライアントアプリケーションはトークンエンドポイントでクライアント認証をおこなわないという意味になります。クライアントタイプが PUBLIC のクライアントは NONE を選択してください。Authlete 2.0 以降、チェックが厳密になったので、PUBLIC クライアントのクライアント認証方式の設定が NONE 以外の場合、トークンリクエスト実行時にエラーが発生します。

CLIENT_SECRET_BASIC は OpenID Connect Core 1.0, 9. Client Authentication の client_secret_basic に対応しています。これは RFC 6749, 2.3. Client Authentication に記述されている Basic 認証ベースの方法です。RFC 6749 では、認可サーバーは必ずこのクライアント認証方式をサポートしなければならないとされています。

CLIENT_SECRET_POST は OpenID Connect Core 1.0, 9. Client Authentication の client_secret_post に対応しています。この方式では、クライアント認証情報が RFC 6749, 2.3. Client Authentication に記載されている方法でリクエスト・ボディーに埋め込まれます。

CLIENT_SECRET_JWT は OpenID Connect Core 1.0, 9. Client Authentication の client_secret_jwt に対応しています。RFC 7523 で定義されている JWT 系クライアント認証方式で、JWT の署名に共有鍵系のアルゴリズムを用います。

PRIVATE_KEY_JWT は OpenID Connect Core 1.0, 9. Client Authentication の private_key_jwt に対応しています。RFC 7523 で定義されている JWT 系クライアント認証方式で、JWT の署名に非対称鍵系のアルゴリズムを用います。

TLS_CLIENT_AUTH はクライアント証明書を用いたクライアント認証方式で、詳細は OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens の 2.1. PKI Mutual TLS OAuth Client Authentication Method で説明されています。

SELF_SIGNED_TLS_CLIENT_AUTH は自己署名クライアント証明書を用いたクライアント認証方式で、詳細は OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens の 2.2. Self-Signed Certificate Mutual TLS OAuth Client Authentication Method で説明されています。

Financial-grade API 仕様では、Read-Only API 用のトークンリクエストで用いることが許されているクライアント認証方式は次の 4 つです。1. TLS_CLIENT_AUTH 2. SELF_SIGNED_TLS_CLIENT_AUTH 3. CLIENT_SECRET_JWT 4. PRIVATE_KEY_JWT

また、Read-Write API 用のトークンリクエストで用いることが許されているクライアント認証方式は次の 3 つです。1. TLS_CLIENT_AUTH 2. SELF_SIGNED_TLS_CLIENT_AUTH 3. PRIVATE_KEY_JWT

ですので、FAPI 対応の CONFIDENTIAL クライアントは、CLIENT_SECRET_BASIC、CLIENT_SECRET_POST 以外の方式でクライアント認証をおこなう必要があります。

トークンエンドポイント / アサーション署名アルゴリズム

トークンエンドポイントで JWT 系のクライアント認証(CLIENT_SECRET_JWT と PRIVATE_KEY_JWT)を使用する際、その JWT の署名アルゴリズムです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metada の token_endpoint_auth_signing_alg に相当します。

いずれのアルゴリズムも選択しない場合、それは、このクライアントアプリケーションは認可サーバーがサポートするアルゴリズムのうち、任意のものを用いて署名をおこなうことを意味します。一方、何かアルゴリズムが選択されていれば、クライアントアプリケーションは宣言通りそのアルゴリズムを使用しなければなりません。

FAPI Read-Write API 用処理に関する要求仕様として「JWS の署名アルゴリズムは PS256 もしくは ES256 でなければならない」というものがあり、この要求仕様は、JWT 系のクライアント認証方式で用いられる JWT(client_assertion リクエストパラメーターで指定される JWT)にも適用されるので注意してください。

トークンエンドポイント / 自己署名証明書を含む JWK のキー ID

このクライアントアプリケーションが使用する自己署名証明書を含む JWK を指定するためのキー ID です。

クライアント認証などで自己署名証明書を用いる場合、クライアントアプリケーションは自己署名証明書を表す JWK を含む JWK セットを事前に登録しておく必要があります。

この項目が設定されていると、それは自己署名証明書を表す JWK のキー ID とみなされ、登録された JWK セットの中から当該 JWK を選択する際に利用されます。この項目が設定されていない場合は x5c フィールドを含む JWK が選択されますが、もし条件を満たす候補が複数存在する場合は選択に失敗し、その結果、自己署名証明書を必要とする処理は失敗します。

リクエストオブジェクトの署名アルゴリズム

このクライアントアプリケーションがリクエストオブジェクト の署名に使う署名アルゴリズムです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の request_object_signing_alg に相当します。

いずれのアルゴリズムも選択しない場合、それは、このクライアントアプリケーションは認可サーバーがサポートするアルゴリズムのうち、任意のものを使用することを意味します(署名しないケースも含みます)。一方、何かアルゴリズムを選択した場合は、このクライアントアプリケーションが用いるリクエストオブジェクトは、そのアルゴリズムで署名されなければなりません。他のアルゴリズムで署名されたリクエストオブジェクトは拒否されます。アルゴリズム NONE は、「何も選択しない」とは意味が異なるので注意してください(参照:JWS 7515, A.5. Example Unsecured JWS )。

非対称鍵系アルゴリズムを選択した場合は、このクライアントアプリケーションは認可サーバーがリクエストオブジェクトの署名を検証するために使用する公開鍵を含む JWK セットを認可サーバーに事前に登録しておくか、もしくは JWK セットをどこかで公開しておく必要があります。後者の場合、JWK セットの場所を示す URI を認可サーバーに登録しておかなければなりません。

このクライアントアプリケーションのクライアントタイプが PUBLIC の場合、対称鍵系のアルゴリズムは選択しないでください。

FAPI Read-Write API 用処理に関する要求仕様として、次のものがあるので注意してください。

  1. 必ずリクエストオブジェクトを使用しなければならない(=認可リクエストにおいて request もしくは request_uri パラメーターのどちらかが必須)。
  2. リクエストオブジェクトは署名されていなければならない(=署名アルゴリズム none は不可)。
  3. 署名アルゴリズムは PS256 もしくは ES256 のどちらか。

リクエストオブジェクトのキー暗号化アルゴリズム

このクライアントアプリケーションがリクエストオブジェクト の暗号鍵の暗号化に使うアルゴリズムです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の request_object_encryption_alg に相当します。

この設定項目の値が何であっても、このクライアントアプリケーションはリクエストオブジェクトを暗号化してもよいですし、暗号化しなくてもかまいません。さらに、認可サーバーがサポートするものであれば、他のアルゴリズムを用いてもかまいません。

「リクエストオブジェクトの本文暗号化アルゴリズム」において何かしらアルゴリズムを選択している場合、この設定項目においても何かしらアルゴリズムを設定しておく必要があります。

このクライアントアプリケーションのクライアントタイプが PUBLIC の場合、対称鍵系のアルゴリズムは選択しないでください。

【参考】二段階の暗号処理

リクエストオブジェクトの本文暗号化アルゴリズム

このクライアントアプリケーションがリクエストオブジェクト の本文を暗号化する際に使うアルゴリズムです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の request_object_encryption_enc に相当します。

リクエスト URI

認可リクエストの request_uri の値として指定する可能性のあるリクエストオブジェクトの URI 群です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の request_uris に相当します。

ここで登録されていない値を request_uri に指定すると、認可リクエストは失敗します。

ユーザー認証 / 最大認証有効期間

最大認証有効期間のデフォルト値を秒単位で指定します。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の default_max_age に相当します。

このアプリケーションからの認可リクエストに max_age リクエストパラメーター(OpenID Connect Core 1.0, 3.1.2.1. Authentication Request )が含まれていない場合、この設定が参照されます。0 という値は「デフォルト値を設定しない」という意味になります。

仕様上、ユーザーが最後に認証されてから max_age もしくは default_max_age により指定された値以上の時間が経過していた場合、既にユーザーがログイン済みであったとしても、認可サーバーは再度ユーザー認証をおこなわなければなりません。

Authlete の /api/auth/authorization API からの応答には maxAge というパラメーターが含まれています。この値が 0 ではない場合、それは max_age もしくは本設定項目(default_max_age)から得られた値ですので、認可サーバーの実装では、ユーザーが最後に認証されてからの経過時間がその値を超えているかどうかをチェックし、超えている場合は再度ユーザー認証をおこなうようにしてください。

もしも認可サーバーの実装が「ユーザーが最後に認証された時刻」を管理していない場合、max age を正しく処理できないということなので、/api/auth/authorization API からの応答に含まれる maxAge が 0 より大きい場合、認可エンドポイントの実装から /api/auth/authorization/fail API を reason=MAX_AGE_NOT_SATISFIED で呼び出し、クライアントアプリケーションへのエラー応答を生成してください。reason パラメーターが取りうる値については AuthorizationFailRequest.Reason の JavaDoc を参照してください。

ユーザー認証 / 認証コンテキスト

認証コンテキストのデフォルト値を指定します。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の default_acr_values に相当します。

このアプリケーションからの認可リクエストに acr_values リクエストパラメーター(OpenID Connect Core 1.0, 3.1.2.1. Authentication Request )が含まれておらず、かつ、claims リクエストパラメーター(OpenID Connect Core 1.0, 5.5. Requesting Claims using the “claims” Request Parameter )の値に acr クレームが含まれていない場合、この設定が参照されます。

仕様上、認可サーバーは、要求された認証コンテキストのいずれかを満たすよう、ユーザー認証を処理します。しかし、必須(essential)とされていない限り、列挙された認証コンテキストのいずれも満たせなくても仕様違反とはなりません。詳細は OpenID Connect Core 1.0, 5.5.1.1. Requesting the “acr” Claim を参照してください。

Authlete の /api/auth/authorization API からの応答には acrs というパラメーターが含まれています。この値が空ではない場合、それは、acr_values リクエストパラメーター、claims リクエストパラメーター内の acr プロパティー、もしくは本設定項目(default_acr_values)から得られた値です。

また、同 API からの応答には acrEssential というパラメーターも含まれており、この値が true の場合、いずれかの認証コンテキストを満たす必要があります。いずれも満たすことができない場合は、認可エンドポイントの実装から /api/auth/authorization/fail API を reason=ACR_NOT_SATISFIED で呼び出し、クライアントアプリケーションへのエラー応答を生成してください。reason パラメーターが取りうる値については AuthorizationFailRequest.Reason の JavaDoc を参照してください。

【参考】認証コンテキストクラス

ID トークン

ID トークンの署名アルゴリズム

【重要】 このアプリケーションが要求する、ID トークン の署名アルゴリズムです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の id_token_signed_response_alg に相当します。

仕様上、ID トークンには必ず署名が必要なので、この項目で NONE を選択すると、認可サーバーは ID トークンを生成できなくなります。そのため、ID トークンを要求する認可リクエストは全て失敗します。

このクライアントアプリケーションのクライアントタイプが PUBLIC の場合、対称鍵系のアルゴリズムは選択しないでください。

FAPI Read-Write API 用処理に関する要求仕様として「JWS の署名アルゴリズムは PS256 もしくは ES256 でなければならない」というものがあり、この要求仕様は、ID トークンにも適用されるので注意してください。

ID トークンのキー暗号化アルゴリズム

このクライアントアプリケーションが要求する、ID トークン の暗号鍵の暗号化に使うアルゴリズムです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の id_token_encrypted_response_alg に相当します。
何もアルゴリズムを選択しなければ、ID トークンは暗号化されません。

非対称鍵系アルゴリズムを選択した場合は、このクライアントアプリケーションは認可サーバーが ID トークンを暗号化するために使用する公開鍵を含む JWK セットを認可サーバーに事前に登録しておくか、もしくは JWK セットをどこかで公開しておく必要があります。後者の場合、JWK セットの場所を示す URI を認可サーバーに登録しておかなければなりません。

「ID トークンの本文暗号化アルゴリズム」において何かしらアルゴリズムを選択している場合、この設定項目においても何かしらアルゴリズムを設定しておく必要があります。

このクライアントアプリケーションのクライアントタイプが PUBLIC の場合、対称鍵系のアルゴリズムは選択しないでください。

【参考】二段階の暗号処理

ID トークンの本文暗号化アルゴリズム

このクライアントアプリケーションが要求する、ID トークン の本文を暗号化する際に使うアルゴリズムです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の id_token_encrypted_response_enc に相当します。

認証要求時刻

ID トークンに auth_time クレームを常に埋め込むかどうかを指定する設定項目です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の require_auth_time に相当します。

Authlete の実装は、この設定項目の値が何であっても、/api/auth/authorization/issue API の authTime リクエストパラメーターが 0 でなければ、ID トークンに auth_time クレームを埋め込みます。

逆に、authTime リクエストパラメーターの値が 0 の場合、この設定項目が true であっても ID トークンに auth_time クレームを埋め込みません。このとき、現在の Authlete の実装はエラーを生成しないので、厳密には仕様違反になります。ただし、この仕様違反動作は認可エンドポイントの実装側で事前に対処すべき事項となります。すなわち、authTime リクエストパラメーターに正しい値を設定して /api/auth/authorization/issue API を呼び出すか、もしくは、authTime の正しい値を用意できないのであれば /api/auth/authorization/issue API ではなく /api/auth/authorization/fail API をコールすべき、ということになります。

サブジェクトタイプ

このクライアントアプリケーションが要求するサブジェクトタイプです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の subject_type に相当します。詳細は OpenID Connect Core 1.0, 8. Subject Identifier Types を参照してください。

補足:OpenID Connect Dynamic Client Registration 1.0 に subject_type が定義されているため、デベロッパーコンソールにもそれに対応する本設定項目が用意されています。しかし、サイブジェクトタイプの存在意義から考えると、サブジェクトタイプの設定をクライアントアプリケーション開発者自身が変更できてしまっては、あまり意味がありません。すなわち、クライアントアプリケーション開発者が PAIRWISE を積極的に選択する動機がない上、サーバー側が PAIRWISE を強制できないのであれば、あまり意味がありません。

セクター識別子

PAIRWISE なサブジェクト値(=他のクライアントアプリケーションでは意味をなさないサブジェクト値)を計算する際に参照する URL です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の sector_identifier_uri に相当します。詳細は OpenID Connect Core 1.0, 8.1. Pairwise Identifier Algorithm を参照してください。

ただし、Authlete は sector_identifier_uri をサポートしていないので、本設定項目の値は認可サーバーの動作になんら影響を与えません。

JWK セット

JWK セットの URI

このクライアントアプリケーションの JWK セット の場所を示す URL です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の jwks_uri に相当します。

このクライアントアプリケーションが、ID トークンユーザー情報エンドポイント からの応答、認可レスポンス JWT(JWT Secured Authorization Response Mode for OAuth 2.0 )の暗号化に、非対称鍵系アルゴリズムを要求する場合、当該アルゴリズムの公開鍵に相当する JWK を含む JWK セットを用意する必要があります。認可サーバーはその公開鍵を用いて暗号化をおこないます。

また、このクライアントアプリケーションが、非対称鍵系アルゴリズムを用いてリクエストオブジェクトに署名する場合、当該アルゴリズムの公開鍵に相当する JWK を含む JWK セットを用意する必要があります。認可サーバーはその公開鍵を用いて署名を検証します。

上記の理由で JWK セットを用意したとき、その JWK セットそのものを「JWK セットの内容」として登録しておくか、もしくは、その JWK セットをどこかに置き、その場所を示す URL を本設定項目にセットしておく必要があります。

JWK セットの内容

【重要】 このクライアントアプリケーションの JWK セットです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の jwks に相当します。

OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata には jwks_uri が利用可能であれば jwks を使用してはいけない、と書かれています。デベロッパーコンソールでは、jwks_uri と jwks に相当する情報(「JWK セットの内容(本項目)」と「JWK セットの URI」)を同時に登録することができますが、両方登録されている場合、jwks_uri に相当する情報のみが利用されます。

このクライアントアプリケーションが、ID トークンユーザー情報エンドポイント からの応答、認可レスポンス JWT(JWT Secured Authorization Response Mode for OAuth 2.0 )の暗号化に、非対称鍵系アルゴリズムを要求する場合、当該アルゴリズムの公開鍵に相当する JWK を含む JWK セットを用意する必要があります。認可サーバーはその公開鍵を用いて暗号化をおこないます。

また、このクライアントアプリケーションが、非対称鍵系アルゴリズムを用いてリクエストオブジェクトに署名する場合、当該アルゴリズムの公開鍵に相当する JWK を含む JWK セットを用意する必要があります。認可サーバーはその公開鍵を用いて署名を検証します。

上記の理由で JWK セットを用意したとき、その JWK セットそのものを本設定項目で登録しておくか、もしくは、その JWK セットをどこかに置き、その場所を示す URL を「JWK セットの URI」にセットしておく必要があります。

JWK セットの内容は、RFC 7515, 5. JWK Set Format で説明されているフォーマットに準拠する JSON でなければなりません。もちろん、その JWK セットにこのクライアントアプリケーションの秘密鍵を含めてはいけません。

参考までに、JWS(RFC 7515 )の alg に指定可能なアルゴリズム(署名に使うアルゴリズム)は、JWA(RFC 7518 )の「3.1. “alg” (Algorithm) Header Parameter Values for JWS 」に列挙されています。それらのうち、RS、PS、ES ではじまるアルゴリズムが非対称鍵系アルゴリズムです。

また、JWE(RFC 7516 )の alg に指定可能なアルゴリズム(暗号化に使うアルゴリズム)は、JWA(RFC 7518 )の「4.1. “alg” (Algorithm) Header Parameter Values for JWE 」に列挙されています。それらのうち、RSA、ECDH ではじまるアルゴリズムが非対称鍵系アルゴリズムです。

JWK や JWK セットを作成するオンラインサービスとして mkjwk.org というものがありますので、参考にしてみてください。

TLS クライアント認証のためのサブジェクト識別子

PKI のクライアント証明書を用いてクライアント認証をおこなう際に用いる証明書の識別子です。この項目は、OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens の 2.1. PKI Mutual TLS OAuth Client Authentication Method で定義されている tls_client_auth_subject_dn に相当します。

クライアント認証に TLS_CLIENT_AUTH を用いる場合のみ、本項目の設定が必要です。

OIDC エンドポイント

ユーザー情報の署名アルゴリズム

このクライアントアプリケーションが要求する、ユーザー情報エンドポイント からの応答に対する署名アルゴリズムです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の userinfo_signed_response_alg に相当します。

何もアルゴリズムを選択しなければ、ユーザー情報エンドポイントからの応答に署名はおこなわれません。なお、何も選択しないことと、NONE を選択することとでは、意味が異なりますので注意してください。NONE を選択すると Unsecured JWS が生成されます。

もしも「ユーザー情報の署名アルゴリズム」も「ユーザー情報のキー暗号化アルゴリズム」も選択されていない場合、ユーザー情報エンドポイントからの応答のフォーマットは、平文の JSON となります(JWT ではありません)。

このクライアントアプリケーションのクライアントタイプが PUBLIC の場合、対称鍵系アルゴリズムを選択しないでください。

FAPI Read-Write API 用処理に関する要求仕様として「JWS の署名アルゴリズムは PS256 もしくは ES256 でなければならない」というものがあり、この要求仕様は、ユーザー情報エンドポイントからの応答が署名されるケースにも適用されるので注意してください。

ユーザー情報のキー暗号化アルゴリズム

このクライアントアプリケーションが要求する、ユーザー情報エンドポイント からの応答の暗号化に用いた暗号鍵を暗号化する際に使うアルゴリズムです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の userinfo_encrypted_response_alg に相当します。

何もアルゴリズムを選択しなければ、ユーザー情報エンドポイントからの応答は暗号化されません。ただし、「ユーザー情報の本文暗号化アルゴリズム」で何かアルゴリズムを選択している場合、本項目を何もアルゴリズムを選択しないままにしておくとエラーとなるので注意してください。

もしも「ユーザー情報の署名アルゴリズム」も「ユーザー情報のキー暗号化アルゴリズム」も選択されていない場合、ユーザー情報エンドポイントからの応答のフォーマットは、平文の JSON となります(JWT ではありません)。

このクライアントアプリケーションのクライアントタイプが PUBLIC の場合、対称鍵系アルゴリズムを選択しないでください。

【参考】二段階の暗号処理

ユーザー情報の本文暗号化アルゴリズム

このクライアントアプリケーションが要求する、ユーザー情報エンドポイント からの応答を暗号化するのに使用するアルゴリズムです。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の userinfo_encrypted_response_enc に相当します。

ログイン開始エンドポイントの URI

サードパーティープログラムがこのクライアントアプリケーションのログイン処理を開始するために使う URL です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の initiate_login_uri に相当します。

OpenID Connect Dynamic Client Registration 1.0 に initiate_login_uri が定義されているため、デベロッパーコンソールにもそれに対応する本設定項目が用意されています。しかし、Authlete の実装ではこの情報を利用していませんので、本項目を設定してもしなくても、認可サーバーの動作にはなんの影響もありません。

ドキュメント

利用規約の URI

このクライアントアプリケーションの利用規約の URL です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の tos_uri に相当します。

データ利用方針文書の URI

エンドユーザーのプロフィールデータの利用方針を記述したページの URL です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の policy_uri に相当します。

ホームページの URI

このクライアントアプリケーションの利用規約の URL です。この項目は OpenID Connect Dynamic Client Registration 1.0, 2. Client Metadata の client_uri に相当します。

拡張

クライアントアプリケーションの属性ではあるものの、クライアントアプリケーション開発者が設定変更可能であるべきではない項目があります。『拡張』タブには、そのような属性がリストされています。この『拡張』タブは、デベロッパーコンソールに「サービス API キー & サービス API シークレット」でログインした場合のみ表示されます。

要求可能スコープ群有効化

このクライアントアプリケーションが要求できるスコープ群に制限をかけるかどうかの設定です。

要求可能スコープ群

このクライアントアプリケーションが要求可能なスコープ群です。ここに列挙可能なスコープ群は認可サーバーがサポートしているものに限られます。サポートされていないスコープ群を書いても、Authlete サーバーはそれらを黙って無視します。

「要求可能スコープ群有効化」の設定を「有効」にし、この設定項目を空にしておくと、このクライアントアプリケーションは何のスコープもリクエストできなくなります。なお、スコープをリクエストはできなくても、アクセストークンの発行を受けることは可能です。ただ、そのアクセストークンには何のスコープも紐付けられません。