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 USER_NAME:PASSWORD http://MS_IP_DNS:8080/v1/organizations/ORG_NAME

In this example, you use the curl -u option to pass Basic authentication credentials. Alternatively, you can pass an OIDC/OAuth2 token in the Authorization: Bearer header to make Edge management API calls, as the following example shows:

curl -H "Authorization: Bearer ACCESS_TOKEN" http://MS_IP_DNS:8080/v1/organizations/ORG_NAME

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 will 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 uses the standard OAuth 2.0 Device Code Flow to acquire OIDC/OAuth2 access and refresh tokens. The utility prompts you to visit a URL in your browser to authenticate via your external IDP (or local LDAP), and then automatically unblocks your terminal to print the valid access token.

The get_token utility caches the tokens securely on disk in ~/.sso-cli/, ready for use when required. It also prints a valid access token to stdout. If an existing token can be refreshed, the utility will automatically refresh it. If the refresh token expires, it will initiate a new browser-based authorization flow.

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

The get_token and acurl utilities are pre-installed on the node hosting the Apigee SSO (OpenLDAP node) at: /opt/apigee/apigee-openldap/bin/
Note: You can copy these utility scripts to your local development machine if you prefer to run them locally.
(Optional) Set the SSO_LOGIN_URL environment variable to your SSO issuer URL, in the form:
```
export SSO_LOGIN_URL="http://EDGE_SSO_IP_DNS:9099"
```
Where EDGE_SSO_IP_DNS is the IP address or DNS name of the machine hosting the Apigee SSO. If you configured TLS on the Apigee SSO, use https and the correct TLS port number.
Invoke get_token with your email address to initiate the OAuth 2.0 Device Code Flow:
```
/opt/apigee/apigee-openldap/bin/get_token -u EMAIL_ADDRESS
```
Where EMAIL_ADDRESS is the email address of an Edge user.
The utility will pause and print a URL and an 8-character device code to your terminal:
```
Please visit: http://EDGE_SSO_IP_DNS:9099/device
And enter code: ABCD-EFGH
```
Open the specified URL in your browser, enter the device code, and click Submit. You will be redirected to your external IDP (or local LDAP form) to authenticate and approve the request.
After you successfully authenticate in the browser, return to your terminal. The get_token utility will automatically detect the approval, obtain the OAuth2 access token, print it to the screen, and cache it securely.
Pass the access token to an Edge management API call using the acurl utility, which automatically reads the cached token and injects the Bearer header:
```
/opt/apigee/apigee-openldap/bin/acurl http://MS_IP_DNS:8080/v1/organizations/ORG_NAME
```
Alternatively, you can manually pass the token using standard curl:
```
curl -H "Authorization: Bearer ACCESS_TOKEN" \
  http://MS_IP_DNS:8080/v1/organizations/ORG_NAME
```

Use the management API to get and refresh tokens

The legacy /passcode endpoint has been removed. Hence, human users must use the get_token utility as described earlier to initiate the browser-based OAuth 2.0 Device Code Flow for initial authentication.

If you are writing scripts or CI/CD pipelines that cannot interact with a browser, see Automate tasks with machine users. Automated machine users or applications with valid credentials can use standard API calls to obtain and refresh token.