Use an external IDP with the Edge management API

Basic authentication 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 authentication credentials. Alternatively, you can pass an OAuth2 token in the Bearer header to make Edge management API calls, as the following example shows:

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

After you enable an external IDP for authentication, you can optionally disable Basic authentication. If you disable Basic authentication, all scripts (such as Maven, shell, and apigeetool) that rely on Edge management API calls supporting Basic authentication no longer work. You must update any API calls and scripts that use Basic authentication to pass OAuth2 access tokens in the Bearer header.

Get and refresh tokens with get_token

The get_token utility exchanges your Basic authentication credentials (and in some cases a passcode) for an OAuth2 access and refresh token. The get_token utility accepts your credentials and returns a valid access token. If a token can be refreshed, the utility refreshes and returns it. 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 a browser extension like Postman or embed it in an environment variable for use in curl.

To obtain an OAuth2 access token to make Edge management API calls:

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 or DNS name of the machine hosting the Apigee SSO module. If you configured TLS on Apigee SSO, use https and the correct TLS port number.
Unzip the ssocli-bundle.zip bundle, as the following example shows:
```
unzip ssocli-bundle.zip
```
Install get_token in /usr/local/bin, as the following example shows:
```
./install -b path
```
The -b option specifies a different location.
Set the SSO_LOGIN_URL environment variable to your login URL, in the following form:
```
export SSO_LOGIN_URL="http://edge_sso_IP_DNS:9099"
```
Where edge_sso_IP_DNS is the IP address of the machine hosting the Apigee SSO module. If you configured TLS on Apigee SSO, use https and the correct TLS port number.
(SAML only) In a browser, navigate to the following URL to obtain a one-time passcode:
```
http://edge_sso_IP_DNS:9099/passcode
```
If you configured TLS on Apigee SSO, use https and the correct TLS port number.

NOTE: If you are not currently logged in by your IDP, you will be prompted to log in.

This request 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.

Note that you can use a passcode only when authenticating with a SAML IDP. You can not use a passcode to authenticate with an LDAP IDP.
Invoke get_token to get the OAuth2 access token, as the following example shows:
```
get_token -u emailAddress
```
Where emailAddress is the email address of an Edge user.

(SAML only) Enter the passcode on the command line in addition to the email address, as the following example shows:
```
get_token -u emailAddress -p 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.
Pass the access token to an Edge management API call as the Bearer header, as the following example shows:
```
curl -H "Authorization: Bearer access_token"
  https://ms_IP:8080/v1/organizations/orgName
```
After you get a new access token for the first time, you can get the access token and pass it to an API call in a single command, as the following example shows:
```
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.

(SAML only) After the refresh token expires, get_token prompts you for a new passcode. You must navigate to the URL shown above in step 3 and generate a new passcode before you can generate a new OAuth access token.

Use the management API to get and refresh tokens

Use OAuth2 security with the Apigee Edge management API shows how to use the Edge management API to obtain and refresh tokens. You can also use Edge API calls to get 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 with a SAML IDP, you must include the passcode, as shown in step 3 of the procedure above.

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

Get an access token

(LDAP) 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'

(SAML) 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'

Note that authentication with a SAML IDP requires a temporary passcode, whereas an LDAP IDP does not.

Refresh an access token

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'