You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/security/oauth/access-tokens). 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.

> [!NOTE]
> **Note:** The machine user's OAuth2 tokens will work for Edge API calls only if the following are true:
>
> - The Edge organization is mapped to a SAML identity zone. See [Connect an Edge organization to an identity zone](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge.md.txt#connect-org-zone)
> - The machine user is added to the SAML-enabled organization and has the required roles assigned. See [Assign required roles to machine user in your Edge organization and assign roles](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#assign-roles).

## 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](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#machiner) |
| 2 | [Assign required roles to the machine user in your Edge organization](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#assign-roles) |
| 3 | [Get the machine users's OAuth2 tokens](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#get-the-machine-users-oauth2-tokens) |

**Video:** Watch a short video to learn about how to automate access to the Apigee Edge APIs using machine user credentials.
<iframe allowfullscreen frameborder="0" height="315" src="https://www.youtube.com/embed/tSQez1VJiRQ" width="560"></iframe>

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

> [!NOTE]
> **Note:** You must be a **zoneadmin** to create and manage machine user accounts for identity zone management in Apigee Edge. To have the zoneadmin role assigned to your Apigee Edge account, contact [Apigee Support](https://cloud.google.com/apigee-api-management/support/). For more information, see [About the zoneadmin role](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge.md.txt#zoneadmin).

### Use the CLI

To use the machine user management CLI, first download and untar the following file:
[`usermgmt.tar.gz`](https://storage.googleapis.com/usermgmt-cli-alpha/usermgmt.tar.gz)[^(1)^](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#note1)

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](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#create) |
| `delete` | [Delete a machine user in an identity zone](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#delete) |
| `help` | [Get help using the CLI](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#help) |
| `list` | [List all machine users in an identity zone](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#list) |
| `reset` | [Reset the password for a machine user in an identity zone](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#reset-password) |

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

### Sign in to the CLI

> [!NOTE]
> **Note:** You cannot access the CLI if you sign in using your company single sign-on (SSO) credentials that are processed through your company's third-party SAML identity provider. You must use your Edge user account (with zoneadmin privileges).
>
> If you do not have an Edge user account or
> are not sure, [create an Apigee Edge account](https://docs.apigee.com/api-platform/get-started/creating-apigee-edge-account). If your Edge user account already exists, you will be notified.
> If you have an Apigee Edge user account but have forgotten your password, see [Reset your password](https://docs.apigee.com/api-platform/get-started/sign-in-manage-account.md.txt#password).

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_<var translate="no">platform</var> help** command. See [Use the CLI](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#use-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_<var translate="no">platform</var> create** command.
See [Use the CLI](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#use-cli) for the list of platforms supported.

1. Enter the following command:

   ```
   `usermgmt_platform create`
   ```

   The list of identity zones is displayed:

       myzone1
       myzone2

2. Enter the name of a zone at the prompt:

       Enter a zone name: myzone1

3. Enter a username for the machine user:

   > [!NOTE]
   > **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

4. 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_<var translate="no">platform</var> list** command. See [Use the CLI](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#use-cli) for the list of platforms supported.

1. Enter the following command:

   ```
   `usermgmt_platform list`
   ```
   The list of identity zones is displayed:

       myzone1
       myzone2

2. 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_<var translate="no">platform</var> reset** command. See [Use the CLI](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#use-cli) for the list of platforms supported.

> [!NOTE]
> **Note:** If you attempt to reset the password to the existing password, the command will fail.

1. Enter the following command:

   ```
   `usermgmt_platform reset`
   ```

   The list of identity zones is displayed:

       myzone1
       myzone2

2. Enter the name of a zone at the prompt:

       Enter a zone name: myzone1

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

4. 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_<var translate="no">platform</var> delete** command. See [Use the CLI](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#use-cli) for the list of platforms supported.

1. Enter the following command:

   ```
   `usermgmt_platform delete`
   ```
   The list of identity zones is displayed:

       myzone1
       myzone2

2. Enter the name of a zone at the prompt:

       Enter a zone name: myzone1

3. 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](https://docs.apigee.com/api-platform/system-administration/managing-organization-users.md.txt#addingusers).

## Get the machine user's OAuth2 tokens

> [!NOTE]
> **Note**: An OAuth2 access token is valid for 12 hours and the refresh token is valid for 30 days.

You can automate the token generation process and handle token caching for machine users with the
`acurl`[^(1)^](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#note1) and `get_token`[^(1)^](https://docs.apigee.com/api-platform/system-administration/automating-tasks.md.txt#note1) utilities, as described in [OAuth2 for machine users](https://docs.apigee.com/api-platform/system-administration/using-oauth2.md.txt#oauth2-for-machine-users) and [Machine users in SAML zones](https://docs.apigee.com/api-platform/system-administration/using-saml.md.txt#machine).

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

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

2. 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`.
3. 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
   ```
4. 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'
   ```

*** ** * ** ***

**^(1)^** 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>.

*** ** * ** ***