Using SAML with automated tasks

Edge for Private Cloud v4.18.01

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

Edge supports automated token generation through the use of 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.

Create a machine user

Use the apigee-ssoadminapi.sh utility to create a machine user for a SAML organization. See Using apigee-ssoadminapi.sh for more. You can create a single machine user 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 SAML identity provider. 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:

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

where:
- SSO_ADMIN_NAME is the admin username defined by the SSO_ADMIN_NAME property in the configuration file used to configure the Edge 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.

Obtain and refresh machine user token

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.
The call prints the access and refresh tokens to the screen. Save the tokens for later use.
Pass the access token to an Edge management API call as the Bearer header:
> curl -H "Authorization: Bearer access_token" http://ms_IP_DNS:8080/v1/organizations/orgName

where orgName 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'

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

Create a machine user by using 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:

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