Como usar o SAML com a API Edge Management

Edge for Private Cloud v. 4.17.09

A autenticação básica é uma maneira de fazer a autenticação ao fazer chamadas para a API de gerenciamento do Edge. Por exemplo, é possível fazer a seguinte solicitação de cURL para a API de gerenciamento do Edge para acessar informações sobre sua organização:

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

Neste exemplo, você usa a opção cURL -u para transmitir credenciais de autenticação básica. Você também pode passar um token OAuth2 no cabeçalho Bearer para fazer chamadas da API Edge Management. Exemplo:

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

Depois de ativar o SAML, você pode desativar a autenticação básica. Se você desativar a autenticação básica, todos os scripts (Maven, shell, apigeetool etc.) que dependem de chamadas de API de gerenciamento do Edge que oferecem suporte à autenticação básica não funcionarão mais. Atualize todas as chamadas de API e scripts que usam a autenticação básica para transmitir tokens de acesso do OAuth2 no cabeçalho do portador.

Como usar o get_token para receber e atualizar tokens

O utilitário get_token troca suas credenciais de autenticação básica e uma senha por um token de acesso e atualização do OAuth2. O utilitário get_token aceita suas credenciais e imprime um token de acesso válido. Se um token puder ser atualizado, ele será atualizado e impresso. Se o token de atualização expirar, ele vai solicitar as credenciais do usuário.

O utilitário get_token armazena os tokens no disco, prontos para uso quando necessário. Ele também imprime um token de acesso válido no stdout. Depois, você pode usar o Postman ou incorporá-lo a uma variável de ambiente para uso no curl.

O procedimento a seguir descreve como usar get_token para receber um token de acesso OAuth2 e fazer chamadas de API de gerenciamento do Edge:

  1. Faça o download do pacote sso-cli:
    curl http://edge_sso_IP_DNS:9099/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"

    em que edge_sso_IP_DNS é o endereço IP do nome DNS da máquina que hospeda o módulo de SSO do Edge. Se você configurou o TLS no SSO de borda, use https e o número de porta TLS correto.

  2. Descompacte o pacote ssocli-bundle.zip:
    unzip ssocli-bundle.zip
  3. Instalar get_token em /usr/local/bin:
    ./install

    Use a opção -b para especificar um local diferente:

    ./install -b path
  4. Defina a variável de ambiente SSO_LOGIN_URL como o URL de login, no formato:
    export SSO_LOGIN_URL="http://edge_sso_IP_DNS:9099"

    em que edge_sso_IP_DNS é o endereço IP do nome DNS da máquina que hospeda o módulo de SSO do Edge. Se você configurou o TLS no SSO de borda, use https e o número de porta TLS correto.

  5. Em um navegador, acesse o seguinte URL para receber uma senha única:
    http://edge_sso_IP_DNS:9099/passcode

    Se você configurou o TLS no SSO de borda, use https e o número de porta TLS correto.

    Esse URL retorna uma senha única que permanece válida até que você atualize o URL para receber uma nova senha ou use a senha com get_token para gerar um token de acesso.

  6. Invocar get_token para receber o token de acesso do OAuth2:
    get_token -u emailAddress

    em que emailAddress é o endereço de e-mail de um usuário do Edge. Você vai receber uma solicitação para inserir a senha única que você recebeu na etapa 3:

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

    Digite a senha. O utilitário get_token recebe o token de acesso do OAuth2, o imprime na tela e o grava, além do token de atualização, em ~/.sso-cli.

    É possível inserir a senha na linha de comando usando um comando get_token no formato:

    get_token -u emailAddress -p passcode

  7. Transmita o token de acesso para uma chamada da API de gerenciamento do Edge como o cabeçalho Bearer:
    curl -H "Authorization: Bearer access_token"
    https://ms_IP:8080/v1/organizations/orgName

    Depois de receber um novo token de acesso pela primeira vez, você pode transmiti-lo a uma chamada de API em um único comando, conforme mostrado abaixo:

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

    Com esse formato de comando, se o token de acesso tiver expirado, ele será atualizado automaticamente até que o token de atualização expire.

Depois que o token de atualização expirar, o get_token vai solicitar uma nova senha. Acesse o URL mostrado acima na Etapa 3 e gere uma nova senha antes de gerar um novo token de acesso OAuth

Como usar a API Management para receber e atualizar tokens

Usar a segurança OAuth2 com a API de gerenciamento do Apigee Edge contém instruções que mostram como usar a API de gerenciamento do Edge para conseguir e atualizar tokens. Também é possível usar chamadas de API do Edge para tokens gerados a partir de declarações SAML.

A única diferença entre as chamadas de API documentadas em Como usar a segurança do OAuth2 com a API de gerenciamento do Apigee Edge é que o URL da chamada precisa referenciar o nome da zona. Além disso, para gerar o token de acesso inicial, é necessário incluir a senha, conforme mostrado na etapa 3 do procedimento acima.

Por exemplo, use a seguinte chamada de API para gerar os tokens de acesso e de atualização iniciais:

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'

Para autorização, transmita uma credencial do cliente OAuth2 reservada no cabeçalho Authorization. A chamada mostra os tokens de acesso e de atualização na tela.

Para atualizar o token de acesso mais tarde, use a seguinte chamada que inclui o token de atualização:

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'