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.

2.4.4 Certificate Management API

Perform the following steps to list the expired or expiring certificates, import, renew, and update certificates:

List the expired or expiring certificates using the following GET method:

URL: https://<AC IP/Host>:<Port>/nps/api/v1/certificates/list

QueryParams

isExpired= true/false (not mandatory)
expiringInDays= 100 (not mandatory)

Sample Response

[
    {
        "certName": "test-signing",
        "subject": "O=novell, OU=accessManager, CN=test-signing",
        "validFrom": "January 08, 2026, 16:50:50",
        "validTo": "January 08, 2024, 16:50:50",
        "isExpired": false
    },
    {
        "certName": "test-encryption",
        "subject": "O=novell, OU=accessManager, CN=test-encryption",
        "validFrom": "January 08, 2026, 16:50:51",
        "validTo": "January 08, 2024, 16:50:51",
        "isExpired": false
    }
]

Find the certificate used in the applications using the following GET method:

URL: https://<AC IP/Host>:<Port>/nps/api/v1/clusters/{clusterId}/apps

QueryParam

appType -> filter apps based on type (SAML2 IDP/SAML2 SP)
  search -> filter based on search key (name and)
certName -> find app based on certificate used (singing/encryption)

Sample Response

[
    {
        "id": "1234",
        "name": "Test Saml SP",
        "type": "SAML2 SP",
        "metadaExpiration": "January 08, 2025, 16:50:50",
        "enabled": true,
   "primarySigningCert":"test-cert",
 "secSigningCert": "test-sec-cert",
"encrCert": "test-encr",
    }
]

Import the certificate using the following POST method:

URL: https://<ACIP/Host>:<Port>nps/api/v1/certificates/importCertificate

FormData

importCertReq: {
  "certificateName": "certName",
  "certEncPwd": "pwd",
  "certificateFileType": "JKS", //for file type JKS
  "certificateAlias": "test_import2",
  "certImportTo":"Keys/TrustRooots" 
                       // Keys: Import to Certificates, TrustRoots: Import TrustRoots
}

certificate: file //PEM/PFX/PKCS/DER format

certificateContent: 'cert content' is supported only for PEM

Add the certificate to KeyStore using the POST request:

URL: https://<ACIP/Host>:<Port>nps/api/v1/certificates/addCertificateToKeyStore

RequestBody

{
"certsKeyStoreList": [{
"certName": "cert name",
"certAlias": "cert alias",
//connector,consumer,provider, alias has to be "tomcat"
"keyStore": "SCC6dgqr4-signing",
"avoidPostUpdateCmd": "true/false"
// connector,consumer,provider -- true signing,encryption -- false
"overwriteSameAlias":"true/false"
}]
}

Assign certificate to the applications using the POST method:

NOTE:Assigning the singing or encryption certificate to API is supported only to SAML2 applications.

URL: https://<ACIP/Host>:<Port>nps/api/v1/clusters/{clusterId}/saml2/assignCertificates

RequestBody
```
[
  {
    "appId": "STSPb5tfsa",
    "primarySigningCertName": "test_import4",
    "secSigningCertName": "test_import2",
    "encryptionCertName": "",
    "appType": "SAML2"
  }
]
```
Swap the certificates using the following PUT method:

NOTE:To swap the existing assigned certificate, no payload is required for the API. The saml2 application must have both primary and secondary certificates. To assign new certificate use API 6.

URL: https://<ACIP/Host>:<Port>nps/api/v1/clusters/{clusterId}/saml2{providerId}/swapcertificates

Update the expired certificate (ROMA API) using the following PUT method:

URL: https://<ACIP/Host>:<Port>/roma/rest/certificates/updateCertificateFiles/{certName}

Path Param

certName -> Certificate name to be updated

Form Data

entityCert -> pem/der format file or Certificate Content (Mandatory)
            rootCert -> pem/der format file or Certificate Content (Mandatory)
            interCert1 -> pem/der format file or Certificate Content (Mandatory)
            interCert2 -> pem/der format file or Certificate Content (Mandatory)

Update the expired certificate (NPS API) using the following PUT method:

URL : https://<ACIP/Host>:<Port>/nps/api/v1/certificates/updateCertificate/{certName}

Path Param

certName -> Certificate name to be updated.

Form Data

 entityCert -> pem/der format file or Certificate Content (Mandatory)
            rootCert -> pem/der format file or Certificate Content (Mandatory)
            interCert1 -> pem/der format file or Certificate Content
            interCert2 -> pem/der format file or Certificate Content