2.3 Administration API Use Cases

This API returns the health of Access Manager devices (Identity Servers and Access Gateways). The API returns the health for the following levels:

You can use this API for integration with external systems, such as NOC to view the status of Access Manager devices and the remote web servers.

Sample Request

Invoke a URL similar to https://192.168.0.0:8443/amsvc/v1/health?expand=4

The expand parameter specifies the level of detail that is returned. Accepted values are 1,2,3, and 4. 4 returns the maximum detail for all devices.

Sample Response

<amService xmlns="urn:novell:schema:am:service">
<health status="noReport" uri="https://192.168.0.0:8443/amsvc/v1/health">
<idpClusterHealthList status="Green" total="1">
<clusterHealth status="Green" uri="https://192.168.0.0:8443/amsvc/v1/idpclusters/SCC7c9nsp/health">
<instanceID>SCC7c9nsp</instanceID>
<displayName>IDPCluster</displayName>
<deviceHealthList total="1">
<deviceHealth status="Green"
uri="https://192.168.0.0:8443/amsvc/v1/idpclusters/SCC7c9nsp/devices/idp-CC1B3FFB0BC40AD8/health">
<instanceID>idp-CC1B3FFB0BC40AD8</instanceID>
<displayName>192.168.0.6</displayName>
<serviceHealthList total="5">
<serviceHealth status="Passed">
<serviceName>Config Datastore</serviceName>
<message>Operating properly</message>
</serviceHealth>
...

This API returns the statistics for all Identity Servers and Access Gateways in Access Manager.

Sample Request

Send a GET request to a URL. For example, https://192.168.0.0:8443/amsvc/v1/statistics.

Sample Response

<amService xmlns="urn:novell:schema:am:service">
<response code="SUCCESS"/>
<statistics uri="https://192.168.0.0:8443/amsvc/v1/statistics">
<idpClusterStatisticsList total="1">
<clusterStatistics uri="https:// 192.168.0.0:8443/amsvc/v1/idpclusters/SCC7c9nsp/statistics">
<instanceID>SCC7c9nsp</instanceID>
<displayName>IDPCluster</displayName>
<deviceStatistics uri="https:// 192.168.0.0:8443/amsvc/v1/idpclusters/SCC7c9nsp/devices/idp-CC1B3FFB0BC40AD8/statistics">
<instanceID>idp-CC1B3FFB0BC40AD8</instanceID>
<displayName>192.168.0.6</displayName>
<statisticList total="90">
<statistic displayName="Cached Sessions">100</statistic>
<statistic displayName="Historical Maximum Logins Served">890</statistic> ...

Trusted providers periodically refresh their metadata. Some metadata repositories, such as InCommon.org, publish an updated metadata everyday. Therefore, an automated approach for refreshing the metadata of all service providers and updating the associated trusted root certificates helps relieve the administrator of this frequent chore and ensures that the system is up to date for security reasons.

Perform the following steps:

You can use this API to import a trusted root certificate. This is usually used in conjunction with the metadata refresh API.

Sample Request:

Send a PUT request to https://192.168.0.0:8443/amsvc/v1/security/trustedroots/myProviderCA where "myProviderCA" is the trusted root name displayed on Administration Console.

The URL encoded public CA certificate must be specified as input.

{
"certificate" : "----BEGIN%20CERTIFICATE----
%0AMIIFNDCCBBygAwIBAgIkAhwR%......
----END%20CERTIFICATE----"
}

Response: 200 OK

You can use this API to renew the certificates that are available through Administration Console. Specify the certificate name and the certificate content as input to the API.

Sample Request:

Send a PUT request to https://192.168.0.0:8443/amsvc/v1/security/certificates/test-signing with the following input, where the intermediate certificates are optional:

{
"entityCertificate" :"----BEGIN%20CERTIFICATE----%0AMIIFDjCCA%2FagAwIBAg
IkAhwR%2F6b94LzCZy%2BK8kSqu----END%20CERTIFICATE----",
"rootCertificate" :"----BEGIN%20CERTIFICATE----%0AMIIFDjCCA%2FagAwIBAg
IkAhwR%2F6b94LzCZy%2BK8kSqu----END%20CERTIFICATE----",
"intermediateCertificate1" :"----BEGIN%20CERTIFICATE----
%0AMIIFDjCCA%2FagAwIBAgb94LzCZy%2BK8kSqu----END%20CERTIFICATE----",
"intermediateCertificate2" :"----BEGIN%20CERTIFICATE----
%0AMIIFDjCCA%2FagAwIBAgzCZy%2BK8kSqu----END%20CERTIFICATE----"
}

These APIs allow fetching and terminating all active sessions of a given user.

Perform the following steps:

Sample Request

https://192.168.0.0:8443/amsvc/v1/idpclusters/SCC7c9nsp/sessions?userid=admin
Use HTTP GET to retrieve all active sessions for the user 'admin'. 
Use HTTP DELETE method to terminate all sessions for the user 'admin'.

Sample Response

{
   "userDN" : "cn=admin, o=novell",

   "sessionDetails": { ["identityServer":"192.168.0.6", "sessionCount":"1"],

["identityServer":"192.168.0.7", "sessionCount":"2"]

}
}

You can use this API to purge the Access Gateway server cache. Periodic purging of the cache frees up storage. You can select to purge the content of the purge list that has already been configured on Administration Console or purge all content cached on the server.

Perform the following steps:

Sample Request

PUT request to https://164.99.86.7:8443/amsvc/v1/agclusters/ce035b033e6c7f29/devices/ag-6459CF981F6FD178

With input { "purge" : "list" }

Specify "list" to purge the content configured in the Purge List on the UI.

Use "all" to purge the entire cache.

Response: 200 OK

You can use these APIs to scale up or scale down Access Gateway and Identity Servers. These APIs can only assign or delete a node in an existing cluster. For more information about how to configure these APIs, see the following configurations.