Authentifizierung – Leitfaden

Der erste Schritt besteht darin, eine Benutzerautorisierung für Ihre App anzufordern. Sie leiten Benutzer:innen zum Autorisierungsendpunkt um, wo sie aufgefordert werden, sich mit ihren Studio-Anmeldedaten anzumelden und Berechtigungen für Ihre App zu erteilen. Senden Sie dazu eine get-Anfrage mit den folgenden Parametern an den Autorisierungsendpunkt.

Autorisierungsendpunkt

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

Parameter anfordern

Parameter müssen in einer Anfragezeichenfolge übergeben werden.

Leistungsumfänge für Studio-Endpunkte:

Aktualisieren Sie Token
Stellen Sie sicher, dass Sie den Bereich „offline_access“ in Ihrer Anfrage anfordern, um ein Update zurück zu erhalten. Weitere Informationen zu aktualisieren_tokens finden Sie unten im 4. Schritt.

Beispielanfrage

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

Benutzererfahrung

Benutzer:innen werden zur Anmeldeseite von Bluebeam weitergeleitet.

Nach der Anmeldung können Benutzer:innen Zugriff erlauben, um Ihrer App Zugriff auf ihre Daten zu gewähren.

Wenn der Benutzer Zugriff auf Ihre App gewährt, indem er „Zugriff erlauben“auswählt, erhalten Sie einen Rückruf an die URL, die in Ihrer ursprünglichen Anfrage durch redirect_uri angegeben wurde. Wenn der Rückruf erfolgreich war, enthält er einen Autorisierungscode, den Sie gegen einen access_token austauschen müssen. Stellen Sie sicher, dass der Status in der Antwort mit dem Status übereinstimmt, den Sie in der ursprünglichen Anfrage eingereicht haben. Wenn ein Fehler aufgetreten ist, erhalten Sie die Umleitung mit Fehlerparameter.

Antwortparameter:

Parameter werden als Teil der Anfragezeichenfolge empfangen.

Beispielantwort

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

Der Autorisierungscode ist nur 5 Minuten gültig. Eine Liste der Codes und der Gültigkeitsdauer von Token finden Sie unter Ablaufdaten von Token.

Nachdem Sie nun den Autorisierungscode erhalten haben, müssen Sie diesen gegen einen access_token von Bluebeam eintauschen. Stellen Sie dazu eine POST-Anfrage mit den unten angegebenen Parametern an den Endpunkt des Tokens.

Token-Endpunkt

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

Parameter anfordern

Parameter müssen formkodiert sein.

cURL-Beispiel

1
2
3
4
5
6
7
8
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

Beispielantwort

1
2
3
4
5
6
7
{
  "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"
}

Antwortparameter:

Sobald Sie ein access_token erhalten haben, können Sie damit auf die API zugreifen. Um ein access_token zu verwenden, müssen Sie es in die Kopfzeile „Autorisierung“ einfügen:

1
Authorization: Bearer {a valid access_token}

Stellen Sie beim Senden der Autorisierungsüberschrift sicher, dass das „B“ in „Bearer“ großgeschrieben wird. Wenn „Bearer“ nicht großgeschrieben wird, erhalten Sie eine Fehlermeldung.

Auf Token zugreifen

Ein access_token ist die eigentliche Zeichenfolge, die es Ihnen ermöglicht, im Namen des Benutzers Anfragen zu stellen. Jede Anfrage an die Bluebeam API muss einen gültigen access_token enthalten.

Jeder Access_Token ist 60 Minuten gültig. Nach Ablauf eines access_tokens kann ein neuer access_token ausgestellt werden, ohne dass sich der Benutzer durch den Austausch eines gültigen updates_tokens erneut anmelden muss.

Aktualisieren Sie Token

Der Zweck von Aktualisierungstoken
Aktualisierungstoken sind eine praktische und sichere Möglichkeit, authentifizierte Anfragen an die Bluebeam API zu stellen, ohne dass Benutzer:innen sich für jede Anfrage erneut anmelden müssen.
Aktualisierungstoken werden immer gegen 1) einen access_token, der 1 Stunde gültig ist, und 2) einen neuen updates_token, der gültig bleibt, solange er mindestens einmal alle sieben Tage verwendet wird, eingetauscht.
Wenn Sie einem Benutzer in Schritt 1 manuell Zugriff gewähren, können Sie theoretisch kontinuierlich gültige Aktualisierungstoken gegen Zugriffstoken austauschen, sodass der Benutzer nie wieder eine manuelle Autorisierung vornehmen muss, vorausgesetzt, Sie tauschen Aktualisierungstoken mindestens alle sieben Tage aus.

Um Ihren ersten aktualisieren_token zu erhalten, empfehlen wir Ihnen, in Schritt 1 den Bereich „offline_access“ anzufordern, damit Sie auch einen updates_token erhalten.

Tauschen Sie Ihren Update-Token innerhalb von 3.600 Sekunden nach Erhalt des letzten Access-Tokens gegen einen neuen Access-Token aus. Wenn Sie einen Update-Token gegen einen Access-Token austauschen, wird Ihnen ein neuer Aktualisierungs-Token angezeigt.

Im Gegensatz zum access_token, das nach 1 Stunde abläuft, bleibt das activation_token unbegrenzt gültig, solange es mindestens alle sieben Tage verwendet wird. Ein Update_Token wird ungültig, wenn er nicht innerhalb von sieben Tagen verwendet wird.

Speichern Sie den Aktualisierungs_Token verschlüsselt an einem sicheren Ort ab. Wenn ein Update Token verloren geht oder abgelaufen ist, müssen Sie die Benutzer:innen vom Beginn des OAuth-Flusses an erneut um eine Autorisierung bitten.

Um einen aktueller_Token gegen einen neuen access_token und einen aktualisieren_Token auszutauschen, stellen Sie eine POST-Anfrage an den Endpunkt des Tokens:

Token-Endpunkt

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

Parameter anfordern

Parameter müssen formkodiert sein.

cURL-Beispiel

1
2
3
4
5
6
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

Aktualisierungstoken werden zurückgenommen
Aktualisierungstoken können widerrufen werden. Wenn ein Update-Token widerrufen wurde, müssen Benutzer sich nach Ablauf des aktuellen Access-Tokens erneut autorisieren.