Automate the token generation process

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

When using SAML with the Edge API, the process that you use to obtain OAuth2 access and refresh tokens from the SAML assertion 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 environment might support automation for common development tasks, such as test automation or Continuous Integration/Continuous Deployment (CI/CD). To automate these tasks when SAML is enabled, you need a way to obtain and refresh OAuth2 tokens without having to copy/paste a passcode from a browser.

About machine users

Apigee Edge supports machine users in your SAML-enabled organization. Machine users are used strictly for automation and are not accessed directly by a human.

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 API.

Steps to automate the token generation process

To automate the token generation process:

Step	Description
1	Create a machine user in your SAML identity zone
2	Assign required roles to the machine user in your Edge organization
3	Get the machine users's OAuth2 tokens

Video: Watch a short video to learn about how to automate access to the Apigee Edge APIs using machine user credentials.

Manage machine users for SAML identity zones

Apigee provides the machine user management command-line interface (CLI) to create and manage machine user accounts. The steps to use the machine user management CLI are described in the following sections.

Use the CLI

To use the machine user management CLI, first download and untar the following file: usermgmt.tar.gz⁽¹⁾

The format for calling the CLI is as follows:

usermgmt_platform [command] [flags]

The following table summarizes the platforms that are supported and the corresponding command to call the machine user management CLI. (The executables are located in the usermgmt directory.)

Platform	32-bit	64-bit
Linux	`usermgmt_linux_386`	`usermgmt_linux_amd64`
Mac	`usermgmt_darwin_386`	`usermgmt_darwin_amd64`
Windows	`usermgmt_windows_386`	`usermgmt_windows_amd64`

The following table summarizes the commands that can be specified.

Command	More information
`create`	Create a machine user in an identity zone
`delete`	Delete a machine user in an identity zone
`help`	Get help using the CLI
`list`	List all machine users in an identity zone
`reset`	Reset the password for a machine user in an identity zone

Optionally, you can pass one of the following flags to display help on the specified command: -h or --help

The first time you run the CLI within a 24-hour period, you are prompted to enter your zoneadmin account credentials.

Enter your Apigee credentials
Username: zoneadmin-username
Password: zoneadmin-password
If your user is opted with MFA, enter MFA code. Otherwise press enter to skip.
MFA: mfa-code_or_enter_to_skip

The machine user management CLI stores an access token on your local machine so you only have to sign in once per 24-hour period.

Get help using the CLI

Display CLI usage information using the usermgmt_platform help command. See Use the CLI for the list of platforms supported.

usermgmt_platform help

The following help information is displayed:

A command-line interface (CLI) to manage machine user accounts to automate
Apigee identity zone management. Use the CLI to create, list, delete,
and reset the password for machine users.

Usage:
  usermgmt [flags]
  usermgmt [command]

Available Commands:
  create  Creates a machine users in an identity zone.
  delete  Deletes a machine users in an identity zone.
  help    Help about any command
  list    Lists the machine users in an identity zone.
  reset   Resets the password for a machine user in an identity zone.

Flags:
  -h, --help               help for usermgmt

Use "usermgmt [command] --help" for more information about a command.

Display help on a specific command by passing both the command and the -h or --help flag on the command line.

For example, to get help on the list command:

usermgmt_platform list -h

The following help information is displayed:

Lists the machine users in an identity zone.

Usage:
  usermgmt list [flags]

Flags:
  -h, --help   help for list

Create a machine user in an identity zone

Create a machine user in an identity zone using the usermgmt_platform create command. See Use the CLI for the list of platforms supported.

Enter the following command:
```
usermgmt_platform create
```
The list of identity zones is displayed:
```
myzone1
myzone2
```
Enter the name of a zone at the prompt:
```
Enter a zone name: myzone1
```
Enter a username for the machine user:
Note: The username must be an email address:
- With a domain name that matches that of the zoneadmin account creating the machine user
- With all lowercase letters
.
```
Create a Machine User
Username: machineuser1@mycompany.com
```

Enter a password for the machine user. Re-enter the password when prompted.

Password: password
Re-enter password: password

The user is created.

Created machine user machineuser1@mycompany.com

List all machine users in an identity zone

List all machine users in an identity zone using the usermgmt_platform list command. See Use the CLI for the list of platforms supported.

Enter the following command:
```
usermgmt_platform list
```
The list of identity zones is displayed:
```
myzone1
myzone2
```
Enter the name of a zone at the prompt:
```
Enter a zone name: myzone1
```
The list of machine users in the identity zone is displayed:
```
Machine users in the zone:
machineuser1@mycompany.com
    
```

Reset the password for a machine user in an identity zone

Reset the password for a machine user in an identity zone using the usermgmt_platform reset command. See Use the CLI for the list of platforms supported.

Enter the following command:
```
usermgmt_platform reset
```
The list of identity zones is displayed:
```
myzone1
myzone2
```
Enter the name of a zone at the prompt:
```
Enter a zone name: myzone1
```

Enter the username for the machine user for which you want to reset the password:

Reset User Password
Enter the username for the machine user
Username: machineuser1@mycompany.com

Enter a new password for the machine user. Re-enter the password when prompted.

Enter the new password: password
Re-enter password: password

The password is reset.

Reset password for machine user machineuser1@mycompany.com

Delete a machine user in an identity zone

Delete a machine user in an identity zone using the usermgmt_platform delete command. See Use the CLI for the list of platforms supported.

Enter the following command:
```
usermgmt_platform delete
```
The list of identity zones is displayed:
```
myzone1
myzone2
```
Enter the name of a zone at the prompt:
```
Enter a zone name: myzone1
```

Enter the username for the machine user that you want to delete:

Delete User
Enter the username for the machine user
Username: machineuser1@mycompany.com

The machine user is deleted.

Deleted user machineuser1@mycompany.com

Assign required roles to the machine user in your Edge organization

Using the UI, add the machine user to your SAML-enabled Edge organization and assign it the required roles (such as organization administrator), as described in Adding users.

Get the machine user's OAuth2 tokens

You can automate the token generation process and handle token caching for machine users with the acurl⁽¹⁾ and get_token⁽¹⁾ utilities, as described in OAuth2 for machine users and Machine users in SAML zones.

To get the machine user's OAuth2 tokens manually with curl:

Use your preferred URL encoding tool to encode the username and password of the machine user.
Warning: Use an internal URL encoding tool to ensure that the machine user credentials will not be compromised.

Generate the initial access and refresh tokens by calling the SAML token endpoint, shown in the following example:

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://zoneName.login.apigee.com/oauth/token -s \
  -d 'grant_type=password&username=machineusername&password=machineuserpassword'

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

Pass the access token to an Edge management API call as the Bearer header:

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

When the access token expires, you can refresh it by sending the refresh token to the SAML token endpoint, as the following example shows:

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://zoneName.login.apigee.com/oauth/token \
  -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

⁽¹⁾ Copyright 2023 Google LLC
The usermgmt, acurl, and get_token tools are made available as "Software" under the agreement governing your use of Google Cloud Platform, including the Service Specific Terms available at https://cloud.google.com/terms/service-terms.