Use SAML with the Edge management API

Basic Auth is one way to authenticate when making calls to the Edge management API. For example, you can make the following cURL request to the Edge management API to access information about your organization:

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

In this example, you use the cURL -u option to pass Basic Auth credentials. Alternatively, you can pass an OAuth2 token in the Bearer header to make Edge management API calls. For example:

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

After you enable SAML, you can optionally disable Basic Auth. if you disable Basic Auth, all scripts (Maven scripts, shell scripts, apigeetool, etc.) that rely on Edge management API calls supporting Basic Auth no longer work. You must update any API calls and scripts that use Basic Auth to pass OAuth2 access tokens in the Bearer header.

Using get_token to get and refresh tokens

The get_token utility exchanges your Basic Auth credentials and a passcode for an OAuth2 access and refresh token. The get_token utility accepts your credentials and prints a valid access token. If a token can be refreshed, it will refresh it and print it out. If the refresh token expires, it will prompt for user credentials.

The get_token utility stores the tokens on disk, ready for use when required. It also prints a valid access token to stdout. From there, you can use Postman or embed it in an environment variable for use in curl.

The following procedure describes how to use get_token to obtain an OAuth2 access token to make Edge management API calls:

1. Download the sso-cli bundle:
   

   curl http://edge_sso_IP_DNS:9099/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"

   where edge_sso_IP_DNS is the IP address of DNS name of the machine hosting the Edge SSO module. If you configured TLS on Edge SSO, use https and the correct TLS port number.

2. Unzip the ssocli-bundle.zip bundle:

   unzip ssocli-bundle.zip

3. Install get_token in /usr/local/bin:
   > ./install Use the -b option to specify a different location: > ./install -b path
4. Set the SSO_LOGIN_URL environment variable to your login URL, in the form:
   export SSO_LOGIN_URL="http://edge_sso_IP_DNS:9099"
   
   where edge_sso_IP_DNS is the IP address of DNS name of the machine hosting the Edge SSO module. If you configured TLS on Edge SSO, use https and the correct TLS port number.
5. In a browser, go to the following URL to obtain a one-time passcode:
   http://edge_sso_IP_DNS:9099/passcode
   
   If you configured TLS on Edge SSO, use https and the correct TLS port number.
   
   Note: If you are not currently logged in by your identity provider, you will be prompted to log in.
   
   This URL returns a one-time passcode that remains valid until you refresh that URL to obtain a new passcode, or you use the passcode with get_token to generate an access token.
6. Invoke get_token to obtain the OAuth2 access token:
   > get_token -u emailAddress
   
   where emailAddress is the email address of an Edge user. You are prompted to enter the one-time passcode that you obtained in step 3:
   One Time Code ( Get one at https://edge_sso_IP.com/passcode )
   Enter the passcode if SAML is enabled or press ENTER:
   
   Enter the passcode. The get_token utility obtains the OAuth2 access token, prints it to the screen, and writes it and the refresh token to ~/.sso-cli.
   
   You can enter the passcode on the command line using a get_token command in the form:
   > get_token -u emailAddress -p passcode
7. Pass the access token to an Edge management API call as the Bearer header:
   > curl -H "Authorization: Bearer access_token" https://ms_IP:8080/v1/organizations/orgName
   
   After you obtain a new access token for the first time, you can obtain the access token and pass it to an API call in a single command, as shown below:
   > header=`get_token` && curl -H "Authorization: Bearer $header" https://ms_IP:8080/v1/o/orgName
   
   With this form of the command, if the access token has expired, it is automatically refreshed until the refresh token expires.

After the refresh token expires, get_token prompts you for a new passcode. You must go to the URL shown above in Step 3 and generate a new passcode before you can generate a new OAuth access token

Using the management API to get and refresh tokens

Using OAuth2 security with the Apigee Edge management API contains instructions that show how to use the Edge management API to obtain and refresh tokens. You can also use Edge API calls to for tokens generated from SAML assertions.

The only difference between the API calls documented in Using OAuth2 security with the Apigee Edge management API is that the URL of the call must reference your zone name. In addition, for generating the initial access token, you must include the passcode, as shown in step 3 of the procedure above.

For example, use the following API call to generate the initial access and refresh tokens:

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'  

For authorization, pass a reserved OAuth2 client credential in the Authorization header. The call prints the access and refresh tokens to the screen.

To later refresh the access token, use the following call that includes the refresh token:

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'