認証ガイド

統合開発用の Bluebeam Developer Portal は、米国、オーストラリア、ドイツ、英国、およびスウェーデンの各地域におけるアクティブな契約ユーザー、チャネルパートナー、およびソフトウェアパートナーのみが利用できます。

すべての Bluebeam API エンドポイントへのリクエストは認証される必要があります。アプリはOAuth 2.0を使用して Bluebeam に接続します。このガイドでは、アプリでユーザーに代わって認証するためのaccess_tokenを取得する方法を説明します。

認証プロセスを開始する前に、必ず次の操作を行ってください。

アプリを登録する
リダイレクトURIを指定する
クライアントIDとシークレットを保存する

上記の手順をまだ実行していない場合は、 Bluebeam Developer Portalの「開始する」ページにアクセスして詳細を確認してください。

すべてのエンドポイントに適用されるリージョン固有のベース URL があります。

たとえば、米国のhttps://api.bluebeam.com/publicapi/v1/sessions は、オーストラリアではhttps://api.bluebeamstudio.com.au/publicapi/v1/sessionsになります。

認証コードフロー

アプリが秘密を保持できる場合（たとえば、アプリがユーザーが管理する Web サーバー上で実行される場合）のみ、認証コード認証を使用します。client_secretパスワードと同じように扱うようにしてください。

1. ユーザーを認可エンドポイントにリダイレクトする

最初のステップは、アプリのユーザー認証を要求することです。ユーザーを認証エンドポイントにリダイレクトし、そこで Studio の資格情報を使用してログインし、アプリに権限を付与するよう求められます。これを行うには、次のパラメータを使用して Authorization エンドポイントにGETリクエストを送信します。

認証エンドポイント

コピー

https://api.bluebeam.com/oauth2/authorize

リクエストパラメータ

パラメータはクエリ文字列で渡す必要があります。

名前	説明
`response_type`	`code`に設定する必要があります
`client_id`	アプリ登録プロセス中に受け取ったクライアントID（マイアプリを参照）
`redirect_uri`	アプリ登録プロセス中に指定されたリダイレクト URI（マイアプリを参照）
`scope`	Studio エンドポイントにのみ適用されます。Studio エンドポイントスコープのリスト (スペース区切り) については、以下の表を参照してください。
`state`	アプリによって生成されたランダムな文字列。Studio は、この状態をコールバックで`redirect_uri`に返します。クロスサイトリクエストフォージェリを防ぐために、アプリ内の状態と照らし合わせて検証します。

Studio エンドポイントのスコープ

スコープ名	説明
`read_prime`	レポート用のユーザーの Studio プロジェクトと Studio セッションへの読み取り専用アクセス
`full_user`	ユーザーが所有するStudio プロジェクトとStudio セッションへのフルアクセス
`jobs`	Studio プロジェクトで自動化されたジョブにアクセスする
`offline_access`	refresh_token を受け取るにはこのスコープをリクエストしてください

リフレッシュトークン
refresh_token を受け取るには、リクエストで必ず 'offline_access' スコープをリクエストしてください。refresh_tokens の詳細については、以下の手順 4 を参照してください。

スコープの選択に関するメモ
スコープを選択するときは、アプリがアクセスする必要があるデータ部分を考慮してください。セキュリティリスクを最小限に抑えるには、必要最小限のスコープだけをリクエストしてください。

リクエストの例

コピー

GET https://api.bluebeam.com/oauth2/authorize?response_type=code&client_id=b5f9fc7c-60dd-469f-a21e-3f4a7ceb874b&redirect_uri=http://myserver.com&scope=full_prime offline_access jobs&state=myteststate

ユーザーエクスペリエンス

ユーザーは Bluebeam ログインページに移動します。

ログイン後、ユーザーは「アクセスを許可」を選択して、アプリに自分のデータへのアクセスを許可することができます。

2. Bluebeamは認証コードを使用してURLにリダイレクトします

ユーザーが[アクセスを許可]を選択してアプリへのアクセスを許可すると、元のリクエストのredirect_uriで指定された URL へのコールバックが送信されます。コールバックが成功した場合、 access_tokenと交換する必要がある認証codeが含まれます。応答内のstateが元のリクエストで送信した状態と一致していることを確認してください。エラーが発生した場合は、 errorパラメータを含むリダイレクトが送信されます。

応答パラメータ

パラメータはクエリ文字列の一部として受け取られます。

名前	説明
`code`	`access_token`と交換する必要がある一時的な認証コード
`state`	アプリによって生成されたランダムな文字列。Bluebeam は、この状態をコールバックで`redirect_uri`に返します。クロスサイトリクエストフォージェリを防ぐために、元のリクエストの状態と照らし合わせて検証します。
`error`	この現場には、承認要求が失敗した場合のエラーコードが含まれます。承認および認証エラーの一般的な HTML 応答コードを参照してください。

回答例

コピー

https://www.myserver.com/?code=acf3cabd-08c1-44db-88a9-4f785ec7c6ec&state=myteststate

セキュリティガイドライン
リダイレクトプロセスの一環として、認証コードがユーザーに表示されないことを確認してください。

認証コードは5分間のみ有効です。コードとトークンの有効期間の一覧については、「トークンの有効期限」を参照してください。

3. アクセストークンの交換コード

認証codeを受け取ったら、次のステップはそれを Bluebeam からのaccess_tokenと交換することです。これを行うには、以下のパラメータを使用してトークンエンドポイントにPOSTリクエストを送信します。

トークンエンドポイント

コピー

https://api.bluebeam.com/oauth2/token

リクエストパラメータ

パラメータはフォームエンコードされる必要があります。

名前	説明
`grant_type`	`authorization_code`に設定する必要があります
`code`	前のステップで返された認証コード
`client_id`	アプリ登録プロセス中に受け取ったクライアントID（マイアプリを参照）
`client_secret`	アプリ登録プロセス中に受け取ったクライアントシークレット（「マイアプリ」を参照）
`redirect_uri`	アプリ登録プロセス中に指定されたリダイレクト URI（マイアプリを参照）
`scope`	スペースで区切られたスコープを含める

cURLの例

コピー

curl [https://api.bluebeam.com/oauth2/token](https://api.bluebeam.com/oauth2/token) \
-d grant_type=authorization_code \
-d code={code returned from previous step} \
-d redirect_uri={your redirect_uri} \
-d client_id={your client_id} \
-d client_secret={your client_secret} \
-d scope= offline_access {your requested scopes} \
-X POST

回答例

コピー

{
  "token_type":"Bearer",
  "expires_in":3600,
  "access_token":"eyJraWQiOiIybEczWnV2Q1pHRDFQX0FYclk4U0YyVVdmU2x3WHFpNWxZcUFzaHc4M05rIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULjJ0Ml9nQWtxc2RvcDFWcWR1ajdLVUZwbXdNT1ZvU1VxcmZWVm5TOUZuMU0iLCJpc3MiOiJodHRwczovL3NpZ25pbi5ibHVlYmVhbS5jb20vb2F1dGgyL2F1c2JlcGh2azBlYkk3T09UNHg3IiwiYXVkIjoiYXBpOi8vYmItYWNtIiwiaWF0IjoxNzA4OTcwMzM2LCJleHAiOjE3MDg5NzM5MzYsImNpZCI6IjBvYWc2aGFjYWhnRUtqM0loNHg3IiwidWlkIjoiMDB1YngyeThtMDlwelVKRms0eDciLCJzY3AiOlsiZnVsbF9wcmltZSJdLCJhdXRoX3RpbWUiOjE3MDg5NzAzMTcsInN1YiI6InRvcnlhZGFtc0BwbS5tZSIsImJiaWQiOiJkNzE3MGZmYy03ZjlmLTQxZjYtOTY2ZS0xOTg1NTJlNzQwOTAifQ.S8m-cIfq8m19GtJ67skC8WM4bMWvJbAAr74A7g3HrUmH66M1_MN4MaDWjgcYjNFOI1zWsiZ5qm1HODLYY92lgUfzGuiYnkvpiJEKBtIUzLec2E2uEGE5HuW6FbyiX_SdGnSKeHlTr_FfiWGcpTYF816rI6q72kFm2J_3pKA-z_6REkNhI7qouRDRIHqT88tOE9KcjrF8_HsRAuixYAOlcGoVq3rvupvNVVaekoLyGiGWovXdJ-Wrx-1pKo0r7px2_Y8ew9OWEgYCX0u8pQvvPB6HAfF8dNCGTz_jFw9MbItu70rIniDoycILZKNxOcdKTLsCK7AC5doBcg9dV0OrHQ",
  "scope":"full_user offline_access",
  "refresh_token":"f5Mj16b7eVXwlY3Axc7TH2oEG_FPV1BrY05ht0uin6B"
}

応答パラメータ

名前	説明
`token_type`	これは常に「Bearer」になります
`expires_in`	トークンの有効期限までの時間（秒）
`access_token`	ユーザーに代わってリクエストを行うために使用されるベアラートークン
`refresh_token`	ユーザーに再度サインインを要求することなく、新しい access_token および refresh_token と交換できます。
`scope`	要求されたスコープのスペース区切りリスト

4. アクセストークンとリフレッシュトークンを使用してAPIにアクセスする

access_tokenを受け取ったら、それを使用して API にアクセスできます。access_tokenを使用するには、それを Authorization ヘッダーに含めます。

コピー

Authorization: Bearer {a valid access_token}

認証ヘッダーを送信するときは、「Bearer」の「B」が大文字になっていることを確認してください。「Bearer」が大文字でない場合、エラーが発生します。

アクセストークン

access_token 、ユーザーに代わってリクエストを行うことを可能にする実際の文字列です。Bluebeam API へのすべてのリクエストには、有効なaccess_tokenが含まれている必要があります。

各access_tokenは 60 分間有効です。access_token有効期限が切れた後、有効なrefresh_tokenを交換することで、ユーザーに再度ログインを要求することなく新しいaccess_tokenを発行できます。

リフレッシュトークン

リフレッシュトークンの目的
リフレッシュトークンは、ユーザーがリクエストごとにサインインする必要なく、Bluebeam API への認証済みリクエストを実行するための便利で安全な方法です。
リフレッシュトークンは常に、1) 1 時間有効な access_token と、2) 少なくとも 7 日間に 1 回使用される限り有効なままになる新しい refresh_token と交換されます。
理論的には、ステップ 1 でユーザーが手動でアクセスを許可すると、有効なリフレッシュトークンをアクセストークンと継続的に交換できるため、少なくとも 7 日ごとに 1 回リフレッシュトークンを交換している限り、ユーザーは再度手動で承認する必要がなくなります。

最初のrefresh_token取得するには、手順 1 でoffline_accessスコープをリクエストして、 refresh_tokenも受け取ることをお勧めします。

最後のaccess_tokenを取得してから 3600 秒以内に、 refresh_token新しいaccess_tokenに交換します。refresh_token access_tokenと交換すると、新しいrefresh_tokenが発行されます。

1 時間後に期限切れになるaccess_tokenとは異なり、 refresh_tokenは、少なくとも 7 日間に 1 回使用される限り、無期限に有効です。refresh_token 7 日以内に使用されない場合は無効になります。

refresh_tokenを暗号化して安全な場所に保管します。refresh_tokenが紛失または期限切れになった場合は、OAuth フローの最初から再度認証するようにユーザーに依頼する必要があります。

refresh_token新しいaccess_tokenおよびrefresh_tokenと交換するには、トークンエンドポイントにPOSTリクエストを送信します。

トークンエンドポイント

コピー

https://api.bluebeam.com/oauth2/token

セキュリティガイドライン
ヘッダーには、base64 エンコードされた文字列 "{your client_id}:{your client_scret}" を含めます。— コロンはスペースなしで存在する必要があることに注意してください。以下の例をご覧ください。

リクエストパラメータ

パラメータはフォームエンコードされる必要があります。

名前	説明
`grant_type`	`refresh_token`に設定する必要があります
`refresh_token`	承認呼び出し中に返される値に設定する必要があります

cURLの例

コピー

curl [https://api.bluebeam.com/oauth2/token](https://api.bluebeam.com/oauth2/token) \
-H Content-Type: application/x-www-form-urlencoded \
-H Authorization: Basic {base64 encoded string of client_id:client_secret} \ 
-d grant_type=refresh_token \
-d refresh_token={your refresh_token} \
-X POST

セキュリティガイドライン
refresh_token をパスワードのように扱います。暗号化された状態で安全な場所に保存する必要があります。

リフレッシュトークンの取り消し
リフレッシュトークンは取り消すことができます。refresh_token が取り消されると、現在の access_token の有効期限が切れた後にユーザーは再認証が必要になります。

トークンの有効期限

認証コードは 5 分後に期限切れになります。
アクセストークンは 60 分後に期限切れになります。
リフレッシュトークンは、7 日間に 1 回以上使用しないと期限切れになります。

承認および認証エラー

どのようなエラーが発生したかをお知らせいただければ、問題の解決をお手伝いいたします。

一般的なHTMLレスポンスコード

HTTPコード	メッセージ	意味
200	OK	リクエストは成功しました。
201	作成済み	リクエストは成功し、新しいリソースが作成されました。
204	コンテンツなし	サーバーはリクエストを満たしたため、エンティティ本体を返す必要はありません。
400	要求の形式が正しくありません	構文が不正なため、要求を理解できませんでした。
401	不正な	リクエストにはユーザー認証が必要です。access_token を渡した後にこれを受け取った場合は、新しい access_token を取得してみてください。それでも 401 が表示される場合は、スコープを確認してください。401 が引き続き表示される場合は、integrations@bluebeam.com のサポートにお問い合わせください。
403	禁断	サーバーはリクエストを理解しましたが、それを実行することを拒否しています。
404	未検出	サーバーは、Request-URI に一致するものを見つけられませんでした。
409	競合	リソースの現在の状態との競合のため、要求を完了できませんでした。

参照:

リソース

Revu 21

Developer Portal

このDeveloper Portalガイドでは、手元のアプリからaccess_tokenを取得して、ユーザーに代わって認証を行う方法について説明します。