Automate tasks for external IDPs

When using an external IDP with the Edge API, the process that you use to obtain OAuth2 access and refresh tokens from the IDP interaction is called the passcode flow. With the passcode flow, you use a browser to obtain a one-time passcode that you then use to obtain OAuth2 tokens.

However, your development environment might support automation for common development tasks, such as test automation or CI/CD. To automate these tasks when an external IDP is enabled, you need a way to obtain and refresh OAuth2 tokens without having to copy/paste a passcode from a browser.

Edge supports automated token generation through the use of machine users within organizations that have an IDP enabled. A machine user can obtain OAuth2 tokens without having to specify a passcode. That means you can completely automate the process of obtaining and refreshing OAuth2 tokens by using the Edge management API.

There are two ways to create a machine user for an IDP-enabled organization:

Using apigee-ssoadminapi.sh
Using the management API

Each of these methods is described in the sections that follow.

You cannot create a machine user for organizations that have no enabled an external IDP.

Create a machine user with `apigee-ssoadminapi.sh`

Use the apigee-ssoadminapi.sh utility to create a machine user within an IDP-enabled organization. See Using apigee-ssoadminapi.sh for more. You can create a single machine user that is used by all of your organizations, or create a separate machine user for each organization.

The machine user is created and stored in the Edge datastore, not in your IDP. Therefore, you are not responsible for maintaining the machine user by using the Edge UI and Edge management API.

When you create the machine user, you must specify an email address and password. After creating the machine user, you assign it to one or more organizations.

To create a machine user with apigee-ssoadminapi.sh:

Use the following apigee-ssoadminapi.sh command to create the machine user:
```
apigee-ssoadminapi.sh saml machineuser add --admin SSO_ADMIN_NAME \
  --secret SSO_ADMIN_SECRET --host Edge_SSO_IP_or_DNS \
  -u machine_user_email -p machine_user_password
```
QUESTION/TBD: Does apigee-ssoadminapi.sh also take "ldap" as an argument?

Where:
- SSO_ADMIN_NAME is the admin username defined by the SSO_ADMIN_NAME property in the configuration file used to configure the Apigee SSO module. The default is ssoadmin.
- SSO_ADMIN_SECRET is the admin password as specified by the SSO_ADMIN_SECRET property in the config file.
  In this example, you can omit the values for --port and --ssl because the apigee-sso module uses the default values of 9099 for --port and http for --ssl. If your installation does not use these defaults, specify them as appropriate.
Log in to the Edge UI and add the machine user's email to your organizations, and assign the machine user to the necessary role. See Adding global users for more.

Create a machine user with the Edge management API

You can create a machine user by using the Edge management API instead of using the apigee-ssoadminapi.sh utility.

To create a machine user with the management API:

Use the following curl command to obtain a token for the ssoadmin user, the username of the admin account for apigee-sso:
```
curl "http://Edge_SSO_IP_DNS:9099/oauth/token" -i -X POST \
  -H 'Accept: application/json' / -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "response_type=token" -d "grant_type=client_credentials" \
  --data-urlencode "client_secret=SSO_ADMIN_SECRET" \
  --data-urlencode "client_id=ssoadmin"
```
Where SSO_ADMIN_SECRET is the admin password you set when you installed apigee-sso as specified by the SSO_ADMIN_SECRET property in the config file.

This command displays a token that you need to make the next call.

Use the following curl command to create the machine user, passing the token that you received in the previous step:

curl "http://edge_sso_IP_DNS:9099/Users" -i -X POST \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"userName" : "machine_user_email", "name" :
    {"formatted":"DevOps", "familyName" : "last_name", "givenName" :
    "first_name"}, "emails" : [ {"value" :
    "machine_user_email", "primary" : true } ], "active" : true,
    "verified" : true, "password" : "machine_user_password" }' \
  -H "Authorization: Bearer token"

You need the machine user password in later steps.

Log in to the Edge UI.
Add the machine user's email to your organizations and assign the machine user to the necessary role. See Adding global users for more.

Obtain and refresh machine user tokens

Use the Edge API to obtain and refresh OAuth2 tokens by passing the machine user's credentials, instead of a passcode.

To obtain OAuth2 tokens for the machine user:

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 \
  http://Edge_SSO_IP_DNS:9099/oauth/token -s \
  -d 'grant_type=password&username=m_user_email&password=m_user_password'

NOTE: For authorization, pass the reserved OAuth2 client credential, Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0, in the Authorization header.

Save the tokens for later use.

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" \
  http://MS_IP_DNS:8080/v1/organizations/org_name
```
Where org_name is the name of the organization containing the machine user.

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 \
  http://edge_sso_IP_DNS:9099/oauth/token \
  -d 'grant_type=refresh_token&refresh_token=refreshToken'