API-Proxy Ephemeral-Certificate Authentication
Ephemeral Certificate Target Authentication
PrivX users can be authenticated and authorized to API targets using ephemeral certificates.
Prerequisites for using ephemeral certificate authentication:
- In order to have an unique CA for issuing access certificates, we recommend creating a new access group. This allows greater granularity in providing and revoking access. For simple cases you may use Default or another existing access group.
- API targets are configured to trust the CA of the chosen access group.
- PrivX and target-system clocks are synchronized.
To configure an API target to use ephemeral certificate authentication:
- Under Administration→API Targets, Edit the desired API target.
- Associate the API target to the correct Access Group.
- For authentication Type, select Ephemeral Certificate.
- Define the patterns for certificate subject name and subject alternative names. Also select the certificate template to use. Patterns and templates are detailed in later sections of this guide.
- Save your changes to the API target.
When using ephemeral-certificate authentication to targets, the target effectively delegates authorization to PrivX.
Ephemeral Certificate Subject Name
The ephemeral certificate subject name is used as a pattern for the certificate's subject name field. The format of the pattern is a list of type=value pairs separated by / and using \ as the escape character. The following types are supported:
| Type | OID | Node Name |
|---|---|---|
| CN | 2.5.4.3 | commonName |
| SN | 2.5.4.4 | surname |
| serialNumber | 2.5.4.5 | serialNumber |
| C | 2.5.4.6 | countryName |
| L | 2.5.4.7 | localityName |
| ST | 2.5.4.8 | stateOrProvinceName |
| streetAddress | 2.5.4.9 | streetAddress |
| O | 2.5.4.10 | organization |
| OU | 2.5.4.10 | organizationName |
| title | 2.5.4.12 | title |
| postalCode | 2.5.4.17 | postalCode |
| GN | 2.5.4.42 | givenName |
| initials | 2.5.4.43 | initials |
| generationQualifier | 2.5.4.44 | generationQualifier |
| dnQualifier | 2.5.4.46 | dnQualifier |
| pseudonym | 2.5.4.65 | pseudonym |
| DC | 0.9.2342.19200300.100.1.25 | domainComponent |
| emailAddress | 1.2.840.113549.1.9.1 | emailAddress |
| userid | 0.9.2342.19200300.100.1.1 | userid |
Additionally, you may use any OID in dotted format as a type. For example 1.2.3.4=foo.
The value can be a static textual value, or it can refer to user attributes with the %attribute% syntax. The following user attibutes are supported:
- principal, aliases username and userprincipalname
- samaccountname
- unix_account
- windows_account
- name, alias full_name
- first_name
- last_name
- distinguishedname
- telephone
- company
- department
- job_title
- source
- external_id
- any custom attribute associated to the PrivX user
Example subject name patterns:
CN=rootCN=%unix_account%/O=Developers/OU=Team A
Ephemeral-certificate authentication won't work when the subject pattern refers to invalid attributes.
Ephemeral Certificate Subject Alternative Name
Similar to subject name pattern, the ephemeral certificate SAN pattern is used for the certificate's SAN field. The format of the pattern is a list of type=value pairs separated by /. You can use \ as the escape character. The following types are supported:
| Type | Notes |
|---|---|
| IP | IPv4 or IPv6 address in dotted notation |
| DNS | |
| URI | |
| UPN | User Principal Name |
| SID | Windows SID in string format (technically a x.509 extension, not a SAN) |
Additionally, you may specify any X.509-SAN othername as othername:{oid};{format}={value}: - OID is given in dotted notation. - Format is one of UTF8String, IA5String or OctetString - Value depends on the format; for UTF8String and IA5String value is provided as a string, for OctetString as hexadecimal string.
Similar to subject name patterns, the ephemeral-certificate SAN pattern supports referring to user attributes with the %attribute% syntax.
Example SAN patterns:
IP=192.168.100.33/DNS=private.privx.ioUPN=%principal%SID=S-1-5-21-3623811015-3361044348-30300820-1013othername:1.3.6.1.5.5.7.8.7;IA5String=_sip._tcp.example.com
Certificate Template
You can create and use certificate templates to configure the key usage and extended key usage of the generated certificates. You can manage certificate templates on Administration→Settings→Authorizer under Certificate Templates.
The supported values in the certificate template's key usage are:
- DigitalSignature
- ContentCommitment
- KeyEncipherment
- DataEncipherment
- KeyAgreement
- CertSign
- CRLSign
- EncipherOnly
- DecipherOnly
The supported values in the certificate template's extended key usage are:
- Any
- ServerAuth
- ClientAuth
- CodeSigning
- EmailProtection
- IPSECEndSystem
- IPSECTunnel
- IPSECUser
- TimeStamping
- OCSPSigning
- MicrosoftServerGatedCrypto
- NetscapeServerGatedCrypto
- MicrosoftCommercialCodeSigning
- MicrosoftKernelCodeSigning
- any OID in dotted format