Acessar a API Edge com SAML

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

O SAML é compatível com um ambiente de Logon único (SSO). Ao usar o SAML com o Edge, você oferece suporte ao SSO para a IU e a API do Edge, além de todos os outros serviços que você fornece e que também são compatíveis com o SAML.

Pré-requisito: é necessário ativar o SAML para pelo menos uma organização antes de usá-lo para acessar a API Edge.

Diferenças entre SAML e OAuth2

Depois de configurar o SAML, o uso dele é muito semelhante ao uso do OAuth2 para acessar a API Edge. Ao chamar a API Edge, você inclui um token de acesso OAuth2 na solicitação.

A principal diferença entre SAML e OAuth2 ao acessar a API Edge está no caminho para receber os tokens. Com o SAML, é preciso incluir o seguinte ao receber o par de tokens:

  1. Zonas:os usuários do Edge para nuvem pública precisam referenciar o nome da zona deles ao receber tokens.
  2. Senha:inclua uma senha única ao solicitar um par de tokens de acesso/atualização.

O SAML usa os mesmos endpoints no serviço OAuth2 do Edge, com o nome da zona apropriado.

Para receber tokens de acesso com o SAML, use um dos métodos a seguir, descritos nesta seção:

Além disso, você pode automatizar o processo de geração de tokens para usuários de máquina, conforme descrito em Automatizar o processo de geração de token.

Receber tokens de acesso com get_token

Use o utilitário get_token para trocar suas credenciais por tokens de acesso ao OAuth2 e atualizar que você usa com o SAML.

Para receber um token de acesso com get_token:

  1. Defina a variável de ambiente SSO_LOGIN_URL como seu URL de login. O URL de login tem este formato:
    https://zoneName.login.apigee.com

    Por exemplo, para uma zona chamada "acme", defina SSO_LOGIN_URL como "https://acme.login.apigee.com", conforme mostrado no exemplo a seguir:

    export SSO_LOGIN_URL=https://acme.login.apigee.com
  2. Chame get_token para receber o token de acesso OAuth2:
    get_token -u me@example.com

    Você precisa acessar o URL exibido para receber uma senha única:

    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:

    Se não tiver feito login recentemente com seu provedor de identidade, você vai receber uma solicitação.

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

  3. Digite a senha. O utilitário get_token recebe os tokens OAuth2, mostra o token de acesso em stdout e grava os tokens de acesso e de atualização em ~/.sso-cli.

  4. Chame a API Edge e transmita o token de acesso no cabeçalho Authorization: Bearer, conforme o exemplo a seguir:
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -H "Authorization: Bearer ACCESS_TOKEN"

    O valor do token de acesso pode ser copiado de stdout.

    Este exemplo mostra detalhes sobre a organização em questão. Para conferir uma lista completa dos endpoints da API de gerenciamento, consulte a Referência da API Apigee Edge.

Quando o token de acesso expirar, chame get_token novamente para receber um novo token. Exemplo:

get_token -u me@example.com

Uma nova senha só será solicitada quando o token de atualização expirar.

Quando o token de atualização expira, o get_token solicita uma nova senha. É necessário gerar uma nova senha antes de gerar um novo token de acesso do OAuth2.

Receber tokens de acesso com o serviço do Edge OAuth2

É possível usar o serviço OAuth2 do Edge para receber tokens de acesso usados com o SAML. Para se autenticar com a API Edge, use uma senha na solicitação inicial para receber um par de tokens de acesso/atualização e novamente para receber um novo par de tokens.

Para receber um par de tokens com a API Edge:

  1. Em um navegador, acesse o seguinte URL para receber uma senha única:
    https://zoneName.login.apigee.com/passcode

    Por exemplo, para uma zona chamada "acme", acesse o seguinte URL:

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

    Se não tiver feito login recentemente com seu provedor de identidade, você vai receber uma solicitação.

    Esse URL retorna uma senha única que funciona como sua credencial para receber tokens e permanece válida até que você atualize o URL para receber uma nova senha. Também é possível usar a senha com get_token para gerar um token de acesso. Exemplo:

  2. Envie uma solicitação para a API Edge, conforme o exemplo a seguir:
    curl https://zoneName.login.apigee.com/oauth/token \
          -s \
          -H "Accept: application/json" \
          -d 'grant_type=password&response_type=token&passcode=passcode'

    O passcode funciona como sua credencial de autorização.

    Em que:

    • O cabeçalho Authorization é "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (use esse valor exato).
    • O tipo de solicitação é POST.
    • O corpo da solicitação contém o seguinte:
      • grant_type é "password".
      • response_type é "token".
      • passcode, em que passcode é a senha retornada na etapa anterior.

    A chamada exibe os tokens de acesso e de atualização na tela.

Para atualizar seu token de acesso:

Envie uma solicitação para https://zoneName.login.apigee.com/oauth/token, conforme o exemplo a seguir:

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

Em que:

  • O corpo da solicitação contém o seguinte:
    • grant_type é "refresh_token".
    • refresh_token é o valor do token de atualização.
  • O cabeçalho Authorization é "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (use esse valor exato).
  • O tipo de solicitação é POST.

Acessar a API Edge com SAML

É possível usar ferramentas como curl ou o utilitário de conveniência da Apigee acurl para acessar a API Edge.

Com curl, você chama a API Edge e transmite o token de acesso no cabeçalho Authorization: Bearer, como mostra o exemplo a seguir:

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

Com acurl, não é necessário especificar o cabeçalho Authorization. Exemplo:

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

Estes exemplos chamam um endpoint da API Edge que recebe detalhes sobre a organização em questão. Confira a lista completa de endpoints da API Edge em Referência da API Apigee Edge.

Para ver outros métodos de chamada da API, incluindo maneiras de garantir que o token permaneça atualizado, consulte Acessar a API Edge com OAuth2.

Usuários de máquinas em zonas SAML

É possível usar os utilitários acurl e get_token para criar scripts de acesso automatizado às APIs Edge para usuários de máquinas em zonas SAML. O exemplo a seguir mostra como usar get_token para solicitar um token de acesso e, em seguida, adicionar o valor do token a uma chamada 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/...'

No exemplo acima, definir o valor de -m como uma string vazia impede que um usuário da máquina receba uma solicitação de código MFA. O uso da sinalização --force-basic-auth modificará o prompt padrão de uma senha acionada por solicitações com zonas SAML.

Como alternativa, é possível combinar a solicitação de token e a chamada de curl usando o utilitário acurl. Exemplo:

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