Acessar a API Edge com SAML

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

O SAML oferece suporte a um ambiente de Logon único (SSO). Ao usar o SAML com o Edge, é possível oferecer suporte ao SSO para a API e a interface do Edge, além de outros serviços que você oferece e que também oferecem suporte ao 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 que o SAML é configurado, 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 do OAuth2 em sua solicitação.

A principal diferença entre o SAML e o OAuth2 ao acessar a API Edge está na maneira como você recebe tokens. Com o SAML, é necessário 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 ao receber tokens.
  2. Senha:inclua uma senha única ao solicitar um par de tokens de acesso/atualização token.

O SAML usa os mesmos endpoints no serviço OAuth2 do Edge, com a adição do nome da zona apropriada.

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

Além disso, é possível automatizar o processo de geração de tokens para usuários de máquinas, conforme descrito em Automatizar o processo de geração de tokens.

Receber tokens de acesso com get_token

É possível usar o get_token utilitário para trocar suas credenciais por tokens de acesso e de atualização do OAuth2 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 o URL de login. O URL de login tem o seguinte 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 do OAuth2: 
    get_token -u me@example.com

    Você vai receber uma solicitação para 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 você não tiver feito login recentemente pelo provedor de identidade, será solicitado que você faça login.

    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. Exemplo:

  3. Digite a senha. O utilitário get_token recebe os tokens do OAuth2, imprime o token de acesso para 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 Authorization: Bearer cabeçalho, conforme mostrado no 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 recebe detalhes sobre a organização fornecida. Para uma lista completa de 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 de acesso. Exemplo:

get_token -u me@example.com

Você não vai receber uma solicitação de nova senha até que o token de atualização expire.

Quando o token de atualização expira, 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 OAuth2 do Edge

É possível usar o serviço OAuth2 do Edge para receber tokens de acesso que você usa 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 você não tiver feito login recentemente pelo provedor de identidade, será solicitado que você faça login.

    Esse URL retorna uma senha única que atua como suas credenciais 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 mostrado no 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 atua como suas credenciais 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 imprime os tokens de acesso e de atualização na tela.

Para atualizar o token de acesso:

Envie uma solicitação para https://zoneName.login.apigee.com/oauth/token, conforme mostrado no 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 acurl para acessar a API Edge.

Com curl, você chama a API Edge e transmite o token de acesso no Authorization: Bearer cabeçalho, conforme mostrado no 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

Esses exemplos chamam um endpoint de API Edge que recebe detalhes sobre a organização fornecida. Para uma lista completa de endpoints da API Edge, consulte a referência da API Apigee Edge.

Para 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 util0itá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 de máquina receba uma solicitação de código MFA. O uso da flag --force-basic-auth substitui a solicitação 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 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/...'