Как использовать OAuth2 для доступа к Edge API

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Apigee Edge позволяет выполнять вызовы API Edge, которые аутентифицируются с помощью токенов OAuth2. Поддержка OAuth2 включена по умолчанию в аккаунтах Edge для облачных сервисов. Если вы используете Edge для частного облака, то не сможете использовать OAuth2, не настроив SAML или LDAP.

Как работает OAuth2 (с Apigee Edge API)

Для вызовов Apigee Edge API требуется аутентификация, чтобы мы могли убедиться, что вы тот, за кого себя выдаете. Чтобы аутентифицировать вас, мы требуем, чтобы вместе с запросом на доступ к API отправлялся токен доступа OAuth2.

Например, если вы хотите получить информацию об организации в Edge, отправьте запрос на URL, подобный следующему:

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

Но вы не можете просто отправить запрос, не указав, кто вы. В противном случае любой пользователь сможет увидеть информацию о вашей организации.

Для аутентификации вам нужно отправить нам в запросе токен доступа. Токен доступа позволяет нам узнать, кто вы, и убедиться, что вам разрешено просматривать информацию об организации.

К счастью, вы можете получить токен, отправив свои учетные данные в сервис Edge OAuth2. Сервис отвечает токенами доступа и обновления.

Процесс OAuth2: первоначальный запрос

На изображении ниже показан поток OAuth2 при первом доступе к Edge API:

Процесс OAuth: первый запрос
Рисунок 1. Использование протокола OAuth: первый запрос

Как показано на рисунке 1, при отправке первого запроса к Edge API:

  1. Вы запрашиваете токен доступа. Это можно сделать с помощью Edge API, acurl или get_token. Пример: 
    get_token
Enter username:
ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
123456
  2. Сервис Edge OAuth2 отвечает токеном доступа и выводит его в stdout, например: 
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    Утилиты acurl и get_token автоматически сохраняют токены доступа и обновления в ~/.sso-cli (токен обновления не записывается в stdout). Если вы используете сервис Edge OAuth2 для получения токенов, вам нужно сохранить их самостоятельно, чтобы использовать в дальнейшем.

  3. Вы отправляете запрос к Edge API с токеном доступа. acurl автоматически добавляет токен, например: 
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    Если вы используете другой HTTP-клиент, добавьте токен доступа. Пример:

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
  4. API Edge выполняет ваш запрос и обычно возвращает ответ с данными.

Процесс OAuth2: последующие запросы

В последующих запросах вам не нужно будет обменивать учетные данные на токен. Вместо этого вы можете указать имеющийся токен доступа, если срок его действия ещё не истек:

Процесс OAuth: последующие запросы
Рисунок 2. Использование протокола OAuth: последующие запросы

Как показано на рисунке 2, если у вас уже есть токен доступа:

  1. Вы отправляете запрос к Edge API с токеном доступа. acurl автоматически прикрепляет токен. Если вы используете другие инструменты, токен нужно добавить вручную.
  2. API Edge выполняет ваш запрос и обычно возвращает ответ с данными.

Протокол OAuth2: когда истекает срок действия токена доступа

Когда срок действия токена доступа истекает (через 12 часов), вы можете использовать токен обновления, чтобы получить новый токен доступа:

Использование протокола OAuth: обновление токена доступа
Рисунок 3. Протокол OAuth: обновление токена доступа

Как показано на рисунке 3, когда срок действия токена доступа истекает:

  1. Вы отправляете запрос к Edge API, но срок действия вашего токена доступа истек.
  2. API Edge отклоняет ваш запрос как неавторизованный.
  3. Вы отправляете токен обновления в сервис OAuth2 Edge. Если вы используете acurl, это происходит автоматически.
  4. Сервис Edge OAuth2 отвечает новым токеном доступа.
  5. Вы отправляете запрос к Edge API с новым токеном доступа.
  6. API Edge выполняет ваш запрос и обычно возвращает ответ с данными.

Как получить токены

Чтобы получить токен доступа, который можно отправить в Edge API, вы можете использовать следующие утилиты Apigee, а также утилиту, например curl:

  • Утилита get_token обменивает учетные данные Apigee на токены доступа и обновления, которые можно использовать для вызова Edge API.
  • Утилита acurl. Удобный контейнер для стандартной команды. curl Создает HTTP-запросы к Edge API, получает токены доступа и обновления от get_token и передает токен доступа в Edge API.
  • Конечные точки токенов в сервисе Edge OAuth2. Обменяйте учетные данные Apigee на токены доступа и обновления, вызвав Edge API.

Эти утилиты обменивают учетные данные аккаунта Apigee (адрес электронной почты и пароль) на токены со следующими сроками действия:

  • Срок действия токенов доступа – 12 часов.
  • Срок действия токенов обновления составляет 30 дней.

Таким образом, после успешного вызова API с использованием acurl или get_token вы можете продолжать использовать пару токенов в течение 30 дней. После истечения срока действия вам нужно будет повторно ввести учетные данные и получить новые токены.

Как получить доступ к Edge API с помощью OAuth2

Чтобы получить доступ к Edge API, отправьте запрос к конечной точке API и добавьте токен доступа. Это можно сделать с помощью любого HTTP-клиента, в том числе утилиты командной строки, такой как curl, браузерного интерфейса, такого как Postman, или утилиты Apigee, такой как acurl.

Доступ к Edge API с помощью acurl и curl описан в следующих разделах.

Как использовать acurl

Чтобы получить доступ к Edge API с помощью acurl, в первом запросе необходимо указать учетные данные. Сервис Edge OAuth2 отвечает токенами доступа и обновления. acurl сохраняет токены локально.

При последующих запросах acurl использует сохраненные токены в ~/.sso-cli, поэтому вам не нужно снова указывать учетные данные, пока токены не станут недействительными.

В примере ниже показан исходный запрос acurl, который получает информацию об организации ahamilton-eval:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

В этом примере, помимо получения информации об организации, показан второй запрос, который позволяет получить список правил в прокси-сервере API helloworld. Во втором запросе в URL используется сокращение "o" вместо "organizations".

Обратите внимание, что acurl автоматически передает токен доступа во втором запросе. Вам не нужно передавать учетные данные пользователя после того, как acurl сохранит токены OAuth2. Он получает токен от ~/.sso-cli для последующих вызовов.

Подробнее о том, как использовать acurl для доступа к Edge API…

Как использовать curl

Вы можете использовать curl для доступа к Edge API. Для этого сначала нужно получить токены доступа и обновления. Вы можете получить их с помощью утилиты, например get_token, или сервиса Edge OAuth2.

После того как вы сохраните токен доступа, передайте его в заголовке Authorization вызовов Edge API, как показано в следующем примере:

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

Срок действия токена доступа составляет 12 часов с момента его выдачи. После истечения срока действия токена доступа токен обновления можно использовать в течение 30 дней, чтобы выпустить другой токен доступа без необходимости вводить учетные данные. Apigee рекомендует запрашивать новый токен доступа только после того, как истечет срок действия токена обновления, а не вводить учетные данные и отправлять новый запрос при каждом вызове API.

Срок действия токена

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

Способ обновления токена доступа зависит от того, какой инструмент вы используете:

  • acurl: никаких действий не требуется. acurl автоматически обновляет токен доступа, когда вы отправляете запрос, содержащий устаревший токен.
  • get_token: вызовите get_token, чтобы обновить токен доступа.
  • Сервис Edge OAuth2. Отправьте запрос, который включает:
    • Токен обновления
    • Параметр формы grant_type имеет значение refresh_token.

OAuth2 для машинных пользователей

Утилиты acurl и get_token позволяют создавать скрипты для автоматического доступа к API Edge с аутентификацией OAuth2 для пользователей-машин. В следующем примере показано, как использовать get_token, чтобы запросить токен доступа, а затем добавить значение токена в вызов curl:

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '')
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

Вы также можете объединить запрос токена и вызов curl с помощью утилиты acurl. Пример:

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'

В обоих примерах, если задать для параметра -m пустую строку, пользователю устройства не будет предложено ввести код многофакторной аутентификации.