よくある質問
1:Monotype Fonts が対応する API 認証方式はどれですか?
Monotype Fonts は、API に対して 2 種類の認証方式をサポートしています:
クライアントクレデンシャル認証方式
ユースケース:この方式は、ユーザーが組織を代表してログインする必要がある場合に適しています。
仕組み:この方式では、組織が固有のクライアント ID とシークレットを使って認証を行います。この方式は通常、ユーザー操作が不要なマシン間通信(M2M)に使用されます。
セキュリティ:サーバーに安全な認証方法で、信頼できる事業体のみが特定のリソースにアクセスできるようにします。
リダイレクト URL による認可コードグラントタイプ
ユースケース:この方式は、API のエンドユーザーがログインする必要がある場合に使用されます。
仕組み:このシナリオでは、ユーザーはコールバック URL ページ(ユーザーが共有したリダイレクト URL)にリダイレクトされます。ユーザーが正常に認証されると、Auth0 は認可コードを付加してユーザーをアプリケーションにリダイレクトします。その後、このコードがアクセストークンと交換されます。
セキュリティ:このフローでは、リダイレクト URL を使うことで追加のセキュリティ層が追加され、アクセストークンがユーザーのブラウザ上に表示されないようにします。
2:グラントタイプとは何ですか?API での使用方法を教えてください。
アプリケーショングラントタイプ(またはフロー)は、アプリケーションがアクセストークンを取得する方式です。これにより、クレデンシャルを公開することなく、別の事業体に自社のリソースへのアクセスを制限して許可できます。OAuth 2.0 プロトコルでは、さまざまな種類のアクセスに対応するため、複数の認証タイプがサポートされています。
Monotype Fonts は、以下の認証タイプをサポートしています:
authorization_code
認可コードフロー(OAuth 2.0 RFC 6749、セクション 4.1 に定義)では、認可コードをトークンに交換します。このフローでは、アプリケーションの認証方式に交換が含まれており、安全を確保しなければならないため、機密アプリケーション(通常のWebアプリケーションなど)でのみ使用することができます。認可コードの取得には、API エンドポイント/oauth/authorize が使用されます。このエンドポイントでは、client_id および redirect_url を受け取ります。正常に実行されると、ユーザーはリダイレクト URL に付加された認可コードを取得します。
client_credentials
Client Credentials Flow(OAuth 2.0 RFC 6749、セクション 4.4 で定義)では、アプリケーションにより、クライアント ID やクライアントシークレットなどのアプリケーションクレデンシャルをアクセストークンと交換することが含まれます。
このフローは、ユーザーの代わりにシステムがアプリケーションを認証・認可する必要があるため、マシン間通信(M2M)型アプリケーション(CLI、デーモン、バックエンドサービスなど)に最適です。
refresh_token
リフレッシュトークンは、ユーザーに新しいアクセストークンおよび/または ID トークンをリクエストするために使用され、再認証は不要です。
通常、前のアクセストークンが失効する前に新しいアクセストークンをリクエストすべきですが(サービスの中断を避けるため)、毎回 API を呼び出す必要はありません。
3:リダイレクト URI とは何ですか?リダイレクト URI は、いつ、どのように使用すべきですか?
リダイレクト URI(Uniform Resource Identifier)は、特に、認可コードグラントタイプを使用する場合、安全な認証フローに不可欠な要素です。これは主に 2 つの目的に役立ちます。
セキュリティ
リダイレクト URI では、アプリケーションが認証サーバーから認可コードを受け取ります。この URI は、悪意あるリダイレクトを防ぐため、認証サーバーに事前登録されています。また、機密性の高い認可コードが適切な場所に送信されるようにします。
ユーザーエクスペリエンス
ユーザーがログインまたはアプリケーションを認可した後、シームレスにアプリケーションへ戻る必要があります。リダイレクト URI は、認証プロセスの完了後にユーザーが戻るべき URL を認証サーバーに指示することで、これを促進します。
リダイレクト URI の使用
登録:ユーザーは、登録時にリダイレクト URI を共有します。Monotype Fonts は、ユーザーアプリケーションのセットアップ時に、この URI を認証サーバーに登録します。
ログインフロー:アプリケーションは、認証リクエストにこの URI を含めて、認証サーバーに送信します。認可コードを取得するには、authorize API エンドポイント(/oauth/authorize)にアクセスします。ここで、クライアント ID(オンボーディングプロセスの一環として顧客と共有するクライアント ID とクライアントシークレット)およびリダイレクト URL を受け取ります。例:
curl --location 'https://api.monotype.com/v2/oauth/authorize?client_id=client_id&redirect_uri=redirect_uri'
認可コードの受け取り:ユーザーの認証後、認証サーバーはユーザーを事前登録された URI にリダイレクトします。その際、認可コードはリダイレクト URI のクエリパラメータまたはリクエストパラメータとして埋め込まれます。
シナリオ別の質問
4:有効なアクセストークンがありますが、一部の API を実行できません。なぜでしょうか?
認証サーバー上の各顧客アプリケーションには、スコープと呼ばれる固有の権限セットが割り当てられています。スコープは、当社 API の機能に対するアプリケーションのアクセスレベルを定義します。一般的なスコープには、read:font:metadata、read:font:data、create:webfonts:kit などがあります。
使用しようとする API 機能に必要なスコープがすべて、アプリケーションのアクセストークンに含まれていることを確認してください(https://jwt.io/ を使用)。
5:クライアント ID とクライアントシークレットとは何ですか?使用方法を教えてください。
クライアント ID とクライアントシークレットは、OAuth 2.0 認可サーバーでアプリケーションを認証するためのクレデンシャルです。これらは、ユーザーのユーザー名とパスワードのようなものですが、登録アプリケーションがその身元情報を証明するためのものです。顧客のアプリケーションが OAuth サーバーに登録された際に、クライアント ID とクライアントシークレットが生成されます。
クライアント ID
クライアント ID は、登録プロセス中にアプリケーションに割り当てられる一意の識別子です。認証サーバーとのやり取りで、アプリケーションを一意に識別するクレデンシャルとして機能します。クライアント ID は認証に不可欠な要素で、Auth サーバーが受信した認証リクエストを特定のアプリケーションと関連付けるのに役立ちます。これは認証リクエストの正当性を検証するために使用され、認可されたアプリケーションのみがユーザーの認証および認可処理にアクセスできるようにします。通常、クライアント ID はクライアントシークレットと組み合わせて使用され、認証フローのセキュリティを強化します。
クライアントシークレット
クライアントシークレットは、アプリケーションと認証サーバーだけに知らされる秘密のクレデンシャルです。クライアント ID と組み合わせることで、認証プロセスに追加のセキュリティ層が追加されます。クライアントシークレットは認証フローで使われて、Auth サーバーにアクセストークンをリクエストする際に、アプリケーションを認証します。これにより、正しいクライアントシークレットを有する登録済みの認可アプリケーションのみが、アクセストークンを取得してユーザーを認証できるようになります。クライアントシークレットを秘密に保持することは極めて重要です。認証プロセスのセキュリティを確保するため、クライアント側のコードや公開リポジトリに絶対に公開しないでください。
6:アクセストークンおよびリフレッシュトークンとは何ですか?
アクセストークンとリフレッシュトークンは、安全なアプリケーションでユーザーセッションや API アクセスを管理するために使われる 2 種類のトークンです。
アクセストークンは、API にアクセスするために、認証サーバーから発行される JSON Web Token(JWT)です。このトークンは時間制限があるクレデンシャルで、通常、24 時間有効です。これにより、アプリケーションと API 間で安全に認証された状態でやり取りできるようにします。
リフレッシュトークンも Auth0 によって生成される JSON Web Token(JWT)です。リフレッシュトークンは、API への継続的なアクセスを維持する上で重要な役割を果たします。このトークンは 1 年間有効で、現在のアクセストークンが期限切れになった際に、新しいアクセストークンを安全に取得する手段として機能します。リフレッシュトークンは 1 回限りのクレデンシャルで、一度使用すると更新されたアクセストークンとともに新しいリフレッシュトークンが発行されます。トークンをシームレスかつ安全に管理するため、最新のリフレッシュトークンをシステム内に安全に保管しておくよう推奨します。
7:リフレッシュトークンを使ってアクセストークンを生成するにはどうすればよいですか?
現在のアクセストークンが期限切れになった、または期限切れが近い場合、リフレッシュトークンを使用してアクセストークンを再生成できます。トークンを再生成するには、Authentication API の /oauth/token エンドポイントに対して、grant_type=refresh_token を使って POST リクエストを送信します。リフレッシュトークン機能は、認可コードグラントタイプにのみ対応します。
curl コマンドの例:
curl --request POST \
--url 'https://{apiGatewayHost}/v2/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {base64Encode(clientId:clientSecret)}' \
--data grant_type=refresh_token&refresh_token={token}
8:JWT とは何ですか?
JWT(JSON Web Token)とは、JSON オブジェクト形式で当事者間で情報を安全にやり取りするための、簡潔で自己完結型の手段です。JWT トークンは、認証、認可、情報交換に使用されます。JWT の信頼性は、デジタル署名によって保証されており、転送したデータの完全性と真正性が確保されます。
9:API を呼び出すたびに新しいアクセストークンが必要ですか?
いいえ。理想的には、API 呼び出しごとに新しい JWT トークンを作成すべきではありません。その代わりに、トークンの有効期限を判定し、リフレッシュトークンを使って新しいトークンを生成するコードスニペットを作成することができます。以下に、リフレッシュトークンから新しいアクセストークンを生成する curl の例を示します。
注記:リフレッシュトークンは、グラントタイプ authorization_code にのみ生成されます。
curl --request POST \
--url 'https://{apiGatewayHost}/v2/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {base64Encode(clientId:clientSecret)}' \
--data grant_type=refresh_token&refresh_token={token}
10:アクセストークンが期限切れになっても、API へのシームレスなアクセスを確保するにはどうすればよいですか?
質問 9 の回答を参照してください。
アクセストークンを生成すると、レスポンスのペイロードに expires_at というフィールドが含まれます。API を連携する際は、このフィールドを利用して、トークンが期限切れになる前、または期限切れが近づいたタイミングで新しいトークンを条件付きで再生成できます。
11:「提供されたトークンにこのリソースにアクセスする適切な権限がありません」というエラーが出ました。なぜですか?
アクセストークンに制限が発生した場合には、トークンに特定の機能やデータにアクセスするために必要な権限(スコープ)がない可能性があります。この問題への対処方法:
アクセストークンの権限を確認する:
アクセストークンには、権限を定義するスコープが含まれています。トークンのスコープを確認すると、実施できる操作を把握できます。
権限の確認方法
JSON Web Tokens(JWT)をデコードする信頼性の高いツール jwt.io にアクセスします。
アクセストークンをデコーダに貼り付けます。権限の配列も含めて、トークン情報がデコードされます。
権限の例:
例えば、トークンに read:font:data、read:font:pair、read:font:preview、read:font:similar などの権限が含まれることがあります。
次のステップ:
必要な権限が不足している場合には、適切なスコープがある更新したトークンをリクエストする必要があります。
必要な権限や追加の権限をリクエストする方法がわからない場合は、当社サポートチームまでお問い合わせください。
12:エラーレスポンスに含まれる GUID はどのような目的に使われますか?
「インスタンス」フィールドの GUID は、一意の識別子として機能し、当社のシステム内で、エラースタックおよび詳細を正確に特定します。エラー報告時にこの GUID を添えると、発生した問題の解決に、より効果的で、対象を絞ったサポートを提供できるようになります。
注記:サポートの依頼時にこの識別子を共有すると、迅速で正確な解決が促進されます。
一般的なエラーコードのリストはこちらからご覧ください:https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
13:レート制限とは何ですか?API 呼び出しでレート制限エラーが発生するのはなぜですか?
レート制限とは、一定の時間内に実行可能な API 呼び出しの上限を定義する閾値です。この上限を超えると、レート制限エラーが返されます。レート制限エラーが発生した場合、ユーザーアカウントから送信された API リクエスト数が指定の時間枠内で当社ポリシーに規定された上限を超えたということです。
14:フォントのインポート時に「申し訳ありませんが、この機能はクライアントクレデンシャルではサポートされていません。authorization_code グラントタイプによるユーザー固有のトークンをリクエストしてください」というエラーが表示されました。なぜですか?
フォントのインポート機能は、ユーザー固有のトークン(grant_type=authorization_code で生成されたアクセストークン)を使用した場合にのみ利用可能です。grant_type=client_credentials のアクセストークンには、フォントダウンロード API に必要な権限(スコープ)がありません。
15:マイライブラリのフォントに「申し訳ありませんが、この機能はクライアントクレデンシャルではサポートされていません。authorization_code グラントタイプによるユーザー固有のトークンをリクエストしてください」というエラーが表示されました。なぜですか?
フォントライブラリの API 機能は、ユーザー固有のトークン(grant_type=authorization_code で生成されたアクセストークン)を使用した場合にのみ利用可能です。grant_type=client_credentials のアクセストークンには、この API を利用するために必要な権限(スコープ)がありません。
16:自分の CDN でフォントをホストして、本番環境のサイトでその CDN を使うことができますか?
特にパブリック CDN では、自分の CDN(コンテンツ配信ネットワーク)の使用は控えるべきです。本番環境でフォントファイルを取得して使用するには、Monotype の CDN を使用するよう推奨します。
17:クライアントのリクエストに応じて、フォントファイルを効率的にホスティング・配信するために、サーバーサイドのキャッシュ戦略を実装することは可能ですか?
サーバーサイドのキャッシュは、さまざまなコンテンツ配信の最適化に活用できますが、フォントファイルのホスティングと配信には推奨しません。その代わりに、Monotype の CDN(コンテンツ配信ネットワーク)の使用を推奨します。これにより、フォントファイルの配信で効率が高まり、セキュリティ層が追加されます。Monotype の CDN を使用すると、業界のベストプラクティスに人事手フォントファイルを配信することができます。ただし、この推奨事項の適用可能性は、貴社とのビジネス契約の特定の条件により異なることがあるので、注意が必要です。より調整された方法の詳細や契約条件との整合性を確認するには、当社のビジネスチームにご相談ください。