2.4 Certificate Management APIs

2.4.1 Refresh Metadata of SAML 2.0 Trusted Providers

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:

Invoke the API to get the Identity Server clusters. Parse the response to get the cluster URL.

Sample URL: https://192.168.0.0:8443/amsvc/v1/idpclusters

Response:
```
...
idpCluster uri="https://192.168.0.0:8443/amsvc/v1/idpclusters/SCC7c9nsp"> ...
```
For each cluster URL, invoke the API to get the list of service providers or identity providers, depending on the provider that needs to be refreshed.
```
https://192.168.0.0:8443/amsvc/v1/idpclusters/SCC7c9nsp/serviceproviders OR
https://192.168.0.0:8443/amsvc/v1/idpclusters/SCC7c9nsp/identityproviders
```

Parse the response to get the URL of the trusted provider to be updated.

Response Snippet:

<serviceProvider uri="https://192.168.0.0:8443/amsvc/v1/idpclusters/SCC7c9nsp/serviceproviders/STSPr9spkh">
<displayName>of365</displayName>
<protocol>saml2</protocol>
...

Invoke the metadata refresh API to apply the updated metadata as follows.
Invoke the trusted roots API to add the root CA of the signing certificate specified in the metadata. This step is needed if the certificate has changed. For more information, see Section 2.4.2, Import Trusted Root Certificates.
Invoke the Apply changes API to send these changes to Identity Servers in that cluster.
Send PUT request to the cluster URL https://192.168.0.0:8443/amsvc/v1/idpclusters/SCC7c9nsp/ with input
```
{ "update" : "all" }
```
Sample Script: You can access a sample script that implements all the steps listed here on the Update MetaData From File page.

Sample Request:

URL format: <trusted provider URL in step 3>/metadata

Send a PUT request to https://192.168.0.0:8443/amsvc/v1/idpclusters/SCC7c9nsp/serviceproviders/STSPr9spkh/metadata with metadata as input. Metadata can be specified as a text or a URL.

Sample text input:

NOTE:The metadata text must be URL encoded.
```
{
"metadata" :
"%3C%3Fxml%20version%3D%221.0%22%20encoding%
3D%22UTF-8%22%20%3F%3E%3Cmd%3AEntityDescriptor%20xmlns%3
Amd%3D%22urn%3Aoasis%3Anames%3Atc%3ASAML%3A2.0%3Ametadata%
22%20ID%3D%22idXMuLnBrALGXkMAMUXd9WXvS0aEI%22%20entityID%
3D%22https%3A%2F%2Fpriyankasb.blr.novell.com%2Fnidp%2Fsaml
2%2Fmetadata%22%3E%3Cds%3ASignature%20xmlns%3Ads%3D%22http
%3A%2F%2Fwww.w3.org%2F2000%2F09%2Fxmldsig%23%22%3E%0A%3Cds
...............
%3C%2Fmd%3AEntityDescriptor%3E"
}
```
Sample metadata URL input:
```
{
"metadata" : "https://164.99.87.129:8443/nidp/saml2/metadata"
}
```
Response: 200 OK

2.4.2 Import Trusted Root Certificates

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

IMPORTANT:

The certificate must be URL encoded.
Apply changes to all devices that might use this certificate.

2.4.3 Renew Certificates

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----"
}

IMPORTANT:

An update is required for all devices using that certificate. Updating the connector certificate requires tomcat restart.
The certificate specified must be the PEM formatted public certificate and must be URL encoded.
Entire chain must be specified. Entity Cert > Intermediate 1 > Intermediate 2 > Root CA, where > indicates that the Entity certificate was signed by Intermediate 1 and so on.