Fortinet black logo

Administration Guide

Configuring a PKI user

Configuring a PKI user

PKI users are users who are identified by a digital certificate they hold. Defining a PKI user in FortiOS specifies:

  • Which CA certificate to use to validate the user’s certificate
  • The field and value of the user’s certificate that FortiOS will check to verify a user

These peer users can then be used in a FortiGate user group, or as a peer certificate group used for IPsec VPN configurations that accept RSA certificate authentication.

Example X.509 certificate

The following certificate demonstrates which FortiGate settings can be used to match on different fields.

Subject:

Subject Alternative Name:

Certification path:

To configure a PKI user:
config user peer
    edit <name>
        set ca <string>
        set mandatory-ca-verify {enable | disable}
        set subject <string>
        set cn <string>
        set cn-type {string | email | FQDN | ipv4 | ipv6}
        set ldap-server <string>
        set ldap-username <string>
        set ldap-password <string>
        set ldap-mode {password | principal-name}
    next
end

ca <string>

Specify which certificate on the FortiGate is used to validate the client’s certificate. This can be any CA in the client’s certificate chain. You may need to upload a CA certificate to the FortiGate specifically to identify PKI peer users (see Uploading a certificate using the GUI).

mandatory-ca-verify {enable | disable}

Control the action if the CA certificate used to sign the client’s certificate is not installed on the FortiGate (default = enable). Disabling this setting makes the FortiGate consider any certificate presented by the peer as valid.

In the example certificate, the certification path shows that VF_CA signed jcarrey’s certificate.

subject <string>

Enter the peer certificate name constraints.

cn <string>

Enter the peer certificate common name.

cn-type {string | email | FQDN | ipv4 | ipv6}

Set the peer certificate common name type: string, email, FQDN, IPv4 address, or IPv6 address. See CN for more details.

ldap-server <string>

Enter the name of an LDAP server defined under config user ldap for performing client access rights checks. See LDAP Servers for more details.

ldap-mode {password | principal-name}

Set the mode for LDAP peer authentication, either by password or principal name (default = password). See LDAP for more details.

ldap-username <string>

Enter the username for the LDAP server bind when the LDAP mode is password.

ldap-password <string>

Enter the password for the LDAP server bind when the LDAP mode is password.

Identifying users based on their client certificate

When the client’s certificate is valid, or mandatory-ca-verify is disabled, the FortiGate can then inspect the certificate to check specific fields for matching values. There are three ways of specifying which certificate field to verify: by subject, CN, or LDAP. All string comparisons are case sensitive.

Subject

This basic method verifies that the subject string defined in the PKI user setting matches a value or substring in the subject field of the user certificate. Further matching is controlled in the following VPN certificate settings.

config vpn certificate setting
    set subject-match {substring | value}
    set subject-set {superset | subset}
    set cn-match {substring | value}
    set cn-allow-multi {enable | disable}
end

subject-match {substring | value}

Control how to do relative distinguished name (RDN) value matching with the certificate subject name:

  • substring: find a match if any string in the certificate subject name matches the name being searched for (such as set subject jcarrey).
  • value: find a match if any attribute value string in a certificate subject name is an exact match with the name being searched for (such as set subject "OU=TAC" or set subject "C=CA, CN=jcarrey, OU=TAC").

set subject-set {superset | subset}

Control how to do RDN value matching with the certificate subject name:

  • superset: a certificate only passes verification if it contains all the RDNs defined in the subject settings (such as set subject "E = jcarrey@fortinet.com, CN = jcarrey, OU = TAC, O = Fortinet, L = Burnaby, S = British Columbia, C = CA").
  • subset: a certificate passes verification if the RDN is a subset of the certificate subject (such as set subject "CN = jcarrey, OU = TAC").

cn-match {substring | value}

Control how to do CN value matching with the certificate subject name:

  • substring: find a match if any string in the certificate subject name matches the name being searched for.
  • value: find a match if any attribute value string in a certificate subject name is an exact match with the name being searched for.

cn-allow-multi {enable | disable}

Enable/disable allowing multiple CN entries with the certificate subject name (default = enable).

CN

Common name (CN) certificate verification compares the CN in the subject field with the configured string (such as set cn "jcarrey". The following logic is used when configuring different CN types:

Type

Action

string

Based on the cn-match setting, perform a substring or exact match in the certificate subject.

email

Look for a match in the certificate subject.

FQDN

Look for a match in the certificate subject, then compare the mapped IP and client IP. The FQDN is only retrieved from the CN.

ipv4

Look for a match in the certificate subject, then compare the IP.

ipv6

Look for a match in the certificate subject, then compare the IP.

The CN type also controls the format checking of the CN string. In this example, if the CN type is set to email, the CN must be in email format (set cn "jcarrey@fortinet.com").

LDAP

LDAP-integrated user authentication allows the FortiGate to check the connecting user against an LDAP server in two ways: through a username and password, or the certificate’s principal name. The password method requires the username and password of each authenticating user to be entered, so it is not recommended when configuring PKI users. The principal-name method is recommended.

The UPN in the user certificate’s Subject Alternative Name field is used to look up the user in the LDAP directory. If a match is found, then authentication succeeds. This type of configuration scales well since only one PKI user needs to be created on the FortiGate. Connecting clients use their unique user certificate to match within the configured LDAP server.

Configuring a PKI user

PKI users are users who are identified by a digital certificate they hold. Defining a PKI user in FortiOS specifies:

  • Which CA certificate to use to validate the user’s certificate
  • The field and value of the user’s certificate that FortiOS will check to verify a user

These peer users can then be used in a FortiGate user group, or as a peer certificate group used for IPsec VPN configurations that accept RSA certificate authentication.

Example X.509 certificate

The following certificate demonstrates which FortiGate settings can be used to match on different fields.

Subject:

Subject Alternative Name:

Certification path:

To configure a PKI user:
config user peer
    edit <name>
        set ca <string>
        set mandatory-ca-verify {enable | disable}
        set subject <string>
        set cn <string>
        set cn-type {string | email | FQDN | ipv4 | ipv6}
        set ldap-server <string>
        set ldap-username <string>
        set ldap-password <string>
        set ldap-mode {password | principal-name}
    next
end

ca <string>

Specify which certificate on the FortiGate is used to validate the client’s certificate. This can be any CA in the client’s certificate chain. You may need to upload a CA certificate to the FortiGate specifically to identify PKI peer users (see Uploading a certificate using the GUI).

mandatory-ca-verify {enable | disable}

Control the action if the CA certificate used to sign the client’s certificate is not installed on the FortiGate (default = enable). Disabling this setting makes the FortiGate consider any certificate presented by the peer as valid.

In the example certificate, the certification path shows that VF_CA signed jcarrey’s certificate.

subject <string>

Enter the peer certificate name constraints.

cn <string>

Enter the peer certificate common name.

cn-type {string | email | FQDN | ipv4 | ipv6}

Set the peer certificate common name type: string, email, FQDN, IPv4 address, or IPv6 address. See CN for more details.

ldap-server <string>

Enter the name of an LDAP server defined under config user ldap for performing client access rights checks. See LDAP Servers for more details.

ldap-mode {password | principal-name}

Set the mode for LDAP peer authentication, either by password or principal name (default = password). See LDAP for more details.

ldap-username <string>

Enter the username for the LDAP server bind when the LDAP mode is password.

ldap-password <string>

Enter the password for the LDAP server bind when the LDAP mode is password.

Identifying users based on their client certificate

When the client’s certificate is valid, or mandatory-ca-verify is disabled, the FortiGate can then inspect the certificate to check specific fields for matching values. There are three ways of specifying which certificate field to verify: by subject, CN, or LDAP. All string comparisons are case sensitive.

Subject

This basic method verifies that the subject string defined in the PKI user setting matches a value or substring in the subject field of the user certificate. Further matching is controlled in the following VPN certificate settings.

config vpn certificate setting
    set subject-match {substring | value}
    set subject-set {superset | subset}
    set cn-match {substring | value}
    set cn-allow-multi {enable | disable}
end

subject-match {substring | value}

Control how to do relative distinguished name (RDN) value matching with the certificate subject name:

  • substring: find a match if any string in the certificate subject name matches the name being searched for (such as set subject jcarrey).
  • value: find a match if any attribute value string in a certificate subject name is an exact match with the name being searched for (such as set subject "OU=TAC" or set subject "C=CA, CN=jcarrey, OU=TAC").

set subject-set {superset | subset}

Control how to do RDN value matching with the certificate subject name:

  • superset: a certificate only passes verification if it contains all the RDNs defined in the subject settings (such as set subject "E = jcarrey@fortinet.com, CN = jcarrey, OU = TAC, O = Fortinet, L = Burnaby, S = British Columbia, C = CA").
  • subset: a certificate passes verification if the RDN is a subset of the certificate subject (such as set subject "CN = jcarrey, OU = TAC").

cn-match {substring | value}

Control how to do CN value matching with the certificate subject name:

  • substring: find a match if any string in the certificate subject name matches the name being searched for.
  • value: find a match if any attribute value string in a certificate subject name is an exact match with the name being searched for.

cn-allow-multi {enable | disable}

Enable/disable allowing multiple CN entries with the certificate subject name (default = enable).

CN

Common name (CN) certificate verification compares the CN in the subject field with the configured string (such as set cn "jcarrey". The following logic is used when configuring different CN types:

Type

Action

string

Based on the cn-match setting, perform a substring or exact match in the certificate subject.

email

Look for a match in the certificate subject.

FQDN

Look for a match in the certificate subject, then compare the mapped IP and client IP. The FQDN is only retrieved from the CN.

ipv4

Look for a match in the certificate subject, then compare the IP.

ipv6

Look for a match in the certificate subject, then compare the IP.

The CN type also controls the format checking of the CN string. In this example, if the CN type is set to email, the CN must be in email format (set cn "jcarrey@fortinet.com").

LDAP

LDAP-integrated user authentication allows the FortiGate to check the connecting user against an LDAP server in two ways: through a username and password, or the certificate’s principal name. The password method requires the username and password of each authenticating user to be entered, so it is not recommended when configuring PKI users. The principal-name method is recommended.

The UPN in the user certificate’s Subject Alternative Name field is used to look up the user in the LDAP directory. If a match is found, then authentication succeeds. This type of configuration scales well since only one PKI user needs to be created on the FortiGate. Connecting clients use their unique user certificate to match within the configured LDAP server.