Using apigee-ssoadminapi.sh

Edge for Private Cloud v4.18.05

The Edge SSO module supports two types of accounts:

  • administrator
  • machine user

The apigee-ssoadminapi.sh utility lets you manage the adminiatrator and machine users associated with the Edge SSO module.

Use the apigee-ssoadminapi.sh utility to:

  • View the list of admin/machine users
  • Add or delete admin/machine users
  • Change the password of admin/machine users

About administrator users

An administrator account on the Edge SSO module is required to manage properties of the module.

By default, when you install the Edge SSO module is creates an administrator account with the following credentials:

  • username: defined by the SSO_ADMIN_NAME property in the configuration file used to configure the Edge SSO module. The default is ssoadmin.
  • password: defined by the SSO_ADMIN_SECRET property in the configuration file used to configure the Edge SSO module.

About machine users

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.

You typically use machine users for:

  • Configuring the Apigee Developer Services portal (or simply, the portal) to communicate with Edge
  • When development environment support automation for common development tasks, such as test automation or Continuous Integration/Continuous Deployment (CI/CD).

For more, see Using SAML with automated tasks.

Installing apigee-ssoadminapi.sh

Install the apigee-ssoadminapi.sh utility on the Edge Management Server node where you installed the Edge SSO module. Typically you install the apigee-ssoadminapi.sh utility when you install the Edge SSO module.

If you have not yet installed the apigee-ssoadminapi.sh utility:

  1. Log in to the Management Server node. That node should already have apigee-service installed as described at Install the Edge apigee-setup utility.
  2. Install the apigee-ssoadminapi.sh utility used to manage admin and machine users for the Edge SSO module: 
    /opt/apigee/apigee-service/bin/apigee-service apigee-ssoadminapi install
  3. Log out of the shell, and then log back in again to add the apigee-ssoadminapi.sh utility to your path.

Viewing help information for the apigee-ssoadminapi.sh

The available commands for the utility are:

  • admin add
  • admin delete
  • admin list
  • admin setpassword
  • saml machineuser add
  • saml machineuser delete
  • aaml machineuser list
  • saml machineuser setpassword

You can view information about these commands in the /opt/apigee/apigee-ssoadminapi/README.md file. Additionally, you can specify the "-h" option to each command to view usage information.

For example, the following command:

apigee-ssoadminapi.sh admin list -h

Returns:

admin list
  --admin SSOADMIN_CLIENT_NAME      Name of the client having administrative privilege on sso
  --secret SSOADMIN_CLIENT_SECRET   Secret/Password for the client
  --host SSO_HOST                   Hostname of SSO server to connect
  --port SSO_PORT                   Port to use during request
  --ssl SSO_URI_SCHEME              Set to https, defaults to http
  --debug                           Set in debug mode, turns on verbose in curl
  -h                                Displays Help

Invoking the apigee-ssoadminapi.sh utility

You can invoke the apigee-ssoadminapi.sh utility by passing all properties as command line arguments, or in interactive mode by responding to prompts.

For example, to specify all required information on the command line to see the list of admin users:

apigee-ssoadminapi.sh admin list --admin ssoadmin --secret Secret123 --host 35.197.94.184

Returns:

[
  {
    "client_id": "ssoadmin",
    "access_token_validity": 300
  }
]

If you omit any required information, such as the admin password, you are prompted.

In this example, you omit the values for --port and --ssl because the Edge SSO module uses the default values of 9099 for --port and http for --ssl. If your installation does not use these defaults, specify them:

apigee-ssoadminapi.sh admin list --admin ssoadmin --secret Secret123
  --host 35.197.94.184 --port 9443 --ssl https

Alternatively, use the interactive form where you are prompted for all information:

apigee-ssoadminapi.sh admin list

You are then prompted for all required information:

SSO admin name (current): ssoadmin
SSO Admin secret (current):
SSO host: 35.197.94.184