WS Management API

The WS Management API provides a set of tools access and manage the gateway.
gateway91
The WS Management API provides a set of tools access and manage the
Layer7 API Gateway
.
3
The following tools are available:
  • Management Client:
    This is a console utility that provides access to the management service.
  • Management Java API:
    The management Java API is a library that can be used for integration of
    API Gateway
    management into other products. The Java API requires Java 7. The current API version is 1.2. 
  • Management SOAP service:
    The management SOAP service, when published as an internal service, is used by the other components and can also be used directly by third party developers. The SOAP service uses SOAP 1.2. The namespace is:
    http://ns.l7tech.com/2010/04/gateway-management
    . WS-Management is used for the management SOAP service.
Management Details
The WS Management API manages the following resources and supports CRUD operations.
Resource Type
WS-Man Resource URI
Look up by:
Notes
Security Zoneable
Active Connector
activeConnectors
id, name
Added in version 8.0
Y
Assertion Security Zone
assertionSecurityZones
id, name
Added in version 8.0
Y
Cluster Property
clusterProperties
id, name
Excludes hidden properties (e.g., license)
 
Custom Key Value
customKeyValues
id, name
New entity in v8.0 for Custom Assertions API
 
Encapsulated Assertion
encapsulatedAssertions
id, guid, name
Import/export capability added in version 8.2.0
Y
Email Listeners
emailListeners
id, name
Added in version 8.2.0
Y
Folder
folders
id
 
Y
Generic Entity
genericEntities
id, name
 
 
HTTP Options
httpConfigurations
id
Added in version 8.2.0
Y
Identity Provider
identityProviders
id, name
Note this is for providers, not identities
LDAP browse password is write only
Y
Interface Tag
interfaceTags
id, name
Used with listen ports, etc.
Note: Also need CRUD permission for Cluster Property with "name=interfaceTags".
 
JDBC Connection
jdbcConnections
id, name
Password is write only
Y
JMS Destination
jmsDestinations
id
 
Y
Listen Port
listenPorts
id, name
 
Y
Policy
policies
id, name
Does not include revisions
Y
Policy Alias
policyAliases
id
Added in version 8.2.0
Y
Private Key
privateKeys
id
The certificate chain for a private key can be changed using an update.
When a private key is stored in an HSM, access may be restricted. For example, you may not be able to export the private key.
Y
Published Service Alias
serviceAliases
id
Added in version 8.2.0
Y
Resource Document
resources
id, uri
 
Y
Revocation Checking Policy
revocationCheckingPolicies
id, name
Full CRUD support in version 8.2.0
Y
Roles & Permissions
role
id
Added in version 8.2.0.
 
Security Zone
securityZones
id, name
Added in version 8.0
 
Service
services
id, policy GUID
 
Y
CA Single Sign-On Configuration
siteMinderConfigurations
id, name
Added in version 8.0
Y
Stored Password
storedPasswords
id, name
Password is write only
Y
Trusted Certificate
trustedCertificates
id
 
Y
Item Naming and Creation
Item names may not start or end with white space. Any leading or trailing white space in the name is automatically removed when the item is created.  Folders, policies, and services may be moved between folders.
Management Methods
Some managed items from the following table expose additional methods for custom operations:
Item
Method
Description
Policy, Service
Export Policy
Export the policy for the item (including dependencies).
Policy, Service
Import Policy
Import the policy for the item (including dependencies).
Policy, Service
Set Version Comment
Sets a version comment of the currently active policy/service or a policy version number specified in the
VersionNumber
element.
Policy, Service
Validate Policy
Validate the policy for the item or an arbitrary policy.
Private Key
Create Key
Create a new key.
Private Key
Export Key
Export a private key as PKCS#12 file.
Private Key
Generate CSR
Generate a Certificate Signing Request for use with a new key.
Private Key
Import Key
Import a private key from a PKCS#12 file.
Private Key
Set Key Purpose
Set the Special Purposes for a key (e.g., SSL, CA, Audit Signing, Audit Viewer).
Roles & Permissions
Add Assignments
Add assignment(s) to a role.
Roles & Permissions
Remove Assignments
Remove assignment(s) from a role.
Policy Import/Export
Policies may be imported and exported, similar to the functionality provided in the Policy Manager. When importing a policy, you can map a policy dependency (for example, identity provider) to an existing item on the target Gateway. Alternatively, you can choose to ignore or delete the assertions that reference these items.
The following table summarizes the resolution options that are available when a matching dependency cannot be found.
Item
Map
Ignore
Delete
Active Connector
Y
Y
Y
Custom Assertion
 
Y
Y
Global XML Schema
 
Y
Y
Identity Provider
Y
Y
Y
JDBC Connection
Y
Y
Y
JMS Queue
Y
Y
Y
Policy Fragment**
 
 
 
Private Key
Y
Y
Y
CA Single Sign-On Configuration
Y
Y
Y
Stored Passwords
Y
Y
Y
Trusted Certificate
Y
Y
Y
**See
"Policy Fragment Mismatch"
below
Be sure to review the import results to see the messages generated.
Policy Fragment Mismatch
When an incoming policy fragment has the same identifier (GUID) as a fragment on the target Gateway, the two fragments must match or else the policy import may fail. If failure occurs due to a policy fragment mismatch, you can still import the policy using the "
-force
" option. When force is used, the conflicting fragments are not imported; the corresponding fragment on the target Gateway is used instead.
Example:
If incoming fragment "A" conflicts with existing fragment "B", then any reference to "A" in the imported policy (after the "force" option is used) is automatically updated to reference "B" instead.
Policy Validation
Validating a policy will produce a validation report consisting of a collection of validation messages. Each message relates to a specific assertion within the policy, with messages flagged as either "Warning" or "Error". For more information on each type, see Validating a Policy.
To help you match up a validation message against the relevant assertion, the following numbering system is used:
  • An ordinal number indicates the absolute position of the assertion in question within the policy. This ordinal count starts with "2" for the first assertion and is numbered contiguously through the policy, including assertions within included fragments. (There is a hidden "All assertions must evaluate to true" folder at the root of every policy that occupies the number "1" ordinal position.)
  • A series of position numbers that can help you more easily locate the assertion within a large policy. Using these position numbers, every assertion and child assertion has a separate count beginning with "0"
Consider the following example:
image2014-9-30 11:37:15.png
This is how the assertions will be referenced in a validation report:
  • "Child assertion A" is ordinal "4""Child assertion A" referenced by position is "1,0" (where "1" represents the position of assertion A's parent and "0" represents the position of A itself)
  • "Child assertion C" is ordinal "7""Child assertion C" referenced by position is "1,2,0"
  • Child assertion E" is ordinal "11"Child assertion F" referenced by position is "3,0"
  • "Route via HTTP" is ordinal "9" and is referenced by position "3"
Using the Management Client
The Management Client is a console utility that provides access to all features of the management API, except for policy validation. The client can run under Red Hat Enterprise Linux (RHEL), CentOS, or Oracle Solaris (refer to Requirements and Compatibility for supported versions).
To run the Management Client:
Enter the following command:
./gatewayManagementClient.sh [
<url
>|
<host>
|
<host:port>
] [
<command>
] [
<option(s)>
]
*
Where:
  • "
    <url>"
    is the URL of the target Gateway (for example, "https://gateway.mycompany.com:8443/wsman")
Or you can optionally specify:
"<host>"
is the hostname of the target Gateway (for example, "gateway.mycompany.com")
"<host:port>"
is the hostname and optionally the port number of the target Gateway (for example, "gateway.mycompany.com:9443")
  • "<command>"
    is a client command 
  • "<option(s)>"
    is one or more options for the command 
The following defaults are used for the port and path if only a hostname or hostname and port number is supplied:
Default port:
8443
Default path:
wsman
Examples:
Specifying:
gateway.mycompany.com
(host only)
Results in: _https://gateway.mycompany.com:8443/wsman_
Specifying:
gateway.mycompany.com:9443
(host and port)
Results in: _https://gateway.mycompany.com:9443/wsman_
Specifying: _https://gateway.mycompany.com:9443/wsman2_ (URL)
Results in: _https://gateway.mycompany.com:9443/wsman2_
The Management Client will permit HTTP connections to be used, but this is insecure and not recommended.
Client Commands and Options
The following lists the commands and options that can be used with the client. Options in bold must be specified; all others are optional.
Command
Description
Options
Notes
create
Create entity
in, inFile, outFile, type
One of in/inFile is required
delete
Delete entity
id, name, type
One of id/name is required
get
Retrieve entity
id, name, outFile, type
One of id/name is required
put
Update entity
in, inFile, type
One of in/inFile is required
enumerate
Enumerate items of selected type(s)
outFile, type
 
generatecsr
Generate a CSR (Certificate Signing Request)
id, type, outFile, csrDn
 
export
Export policy
id, type, outFile
 
import
Import policy
id, in, inFile, type
One of in/inFile is required
validate
Validate policy
id, in, inFile, type
Use id to validate an existing policy, in/inFile for a modified policy
createkey
Create private key
id, type, inFile
Input file specifies all options (Subject DN, Key type, Expiry, etc)
exportkey
Export private key
id, type, outFile, keyAlias, keyPassword
 
importkey
Import private key
id, inFile, type, keyAlias, keyPassword
 
keypurposes
Set special purposes for a key
id, type, keyPurpose
Sets specified purposes, clears purpose from other key(s)
The following table describes each option in more detail.
Option
Description
-force
Force update (skip version check and ignore policy fragment mismatch)
Normally, an item's version number is checked during updating to ensure that the current version is being updated. Use the
force
option if version checking is not desirable (for example, items are being versioned externally)
-genericEntityType
Used in conjunction with
-name
to uniquely get a generic entity.
-guid
<value>
The GUID (Globally Unique Identifier), for items that support GUID lookup.
Currently, the only entity that supports GUID is Policy.
-id
<value>
The item identifier
-import
<instruction>
Used with the "
import
" command to provide additional instructions for the import. For more information, see
"Import Instructions"
.
-in
<value>
The input item
-inFile
<file>
The file from which to read the input item.
You can use a "-"(hyphen) in place of <file> to read from the standard input, i.e.:
-inFile -
-name
<value>
The item name, for items that support name lookup.
-outFile
<file>
The file to write the output item to; use the "-safe" option to not overwrite an existing file.
You can use a "-"(hyphen) in place of <file> to write to the standard output, i.e.:
-outFile –
When creating a new item with sensitive data present in the "infile", this sensitive data will be revealed in the "outfile". Be sure to take the necessary precautions if this is the case.
-safe
Prevents overwriting of an existing file. When creating an "-outFile <file>", abort if "<file>" already exists in the specified path.
-type
<value>
The item type; for a list of the available values, see the "Type Name" column.
The following options can be used with
any
command or with
no
command:
 
-help
Displays help for the command or displays global help if no command is specified.
-password
<value>
The password to use to log onto the Gateway.
-passwordFile
<file>
The file from which to read the password.
Use this option if you do not wish to specify the password on the command line.
See
"
Using text files to input passwords
"
below for suggestions to ensure the password is not rejected.
-proxyHost
<value>
The hostname of the HTTP proxy server to use.
If an invalid proxy server is entered, the Gateway Management Client will fall back to not using a proxy rather than failing.
-proxyPort
<value>
The port of the HTTP proxy server to use.
If an invalid port is entered, the Gateway Management Client will fall back to not using a proxy rather than failing.
-proxyUsername
<value>
The username to use with an HTTP proxy server.
-proxyPassword
<value>
The password to use with an HTTP proxy server.
-proxyPasswordFile
<value>
The file from which to read the proxy password.
Use this option if you do not wish to specify the password on the command line.
See
"
Using text files to input passwords
"
below for suggestions to ensure the password is not rejected.
-skipVerifyCertificate
To disable trust checking for the server's SSL certificate.
Use this option to permit a connection even though the server certificate is not trusted when using SSL.
 
Use this option with caution as it introduces a security risk.
-skipVerifyHostname
To disable hostname verification.
Use this option to permit a connection even though the hostname does not match the server certificate when using SSL.
Use this option with caution as it introduces a security risk.
-username
<value>
The user name to use to log onto the CA API Gateway.
-version
Show the version of the Management Client. Use this option without any command.
The following options are available for
private key
commands:
 
-keyAlias
<value>
The alias (to use) for the key in the PKCS#12 keystore.
-keyPassword
<value>
The password (to use) for the PKCS#12 keystore.
-keyPasswordFile
<value>
The password (to use) for the PKCS#12 keystore.
See "Using text files to input passwords" below for suggestions to ensure the password is not rejected.
-keyPurpose
<value>
A purpose for the key (option can be repeated).
-csrDn
<value>
The DN to use in the generated CSR.
Using text files to input passwords
If you are inputting the password from a text file, it is important that the file is free from any extraneous line breaks (which may be introduced by certain editors in Linux), as this will cause validation failures.
One way to create a text file with no line breaks is to use this command:
echo -n "password" > password.txt
You can remove line breaks from an existing file using this command:
cat password.txt | tr -d '\n' > password2.txt
These are especially relevant to the following commands:
-passwordFile
-proxyPasswordFile
-keyPasswordFile
Import Instructions
When using the "
-import
" option with the "
import
" command, you can use the instructions in the following table to control how missing or conflicting policy dependencies are handled.
Instruction
Description
accept
<info>
The dependency is imported as is.
remove
<info>
Any assertions using the dependency are not imported.
rename
<info>
The dependency is renamed and imported.
replace
<info>
The dependency is replaced with an alternative.
For each instruction,
<info>
is where you supply information to identity the dependency and any additional information as required by the type of instruction.
Examples:
-import accept IdProviderReference 10231
  • Import assertions referencing the provider as-is.
-import remove IdProviderReference 10231
  • Do not import assertions referencing the provider
-import replace IdProviderReference 10231 23111
  • Replace references to the provider with the given ID
-import rename IncludedPolicyReference 13214 NewName
  • Rename the included policy fragment when importing
Management Client Examples
The following are examples of using the basic commands. Note that all commands must be typed on one line.
Example 1:
gatewayManagementClient.sh ssg.acmecorp.com get -type service -id 221806592 -username admin -password password -outFile out.xml
Use the Management Client to log onto the CA API Gateway at https://ssg.acmecorp.com:8443/wsman, with the credentials "admin/password" and retrieve a service with the identifier "221806592", then write the output to the file "out.xml".
Example 2:
gatewayManagementClient.sh ssg.acmecorp.com put -type clusterProperty username admin -password password -inFile in.xml
Use the Management Client to log onto the CA API Gateway at https://ssg.acmecorp.com:8443/wsman, with the credentials "admin/password" and update a cluster property using information from the input file "in.xml".
Example 3:
gatewayManagementClient.sh ssg.acmecorp.com create -type clusterProperty username admin -password password -inFile in.xml
outFile out.xml
Same as Example 2 except a new cluster property is created and any output is directed to "out.xml".
Example 4:
gatewayManagementClient.sh ssg.acmecorp.com delete -type clusterProperty id 226885632 -username admin -password password
Use the Management Client to log onto the CA API Gateway at https://ssg.acmecorp.com:8443/wsman, with the credentials "admin/password" and delete a cluster property with the identifier "226885632".
Example 5:
gatewayManagementClient.sh ssg.acmecorp.com enumerate -type identityProvider -username admin -password password -outFile out.xml
Use the Management Client to log onto the CA API Gateway at https://ssg.acmecorp.com:8443/wsman, with the credentials "admin/password" and enumerate the identity providers, placing the results in the file "out.xml".
Example 6:
gatewayManagementClient.sh ssg.acmecorp.com import -id 56789 -type service -username admin -password password –inFile in.xml -import accept IdProviderReference 10231
Use the Management Client to log onto the CA API Gateway at https://ssg.acmecorp.com:8443/wsman, with the credentials "admin/password". Import the policy export from the file "in.xml" for the service with ID "56789". When importing, the invalid dependency on the identity provider "10231" would be imported "as-is". The administrator would then need to edit the policy in the Policy Manager and select an identity provider that was valid on the target Gateway.
This example assumes that the policy export references an identity provider (perhaps via "Authenticate Against Identity Provider Assertion") that does not exist on the target Gateway. Normally this import could not proceed unless you used the "accept" instruction to dictate how to handle that dependency.
Example 7:
gatewayManagementClient.sh ssg.acmecorp.com get -type revocationCheckingPolicy -name default -username admin -password password -outFile out.xml
Use the Management Client to log onto the Gateway at https://ssg.acmecorp.com:8443/wsman, with the credentials "admin/password". Retrieve the revocation checking policy named "default" and place it in the file "out.xml".
Example 8:
gatewayManagementClient.sh ssg.acmecorp.com exportkey -type privateKey -id 2:alice -outFile alice.p12 -keyAlias alice
keyPassword password -username admin -password password
Use the Management Client to log onto the CA API Gateway at https://ssg.acmecorp.com:8443/wsman, with the credentials "admin/password". Export the private key with the alias "alice" into the output file alice.p12, using "password" as the private key password and "alice" as the alias.