Certificate Templates

You can use REST API calls to obtain information about certificate templates being used in the Cloudpath system.
URIs updated for 5.9

The following table lists the properties that can be used in the body of a certificate-template-related request and/or are provided in the response body. (In the "Optional" column, if a default value is applicable, it is listed in angle brackets (< >).)

Resource: Certificate Templates

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
guid String No Neither No The unique identifier for this authentication server.
name String Yes orderBy, like No The unique reference name of the authentication server.
caType   Yes in, eq, orderBy No

The type of certificate to be used: ONBOARD, MICROSOFT_CA, CUSTOM, INCOMMON, NETWORK_FX

Note: Sort order is as listed above, not alphabetical.
detail One of the following: Onboard, Incommon, MicrosoftCa, NetworkFx, or Custom. Yes Neither No This property is always includes and must match the caType provided in the template.
RADIUS Attribute Groups Object <RadiusAttributeGroup> Yes Neither No If the certificate template is not using a policy (pre-Cloudpath release 5.8), a RADIUS attribute group is provided here, detailing the information that the template provides for RADIUS.
defaultAccess

String <Enum>

 Yes orderBy , like default=REJECT When no policies are assigned, or when policies are assigned but no match is found against any of the policies, the default access for authentication is either: ACCEPT or REJECT.
allowAuthRadius Boolean Yes eq, orderBy default=true If selected, the RADIUS server will contain policy information for this certificate template.
workflowCount int No Neither default = 0 Indicates the number of workflows to which this template has been assigned.
issuedCertificateCount int No Neither default = 0 Indicates the number of issued certificates to which this template has been assigned.
authorizedEnrollmentsCount int No Neither default = 0 Indicates the number of authorized enrollments to which this template has been assigned.
links[] Link array No No No Self-referencing link, and links to: certificates, msiPackages, notifications, scepKeys, and assignedPolicies.

Resource: Onboard

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
commonNamePatern String Yes Neither No The pattern used to determine the common name for certificates generated using this template.
validPeriod Object <Embedded> Yes Neither No The timeframe for when this certificate remains valid.
keyLength Number Yes Neither No The key length: a valid number between 512 and 4049.
algorithm String <Enum> Yes Neither No The algorithm, as dictated by the CA.
  • SHA-1: The SHA-1 hash
  • SHA-256: The SHA-2 hash using 256 bits
  • SHA-384: The SHA-2 hash using 384 bits
  • SHA-512: The SHA-2 hash using 512 bits
organizationPattern String Yes Neither Yes The pattern used to determine the organization for certificates generated using this template.
unitPattern String Yes Neither Yes The pattern used to determine the organization unit for certificates generated using this template.
localityPattern String Yes Neither Yes The pattern used to determine the locality for certificates generated using this template.
statePattern String Yes Neither Yes The pattern used to determine the state for certificates generated using this template.
countryPattern String Yes Neither Yes The pattern used to determine the country for certificates generated using this template.
type String <Enum> Yes Neither

Yes; default is USER_DEVICE

 Controls whether the validity of the certificate is dependant on an identity:
  • USER_DEVICE: The validity of the certificate is based, in part, on the identity of the user (if an identity exists in the enrollment). If the user is blocked, the certificate will be blocked.
  • DEVICE: The validity of the certificate does not take into consideration the identity of the user. If the user is blocked, the certificate will not be affected.
ekuHotSpot Boolean Yes Neither

Yes; default is false

 List of the extended key usage (EKUs) object identifiers (OIDs) inserted into certificates generated using this template. If this template is being used to generate a device certificate, the certificate must contain the client EKU. If this template is being used to generate a RADIUS server certificate, the certificate must contain the server EKU. If this template is being used to generate a Domain Controller certificate, the certificate must contain both the client and the server EKUs.
ekuMsClient Boolean Yes Neither

Yes; default is false

 See "ekuHotspot" description.
ekuMsServer Boolean Yes Neither

Yes; default is true.

 See "ekuHotspot" description.
advancedPatterns Object <embedded> Yes Neither Yes Refer to the "advancedPatterns" resource table.
link         Link to the caAuthority.

Resource: validPeriod

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
notBeforeOffset Number Yes Neither No; default = 1 A number represting how to apply the notbeforeDataType property.
notBeforeDate String <Date> Yes Neither See "Description" column. If the "notBeforeDateType" (see next entry in this table) is "SPECIFIED_DATE",then this property must be set.
notBeforeDateType String <Enum> Yes Neither Yes

Indicates how to apply the date offset when defining the start period for certificates that are granted:

SPECIFIED_DATE, IMMEDIATE, HOURS_AFTER_TIME, DAYS_AFTER_TIME, WEEKS_AFTER_TIME, MONTHS_AFTER_TIME, QUARTERS_AFTER_TIM, YEARS_AFTER_TIME, END_OF_HOUR, END_OF_DAY, END_OF_WEEK, END_OF_MONTH, END_OF_QUARTER, END_OF_YEAR, HOURS_BEFORE_TIME, DAYS_BEFORE_TIME, WEEKS_BEFORE_TIME, MONTHS_BEFORE_TIME, QUARTERS_BEFORE_TIME, YEARS_BEFORE_TIME, START_OF_HOUR, START_OF_DAY, START_OF_WEEK, START_OF_MONTH, START_OF_QUARTER, START_OF_YEAR, MINUTES_AFTER_TIME, MINUTES_BEFORE_TIME, END_OF_HALF, or START_OF_HALF
notAfterOffset Number Yes Neither No; default=1 The method used to calculate the expiration date for certificates generated using this template.
notAfterDate String <Date> Yes Neither See the "description" for this property. If the "notAfterDateType" property (see next table entry) is "SPECIFIED_DATE", the notAfterDate property must be set.
notAfterDateType String <Enum> Yes Neither Default is in MONTHS.

Indicates how the date offset is to be applied when defining the expiration date for certificates that are granted:

SPECIFIED_DATE, IMMEDIATE, HOURS_AFTER_TIME, DAYS_AFTER_TIME, WEEKS_AFTER_TIME, MONTHS_AFTER_TIME, QUARTERS_AFTER_TIM, YEARS_AFTER_TIME, END_OF_HOUR, END_OF_DAY, END_OF_WEEK, END_OF_MONTH, END_OF_QUARTER, END_OF_YEAR, HOURS_BEFORE_TIME, DAYS_BEFORE_TIME, WEEKS_BEFORE_TIME, MONTHS_BEFORE_TIME, QUARTERS_BEFORE_TIME, YEARS_BEFORE_TIME, START_OF_HOUR, START_OF_DAY, START_OF_WEEK, START_OF_MONTH, START_OF_QUARTER, START_OF_YEAR, MINUTES_AFTER_TIME, MINUTES_BEFORE_TIME, END_OF_HALF, or START_OF_HALF
ocspMonitor Boolean Yes Neither

Default is false.

 As the certificate is used, the system receives OCSP requests. The system can monitor the last usage of the certificate and automatically revoke the certificate if it remains unused for an extended period of time.
ocspRevokeDays number Yes Neither No Defaults to 30 days.

Resource: advancedPatterns

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
email String Yes Neither Yes The pattern used to determine the email for certificates generated using this template.
sanOtherNamesList List <String> Yes Neither Yes The pattern used to determine the Other Name entry of the Subject Alternative Name (SAN) for certificates generated using this template. The SAN Other Name Pattern entry is a value string, which can be a short name, long name, or numerical format.
sanRfc822 String Yes Neither Yes The pattern used to determine the RFC822 (email) entry of the Subject Alternative Name (SAN) for certificates generated using this template. The SAN RFC822 Pattern entry must be in the form : "local-part@domain".
sanDnsNames List <String> Yes Neither Yes The pattern used to determine the DNS Name entry of the Subject Alternative Name (SAN) for certificates generated using this template. The SAN DNS Name Pattern must follow the 'preferred name syntax' as specified in RFC 1035.
sanUrl String Yes Neither Yes The pattern used to determine the URI entry of the Subject Alternative Name (SAN) for certificates generated using this template. The SAN URL Pattern must contain both a scheme (http, https, or ftp) and a scheme-specific-part. The scheme-specific-part must include a fully qualified domain name or IP address as the host.
sanIp String Yes Neither Yes The pattern used to determine the IP entry of the Subject Alternative Name (SAN) for certificates generated using this template. The SAN IP Pattern can be in either IPv4 or IPv6 format.
sanRid String Yes Neither Yes The pattern used to determine the RID (registered object ID) entry of the Subject Alternative Name (SAN) for certificates generated using this template. The SAN RID Pattern must be in the form of an OID string, which is a string that contains digits (0-9) and decimal points (.). For example: "1.2.3.4".
title String Yes Neither Yes The pattern used to determine the title for certificates generated using this template.

Resource: Incommon

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
adminName String Yes Neither No The username of an administrator within the inCommon admin UI.
adminPassword String Yes Neither No The password of an administrator within the inCommon admin UI.
organizationId Number Yes Neither No The organization Id required for inCommon.
apiSecret String Yes Neither No The api secret required for inCommon.
realmsList List <String> Yes Neither Yes A list of the realms from which the inCommon certificate may be issued. The name of the realm typically begins with the character "@", and can also contain a wildcard (*).
server String <Enum> Yes Neither  

The inCommon server name for this certificate.

Will be: PRODUCTION or TEST
certHasEmail Boolean Yes Neither No; default = true If true, the user's email address is included in the certificate. If false, the user's email address is not included.

Resource: MicrosoftCA

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
caUrl String No Neither No The URL of the Integration Module. This is typically similar to the following: https://servername.domain.com/
caHost String No Neither No The DNS name of the CA server.
caName String No Neither No The name of the CA. This appears in the Certificate Authority console.
requestAttributes List <String> No Neither Yes The attributes used when querying the CA. This typically includes at minimum the certificate-template name.
caChain String No Neither Yes Provides the CA chain for certificates issued by the remote CA. The certificates should be concatenated together in PEM format.
keyLength Number No Neither No The key length: A valid number between 512 and 4049.
algorithm String <Enum> No Neither No The algorithm, as dictated by the CA.
  • SHA-1: The SHA-1 hash
  • SHA-256: The SHA-2 hash using 256 bits
  • SHA-384: The SHA-2 hash using 384 bits
  • SHA-512: The SHA-2 hash using 512 bits
useStaticCredentials boolean No Neither No; default= false Indicates whether the CA should use the static credentials.
staticUserName String No Neither Yes The username to use when interacting with the external CA.
staticPassword String No Neither Yes The password to use when interacting with the external CA.
customCsr customMsCsr No Neither No Allows use of custom Csr; provide this resource if you want to apply the custom csr.

Resource: customMsCsr

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
commonNamePattern String Yes Neither Yes If the template within Microsoft CA is configured to allow the subject to be supplied by the caller in the CSR, the value or pattern specified here will be used in the CSR.
organizationPattern String Yes Neither Yes If the template within Microsoft CA is configured to allow the subject to be supplied by the caller in the CSR, the value or pattern specified here will be used in the CSR.
unitPattern String Yes Neither Yes If the template within Microsoft CA is configured to allow the subject to be supplied by the caller in the CSR, the value or pattern specified here will be used in the CSR.
localityPattern String Yes Neither Yes If the template within Microsoft CA is configured to allow the subject to be supplied by the caller in the CSR, the value or pattern specified here will be used in the CSR.
statePattern String Yes Neither Yes If the template within Microsoft CA is configured to allow the subject to be supplied by the caller in the CSR, the value or pattern specified here will be used in the CSR.
countryPattern String Yes Neither Yes If the template within Microsoft CA is configured to allow the subject to be supplied by the caller in the CSR, the value or pattern specified here will be used in the CSR.

Resource: NetworkFx

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
baseUrl String Yes Neither No The base URL for the Network FX service.
profileName String Yes Neither No The certificate profile name within the Network FX service.
organization String Yes Neither No NetworkFX requires that CSRs contain the organization. This value will be used as the organization (O) in the CSR.
organizationUnit String Yes Neither No NetworkFX requires that CSRs contain the organization unit. This value will be used as the organization unit (OU) in the CSR.
country String Yes Neither No NetworkFX requires that CSRs contain the country. This value will be used as the country (C) in the CSR.
serverChain String Yes Neither Yes One or more CA certificates in PEM (BASE64) format.
clientChain String Yes Neither Yes One or more CA certificates in PEM (BASE64) format.

Resource: Custom

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
caUrl String Yes Neither No The URL of the external CA.
caChain String Yes Neither Yes Provide the CA chain for certificates issued by the remote CA. The certificates should be concatenated together in PEM format.
useStaticCredentials Boolean Yes Neither Yes By default, the system will use the user's credentials when interacting with the external CA. However, if this option is selected, the static credentials specified will be used when interacting with the external CA.
staticUserName String Yes Neither Yes The username to use when interacting with the external CA.
staticPassword String Yes Neither Yes The password to use when interacting with the external CA.

Certificate Templates URIs and Actions

The following table indicates the URIs that you can append to the root URI, along with the actions you can take, and possible return codes you can receive.

Certificate Templates URIs and Actions

URI Action Description Return Codes
/certificateTemplates GET Returns the list of certificate templates.

404 - Not found

401 - Unauthorized

200 - Ok
/certificateTemplates/{id} GET Returns details about the specified certificate template.  

Example of Using GET for Certificate Templates

This example demonstrates how to obtain information about all certificate templates.

URI:

This example uses the following URI: 

 https://Jeff245.cloudpath.net/admin/publicApi/certificateTemplates

where https://Jeff245.cloudpath.net/admin/publicApi is the root URI of the Cloudpath system being used (must include https, as shown).

Request Headers:

The following table shows the required request headers for this URI example, with an example value of an active token that must be pasted into the Authorization header value:

Request Headers

Key Value
Content-type application/json
Authorization eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqZWZmLnJob2RpZUBjb21tc2NvcGUuY29tIiwicm9sZVBrIjoiMjEwMDAiLCJhY2NvdW50QWRtaW5QayI6IjIiLCJhcGlLZXkiOiJaV2NjTGpQZUdZMGUiLCJpYXQiOjE1NzU1NzUxNTcsImV4cCI6MTU3NTU3NTQ1N30.2q4KTyDUevkAAz7mJyp529Be1-ip3EC8P06Xarmz5ao

Request Body:

None required.

Action:

Use the GET action to send the request.

Response Body:

Once the request is sent, you will receive a "Status: 200 OK" if the GET is successful. The response body provides information about all existing certificate templates, as shown in the following example display. 

{
    "page": {
        "page": 1,
        "pageSize": 2,
        "totalCount": 2
    },
    "contents": [
        {
            "guid": "1",
            "name": "Server Template",
            "caType": "ONBOARD",
            "detail": {
                "commonNamePattern": "${SERVER_NAME}",
                "validPeriod": {
                    "notBeforeOffset": 1,
                    "notBeforeDate": "2021-02-20T01:12:54.515Z",
                    "notBeforeDateType": "MONTHS_BEFORE_TIME",
                    "notAfterOffset": 3,
                    "notAfterDate": "2021-02-20T01:12:54.515Z",
                    "notAfterDateType": "YEARS_AFTER_TIME",
                    "ocspMonitor": false,
                    "ocspRevokeDays": 30
                },
                "keyLength": 2048,
                "algorithm": "SHA256WITHRSA",
                "organizationPattern": "Sample Company, Inc.",
                "unitPattern": "IT",
                "localityPattern": "Westminster",
                "statePattern": "Colorado",
                "countryPattern": "US",
                "type": "IDENTITY_BASED",
                "ekuHotSpot": false,
                "ekuMsClient": false,
                "ekuMsServer": true,
                "keyUsageList": [
                    "DIGITAL_SIGNATURE",
                    "KEY_ENCIPHERMENT"
                ],
                "advancedPatterns": {
                    "emailPattern": "it@company.com",
                    "sanOtherNamesList": "",
                    "sanRfc822": "",
                    "sanDnsNames": "",
                    "sanUrl": "",
                    "sanIp": "",
                    "sanRid": "",
                    "title": ""
                }
            },
            "allowsRadiusAuth": false,
            "defaultAccess": "ACCEPT",
            "workflowCount": 0,
            "issuedCertificateCount": 1,
            "authorizedEnrollmentsCount": 0,
            "status": "ENABLED",
            "links": [
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/certificateTemplates/1",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "certificates",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/certificateTemplates/1/certificates?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "msiPackages",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/certificateTemplates/1/msiPackages?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "policies",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/certificateTemplates/1/policies",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        },
        {
            "guid": "2",
            "name": "username@byod.company.com",
            "caType": "ONBOARD",
            "detail": {
                "commonNamePattern": "${USERNAME}@byod.company.com",
                "validPeriod": {
                    "notBeforeOffset": 1,
                    "notBeforeDate": "2021-02-20T01:12:54.518Z",
                    "notBeforeDateType": "MONTHS_BEFORE_TIME",
                    "notAfterOffset": 1,
                    "notAfterDate": "2021-02-20T01:12:54.518Z",
                    "notAfterDateType": "YEARS_AFTER_TIME",
                    "ocspMonitor": false,
                    "ocspRevokeDays": 30
                },
                "keyLength": 2048,
                "algorithm": "SHA256WITHRSA",
                "organizationPattern": "Sample Company, Inc.",
                "unitPattern": "IT",
                "localityPattern": "Westminster",
                "statePattern": "Colorado",
                "countryPattern": "US",
                "type": "IDENTITY_BASED",
                "ekuHotSpot": true,
                "ekuMsClient": true,
                "ekuMsServer": false,
                "keyUsageList": [
                    "DIGITAL_SIGNATURE",
                    "KEY_ENCIPHERMENT"
                ],
                "advancedPatterns": {
                    "emailPattern": "",
                    "sanOtherNamesList": "",
                    "sanRfc822": "",
                    "sanDnsNames": "",
                    "sanUrl": "",
                    "sanIp": "",
                    "sanRid": "",
                    "title": ""
                }
            },
            "allowsRadiusAuth": true,
            "defaultAccess": "ACCEPT",
            "workflowCount": 1,
            "issuedCertificateCount": 0,
            "authorizedEnrollmentsCount": 0,
            "status": "ENABLED",
            "links": [
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/certificateTemplates/2",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "certificates",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/certificateTemplates/2/certificates?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "msiPackages",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/certificateTemplates/2/msiPackages?page=1&pageSize=10{&filter,orderBy}",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "policies",
                    "href": "https://jeff245.cloudpath.net/admin/publicApi/certificateTemplates/2/policies",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        }
    ]
}

Parent topic: Certificate Templates and Related Resources