Доступ к Edge API с помощью SAML

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

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

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

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

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

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

  1. Зоны: Пользователи Edge for Public Cloud должны указывать имя своей зоны при получении токенов.
  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. Вызовите API Edge и передайте токен доступа в заголовке Authorization: Bearer , как показано в следующем примере:
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

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

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

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

get_token -u me@example.com

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

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

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

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

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

  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 равен "password".
      • response_type — "token".
      • 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 или удобную утилиту acurl от Apigee.

При curl вы вызываете API Edge и передаете токен доступа в заголовке 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 в пустую строку предотвратит запрос на ввод кода многофакторной аутентификации (MFA) для пользователя компьютера. Использование флага --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/...'