ADN Open CIS
Сообщество программистов Autodesk в СНГ

04/07/2016

Основы oAuth API Autodesk Forge - часть 1

Хотя детали могут быть более сложным, основная последовательность использования OAuth на платформе Forge выглядит следующим образом:

  1. Ваше приложение делает вызов HTTP к конечной точке OAuth REST и предоставляет свои учетные данные.
  2. Вашему приложению возвращается маркер.
  3. При проведении последующих HTTP-вызовов к различным API на платформе Forge, ваше приложение включает в заголовок запроса маркер.

Есть целый ряд понятий, с которыми вы должны быть знакомы:

app

"app" - это код, который вы пишете, который вызывает Forge API. Это может быть веб-приложение, процесс на сервере без графического интерфейса, мобильное приложение, или даже встроенное ПО. В Dev Portal, ваше приложение регистрируется в разделе Мои приложения .

Иногда "app" относится к коду; в других случаях, это относится к сущности, зарегистрированной в Dev Portal – это будет ясно из контекста.

При регистрации приложения в Dev Portal, вы выбираете API-интерфейсы, с которыми хотите его связать. В случае потери контроля над учетными данными аутентификации это гарантирует защиту от осуществления вызовов от вашего имени к API, для которых ваше приложение не было разработано.

Зарегистрированное приложение имеет привязанные к его учетным данным "client ID" и "client secret", которые аналогичны имени пользователя и паролю, за исключением того, что вы не выбираете их. Они используются для получения маркера доступа.

client ID

"client ID" – по существу, имя пользователя вашего приложения и может быть найдено в разделе Мои приложения. Это буквенно-цифровая строка длинной 32 символа (например, 5zw90va0UuwMKTnPS5sLsdgZjDkVYXN7), и она передается в качестве значения для параметра запроса client ID и атрибута JSON.

На других платформах, иногда это называют "consumer key" или "API key".

client secret

"client secret" – фактически, пароль вашего приложения и может быть найден рядом с идентификатором клиента в разделе Мои приложения. Это буквенно-цифровая строка из 16 символов (например, 7I6uN1rjneirxiMW), и передается в качестве значения для параметра запроса client_secret.

На других платформах, иногда это называют "consumer secret" или "API secret".

two-legged authentication

Это часто считается типом аутентификации по умолчанию, и является самым простым. Когда ваше приложение должно вызывать API без необходимости доступа к ресурсам, которые требуют разрешений конечного пользователя (например, перевод файлов проекта из одного формата в другой), связь осуществляется непосредственно между вашим приложением и платформой Forge. Конечному пользователю, если таковой имеется, не нужно знать о проверке подлинности или предоставить разрешение приложению, чтобы получить доступ к любым ресурсам.

Такой процесс называется "two-legged", потому что ваше приложение и платформа Forge являются двумя "ногами".

Об общих потоках аутентификации читайте ниже.

three-legged authentication

Когда приложение должно получить доступ к ресурсам, принадлежащим конечному пользователю, этот пользователь должен явным образом предоставить разрешение. В случае веб-приложения типичным механизмом является перенаправление пользователя на страницу входа в систему Autodesk с информацией о том, к каким из ресурсов пользователя он хочет получить доступ. Затем пользователь дает явное согласие, давая знать платформе Forge, что ссылающемуся приложению должен быть предоставлен запрашиваемый доступ. Затем пользователь перенаправляется обратно в приложение, которое может затем получить доступ к необходимым ресурсам.

Такой поток называется "three-legged", потому что ваше приложение, платформа Forge, и конечный пользователь составляют три "ноги" потока.

Об общих потоках аутентификации читайте ниже.

callback URL

В некоторых контекстах ваше приложение должно передать часть потока аутентификации платформе Forge. Например, в three-legged аутентификации для веб-приложения, конечный пользователь приложения перенаправляется на процесс входа в систему Autodesk, так что пользователь может сообщить платформе Forge, что ваше приложение уполномочено действовать от имени пользователя. URL обратного вызова передается потоку входа в систему Autodesk, чтобы сообщить ему, как перенаправить пользователя обратно к вашему приложению.

Callback URL указывается в двух местах. Вы сначала указываете URL обратного вызова для приложения в разделе My Apps. Затем, когда вы перенаправляете пользователя к потоку входа в систему Autodesk, вы можете также указать URL обратного вызова в параметре redirect_uri. Это позволяет использовать различные URL-адреса обратного вызова в разных частях вашего приложения. Все URL обратного вызова сверяются с тем, что указано в информации о вашем приложении, и любое выполнение обратного вызова URL должно соответствовать шаблону зарегистрированного вызова.

Больше информации о взаимосвязи между полем URL обратного вызова и параметром redirect_uri вы можете найти в документации по GET authorize.

Обратите внимание на то, что если ваше приложение не требует three-legged аутентификации, вы можете поместить любое допустимое значение в поле обратного вызова URL при регистрации приложения, так как redirect_uri никогда не будет подтверждено.

authorization code

В three-legged потоке OAuth код авторизации передается через параметр запроса code, когда пользователь перенаправляется обратно в приложение через функцию обратного вызова URL.

Наряду с его идентификатором клиента и секретом, приложение вызывает конечную точку POST gettoken для обмена кода авторизации на маркер доступа.

Код авторизации - это строка из 40 символов (например, wroM1vFA4E-Aj241-quh_LVjm7UldawnNgYEHQ8I).

access token

Маркер доступа (иногда просто "token" или "bearer token") возвращается в конце успешного потока аутентификации. Маркер представляет собой буквенно-цифровую строку из 28 символов, который используется в последующих вызовах API к платформе Forge. Платформа отслеживает, к каким ресурсам маркер имеет право на доступ и разрешает или запрещает доступ во время вызова.

Маркеры имеют ограниченный срок службы и заканчивается по истечении определенного количества секунд.

Вот пример того, как выглядит маркер: GX6OONHlQ9qoVaCSmBqJvqPFUT5i

refresh token

В three-legged контексте было бы очень разрушительными требовать, чтобы конечный пользователь вашего приложения проходил через процесс аутентификации каждый раз, как маркер доступа становится просроченным. Когда ваше приложение получает маркер three-legged аутентификации, он также предоставляет маркер обновления, который может быть использован с конечной точкой POST refreshtoken, чтобы получить новый three-legged маркер доступа без участия пользователя, поместив их через другой процесс аутентификации.

Маркеры обновления являются 42-символьными буквенно-цифровыми строками, которые выглядят следующим образом: SDrclmgQSGyF79wjLqxQeEIjqELf0wE8aMym02PjRy

scopes

Областью видимости является разрешение, которое устанавливается на маркер – контекст, в котором этот маркер может действовать.

Например, маркеру с областью видимости data:read разрешено считывать данные в экосистеме Forge, и он может быть использован с теми конечными точками, которые требуют этой области видимости. Маркерам без этой области видимости будет отказано в доступе к таким конечным точкам. (Индивидуальные ссылочные страницы конечных точек перечисляют требуемые области видимости.)

Области видимости выполняют две основные функции: в three-legged контексте, они выступают в качестве механизма для запроса и обеспечения разрешения действовать от имени конечного пользователя в указанных направлениях. В three-legged и two-legged контекстах, они гарантируют, что если вы потеряете контроль над вашим маркером, он не сможет быть неправильно использован для доступа к ресурсам, для которых он не предназначался.

Больше информации вы можете найти на странице Scopes.

authentication context

За исключением конечных точек OAuth и тех, которые не требуют аутентификации, все конечные точки имеют один из следующих контекстов аутентификации:

app only: Конечная точка принимает либо two-legged или three-legged маркер, но он будет действовать только от имени самого приложения, игнорируя любые разрешения, связанные с конечным пользователем.

user context required: Конечная точка требует three-legged маркер и действует от имени конечного пользователя аутентификации.

user context optional:Если предусмотрен two-legged маркер, конечная точка будет действовать от имени приложения, получая доступ только к тем ресурсам, для которых само приложение имеет разрешение. При наличии three-legged маркера, конечная точка будет действовать от имени конечного пользователя, имея доступ только к тем ресурсам, к которым пользователь имеет разрешение.

Автор перевода: Дмитрий Емельянов

Обсуждение: http://adn-cis.org/forum/index.php?topic=

Опубликовано 04.07.2016
Отредактировано 23.07.2016 в 13:58:07