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

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

SAML поддерживает среду с системой единого входа (SSO). Используя SAML с Edge, вы можете поддерживать SSO для интерфейса и API Edge, а также для любых других сервисов, которые вы предоставляете и которые также поддерживают SAML.

Требование. Чтобы использовать SAML для доступа к Edge API, необходимо включить SAML хотя бы для одной организации.

Различия между SAML и OAuth2

После настройки SAML ее использование будет очень похоже на использование OAuth2 для доступа к Edge API. При вызове Edge API в запрос включается токен доступа OAuth2.

Основное различие между SAML и OAuth2 при доступе к API Edge заключается в способе получения токенов. При использовании SAML при получении пары токенов необходимо указать следующие данные:

  1. Зоны. Пользователи Edge для общедоступного облака должны указывать название зоны при получении токенов.
  2. Код доступа. Включите одноразовый код доступа при запросе пары токенов доступа и обновления.

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

Чтобы получить токены доступа с помощью SAML, можно использовать один из следующих методов, описанных в этом разделе:

Кроме того, вы можете автоматизировать процесс создания токенов для пользователей-машин, как описано в разделе Автоматизация процесса создания токенов.

Как получить токены доступа с помощью get_token

Вы можете использовать утилиту get_token, чтобы обменять свои учетные данные на токены доступа и обновления OAuth2, которые используются с SAML.

Как получить токен доступа с помощью get_token

  1. Установите для переменной среды SSO_LOGIN_URL URL для входа. URL для входа имеет следующий формат: 
    https://zoneName.login.apigee.com

    Например, для зоны с названием acme задайте для параметра SSO_LOGIN_URL значение https://acme.login.apigee.com, как показано в следующем примере:

    export SSO_LOGIN_URL=https://acme.login.apigee.com
  2. Вызовите get_token, чтобы получить токен доступа OAuth2: 
    get_token -u me@example.com

    Вам будет предложено перейти по указанному URL, чтобы получить одноразовый код доступа:

    Get passcode from https://acme.login.apigee.com/passcode
[Note:  Passcode can be used only time time and expires] Input passcode (no spaces) and then press ENTER:

    Если вы недавно не входили в аккаунт через поставщика идентификационной информации, вам будет предложено это сделать.

    Этот URL возвращает одноразовый код доступа, который действителен, пока вы не обновите URL, чтобы получить новый код, или не используете код с get_token для создания токена доступа. Пример:

  3. Введите код доступа. Утилита get_token получает токены OAuth2, печатает токен доступа в stdout и записывает токены доступа и обновления в ~/.sso-cli.

  4. Вызовите Edge API и передайте токен доступа в заголовке Authorization: Bearer, как показано в следующем примере: 
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

    Значение токена доступа можно скопировать из stdout.

    В этом примере показано, как получить информацию об указанной организации. Полный список конечных точек API управления приведен в справочнике по Apigee Edge API.

Когда срок действия токена доступа истечет, вы можете снова вызвать функцию get_token, чтобы получить новый токен доступа. Пример:

get_token -u me@example.com

Запрос на новый код доступа появится только после того, как истечет срок действия токена обновления.

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

Как получать токены доступа с помощью сервиса Edge OAuth2

Вы можете использовать сервис Edge OAuth2, чтобы получать токены доступа, которые используются с SAML. Чтобы пройти аутентификацию в Edge API, вы используете код доступа в первом запросе, чтобы получить пару токенов доступа и обновления, а затем снова, чтобы получить новую пару токенов.

Чтобы получить пару токенов с помощью API Edge:

  1. В браузере перейдите по следующему URL, чтобы получить одноразовый код доступа: 
    https://zoneName.login.apigee.com/passcode

    Например, для зоны с названием "acme" перейдите по следующему URL:

    https://acme.login.apigee.com/passcode

    Если вы недавно не входили в аккаунт через поставщика идентификационной информации, вам будет предложено это сделать.

    Этот URL возвращает одноразовый код доступа, который действует как ваши учетные данные для получения токенов. Он остается действительным, пока вы не обновите URL, чтобы получить новый код доступа, или пока вы не используете код доступа с get_token для создания токена доступа. Пример:

  2. Отправьте запрос к Edge API, как показано в следующем примере: 
    curl https://zoneName.login.apigee.com/oauth/token \
      -s \
      -H "Accept: application/json" \
      -d 'grant_type=password&response_type=token&passcode=passcode'

    passcode – это ваши учетные данные для авторизации.

    Где:

    • Заголовок Authorization должен иметь значение "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (используйте именно его).
    • Тип запроса – POST.
    • Тело запроса содержит следующие данные:
      • grant_type – "пароль".
      • response_type – "токен".
      • passcode, где passcode – код доступа, полученный на предыдущем шаге.

    В результате вызова на экране будут показаны токен доступа и токен обновления.

Чтобы обновить токен доступа:

Отправьте запрос https://zoneName.login.apigee.com/oauth/token, как показано в следующем примере:

curl https://zoneName.login.apigee.com/oauth/token \
      -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

Где:

  • Тело запроса содержит следующие данные:
    • grant_type – "refresh_token".
    • refresh_token – значение токена обновления.
  • Заголовок Authorization должен иметь значение "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (используйте именно его).
  • Тип запроса – POST.

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

Для доступа к Edge API можно использовать такие инструменты, как curl или утилиту Apigee acurl.

С помощью curl вы вызываете Edge API и передаете токен доступа в заголовке Authorization: Bearer, как показано в следующем примере:

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

При использовании acurl указывать заголовок Authorization не нужно. Пример:

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

В этих примерах вызывается конечная точка Edge API, которая получает информацию об указанной организации. Полный список конечных точек Edge API приведен в справочнике по Apigee Edge API.

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

Пользователи компьютеров в зонах SAML

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

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

В приведенном выше примере, если для параметра -m задать пустую строку, пользователю устройства не будет предложено ввести код многофакторной аутентификации. Использование флага --force-basic-auth переопределит стандартный запрос кода доступа, который активируется запросами с зонами SAML.

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

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