Accéder à l'API Edge avec SAML

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X.
en savoir plus

SAML est compatible avec un environnement d'authentification unique (SSO). En utilisant SAML avec Edge, vous pouvez prendre en charge l'authentification unique pour l'interface utilisateur et l'API Edge en plus de tous les autres services que vous fournissez et qui prennent également en charge SAML.

Condition préalable:vous devez activer SAML pour au moins une organisation avant de pouvoir l'utiliser pour accéder à l'API Edge.

Différences entre SAML et OAuth2

Une fois SAML configuré, son utilisation est très semblable à l'utilisation d'OAuth2 pour accéder à l'API Edge. Lorsque vous appelez l'API Edge, vous incluez un jeton d'accès OAuth2 dans votre requête.

La principale différence entre SAML et OAuth2 lors de l'accès à l'API Edge réside dans la façon dont vous obtenez des jetons. Avec SAML, vous devez inclure les éléments suivants lorsque vous obtenez votre paire de jetons:

  1. Zones:les utilisateurs Edge for Public Cloud doivent référencer le nom de leur zone lorsqu'ils obtiennent des jetons.
  2. Code secret:incluez un code secret à usage unique lorsque vous demandez une paire de jetons d'accès/d'actualisation.

SAML utilise les mêmes points de terminaison sur le service Edge OAuth2, avec en plus le nom de zone approprié.

Pour obtenir des jetons d'accès avec SAML, vous pouvez utiliser l'une des méthodes suivantes, décrites dans cette section:

De plus, vous pouvez automatiser le processus de génération de jetons pour les utilisateurs de machines, comme décrit dans Automatiser le processus de génération de jetons.

Obtenir des jetons d'accès avec get_token

L'utilitaire get_token vous permet d'échanger vos identifiants contre des jetons d'accès OAuth2 et d'actualisation que vous utilisez avec SAML.

Pour obtenir un jeton d'accès avec get_token:

  1. Définissez la variable d'environnement SSO_LOGIN_URL sur votre URL de connexion. L'URL de connexion se présente au format suivant :
    https://zoneName.login.apigee.com

    Par exemple, pour une zone nommée "acme", définissez SSO_LOGIN_URL sur "https://acme.login.apigee.com", comme indiqué dans l'exemple suivant:

    export SSO_LOGIN_URL=https://acme.login.apigee.com
  2. Appelez get_token pour obtenir le jeton d'accès OAuth2 :
    get_token -u me@example.com

    Vous êtes invité à accéder à l'URL qui s'affiche pour obtenir un code secret à usage unique:

    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:

    Si vous ne vous êtes pas connecté récemment via votre fournisseur d'identité, vous serez invité à vous connecter.

    Cette URL renvoie un code secret à usage unique qui reste valide jusqu'à ce que vous l'actualisez pour obtenir un nouveau code secret ou jusqu'à ce que vous utilisiez le code secret avec get_token pour générer un jeton d'accès. Exemple :

  3. Saisissez le code secret. L'utilitaire get_token obtient les jetons OAuth2, imprime le jeton d'accès dans stdout, et écrit les jetons d'accès et d'actualisation dans ~/.sso-cli.

  4. Appelez l'API Edge et transmettez le jeton d'accès dans l'en-tête Authorization: Bearer, comme indiqué dans l'exemple suivant :
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -H "Authorization: Bearer ACCESS_TOKEN"

    La valeur du jeton d'accès peut être copiée depuis stdout.

    Cet exemple permet d'obtenir des informations sur l'organisation donnée. Pour obtenir la liste complète des points de terminaison de l'API de gestion, consultez la documentation de référence de l'API Apigee Edge.

Lorsque votre jeton d'accès expire, vous pouvez appeler à nouveau get_token pour obtenir un nouveau jeton d'accès. Exemple :

get_token -u me@example.com

Vous ne serez pas invité à en saisir un nouveau tant que le jeton d'actualisation n'aura pas expiré.

Lorsque le jeton d'actualisation expire, get_token vous invite à saisir un nouveau code secret. Vous devez générer un nouveau code secret avant de pouvoir générer un nouveau jeton d'accès OAuth2.

Obtenir des jetons d'accès avec le service Edge OAuth2

Vous pouvez utiliser le service Edge OAuth2 pour obtenir des jetons d'accès que vous utilisez avec SAML. Pour vous authentifier auprès de l'API Edge, vous utilisez un code secret sur votre requête initiale afin d'obtenir une paire de jetons d'accès/d'actualisation, puis une nouvelle paire de jetons.

Pour obtenir une paire de jetons avec l'API Edge:

  1. Dans un navigateur, accédez à l'URL suivante pour obtenir un code secret à usage unique :
    https://zoneName.login.apigee.com/passcode

    Par exemple, pour une zone nommée "acme", accédez à l'URL suivante:

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

    Si vous ne vous êtes pas connecté récemment via votre fournisseur d'identité, vous serez invité à vous connecter.

    Cette URL renvoie un code secret à usage unique qui sert d'identifiant pour obtenir des jetons. Elle reste valide jusqu'à ce que vous l'actualisez pour obtenir un nouveau code secret, ou vous pouvez utiliser ce code avec get_token pour générer un jeton d'accès. Exemple :

  2. Envoyez une requête à l'API Edge, comme indiqué dans l'exemple suivant :
    curl https://zoneName.login.apigee.com/oauth/token \
          -s \
          -H "Accept: application/json" \
          -d 'grant_type=password&response_type=token&passcode=passcode'

    Le passcode sert d'identifiant pour l'autorisation.

    Où :

    • L'en-tête Authorization est "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (utilisez cette valeur exacte).
    • Le type de requête est POST.
    • Le corps de la requête contient les éléments suivants :
      • grant_type correspond au "mot de passe".
      • response_type est "jeton".
      • passcode, où passcode correspond au code secret renvoyé à l'étape précédente.

    L'appel imprime les jetons d'accès et d'actualisation à l'écran.

Pour actualiser votre jeton d'accès:

Envoyez une requête à https://zoneName.login.apigee.com/oauth/token, comme indiqué dans l'exemple suivant:

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

Où :

  • Le corps de la requête contient les éléments suivants :
    • grant_type est "refresh_token".
    • refresh_token correspond à la valeur du jeton d'actualisation.
  • L'en-tête Authorization est "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (utilisez cette valeur exacte).
  • Le type de requête est POST.

Accéder à l'API Edge avec SAML

Vous pouvez utiliser des outils tels que curl ou l'utilitaire pratique Apigee acurl pour accéder à l'API Edge.

Avec curl, appelez l'API Edge et transmettez le jeton d'accès dans l'en-tête Authorization: Bearer, comme le montre l'exemple suivant:

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

Avec acurl, vous n'avez pas besoin de spécifier l'en-tête Authorization. Exemple :

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

Ces exemples appellent un point de terminaison de l'API Edge qui obtient des détails sur l'organisation donnée. Pour obtenir la liste complète des points de terminaison de l'API Edge, consultez la documentation de référence de l'API Apigee Edge.

Pour connaître d'autres méthodes d'appel de l'API, y compris pour vous assurer que votre jeton reste à jour, consultez Accéder à l'API Edge avec OAuth2.

Utilisateurs de machine dans les zones SAML

Vous pouvez utiliser les utilitaires acurl et get_token pour créer un script d'accès automatisé aux API Edge pour les utilisateurs machine dans les zones SAML. L'exemple suivant montre comment utiliser get_token pour demander un jeton d'accès, puis ajouter la valeur du jeton à un appel 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/...'

Dans l'exemple ci-dessus, la définition de la valeur de -m sur une chaîne vide empêche un utilisateur de la machine d'être invité à saisir un code MFA. L'option --force-basic-auth remplace l'invite standard de code secret déclenchée par des requêtes avec des zones SAML.

Vous pouvez également combiner la requête de jeton et l'appel curl à l'aide de l'utilitaire acurl. Exemple :

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