Как использовать SAML с Edge Management API

Edge for Private Cloud версии 4.17.09

Базовая аутентификация – это один из способов аутентификации при вызовах API управления Edge. Например, вы можете отправить следующий запрос cURL к Edge Management API, чтобы получить информацию о своей организации:

curl -u userName:pWord https://ms_IP_DNS:8080/v1/organizations/orgName

В этом примере вы используете параметр cURL -u для передачи учетных данных базовой аутентификации. Вы также можете передать токен OAuth2 в заголовке Bearer, чтобы выполнить вызовы Edge Management API. Пример:

curl -H "Authorization: Bearer <access_token>" https://ms_IP_DNS:8080/v1/organizations/orgName

После включения SAML вы можете отключить базовую аутентификацию. Если вы это сделаете, все скрипты (скрипты Maven, сценарии командной строки, apigeetool и т. д.), которые используют вызовы Edge Management API с поддержкой базовой аутентификации, перестанут работать. Вам необходимо обновить все вызовы API и скрипты, в которых используется базовая аутентификация, чтобы передавать токены доступа OAuth2 в заголовке Bearer.

Как использовать get_token для получения и обновления токенов

Утилита get_token обменивает ваши учетные данные базовой аутентификации и код доступа на токен доступа и токен обновления OAuth2. Утилита get_token принимает ваши учетные данные и выводит действительный токен доступа. Если токен можно обновить, он будет обновлен и выведен на экран. Если срок действия токена обновления истечет, пользователю будет предложено ввести учетные данные.

Утилита get_token сохраняет токены на диске, чтобы их можно было использовать при необходимости. Он также выводит действительный токен доступа в stdout. После этого вы можете использовать Postman или встроить токен в переменную среды для использования в curl.

Ниже описано, как использовать get_token для получения токена доступа OAuth2, чтобы выполнять вызовы API управления Edge.

  1. Скачайте пакет sso-cli:
    curl http://edge_sso_IP_DNS:9099/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"

    где edge_sso_IP_DNS – IP-адрес DNS-имени компьютера, на котором размещен модуль Edge SSO. Если вы настроили TLS в Edge SSO, используйте https и правильный номер порта TLS.

  2. Распакуйте пакет ssocli-bundle.zip:
    unzip ssocli-bundle.zip
  3. Установите get_token в /usr/local/bin:
    ./install

    Чтобы указать другое местоположение, используйте параметр -b:

    ./install -b path
  4. Задайте для переменной среды SSO_LOGIN_URL URL входа в следующем формате:
    export SSO_LOGIN_URL="http://edge_sso_IP_DNS:9099"

    где edge_sso_IP_DNS – IP-адрес или DNS-имя компьютера, на котором размещен модуль Edge SSO. Если вы настроили TLS в Edge SSO, используйте https и правильный номер порта TLS.

  5. Чтобы получить одноразовый код доступа, перейдите по следующему URL в браузере:
    http://edge_sso_IP_DNS:9099/passcode

    Если вы настроили TLS в Edge SSO, используйте https и правильный номер порта TLS.

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

  6. Вызовите get_token, чтобы получить токен доступа OAuth2:
    get_token -u emailAddress

    где emailAddress – адрес электронной почты пользователя Edge. Вам будет предложено ввести одноразовый код доступа, полученный на шаге 3.

    One Time Code ( Get one at https://edge_sso_IP.com/passcode )
          Enter the passcode if SAML is enabled or press ENTER:

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

    Вы можете ввести код доступа в командной строке, используя команду get_token в следующем формате:

    get_token -u emailAddress -p passcode
  7. Передайте токен доступа в вызов Edge Management API в качестве заголовка Bearer:
    curl -H "Authorization: Bearer access_token"
    https://ms_IP:8080/v1/organizations/orgName

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

    header=`get_token` &&
    curl -H "Authorization: Bearer $header"
    https://ms_IP:8080/v1/o/orgName

    Если токен доступа истек, он автоматически обновляется до тех пор, пока не истечет токен обновления.

После истечения срока действия токена обновления get_token запрашивает новый код доступа. Чтобы сгенерировать новый токен доступа OAuth, необходимо перейти по URL, указанному на шаге 3, и сгенерировать новый код доступа.

Как использовать Management API для получения и обновления токенов

Инструкции по получению и обновлению токенов с помощью Edge Management API приведены в статье Using OAuth2 security with the Apigee Edge management API (Использование OAuth2 с Apigee Edge Management API). Вы также можете использовать вызовы Edge API для токенов, сгенерированных из утверждений SAML.

Единственное различие между вызовами API, описанными в статье Использование безопасности OAuth2 с API управления Apigee Edge, заключается в том, что URL-адрес вызова должен ссылаться на имя вашей зоны. Кроме того, для создания начального токена доступа необходимо включить код доступа, как показано на шаге 3 в процедуре выше.

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

curl -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" /
  -H "accept: application/json;charset=utf-8" /
  -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" -X POST /
  https://edge_sso_IP_DNS:9099/oauth/token -s /
  -d 'grant_type=password&response_type=token&passcode=passcode'

Для авторизации передайте зарезервированные учетные данные клиента OAuth2 в заголовке Authorization. В результате вызова на экране появятся токены доступа и обновления.

Чтобы обновить токен доступа, используйте следующий вызов, включающий токен обновления:

curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" /
  -H "Accept: application/json;charset=utf-8" /
  -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" -X POST /
  https://edge_sso_IP_DNS:9099/oauth/token /
  -d 'grant_type=refresh_token&refresh_token=refreshToken'