Fortinet black logo

CLI Reference

user pki

user pki

Use this command to configure public key infrastructure (PKI) users.

A PKI user can be either an email user or a FortiMail administrator. PKI users can authenticate by presenting a valid client certificate, rather than by entering a user name and password.

When the PKI user connects to the FortiMail unit with his or her web browser, the web browser presents the PKI user’s certificate to the FortiMail unit. If the certificate is valid, the FortiMail unit then authenticates the PKI user. To be valid, a client certificate must:

  • Not be expired
  • Not be revoked by either certificate revocation list (CRL) or, if enabled, online certificate status protocol (OCSP)
  • Be signed by a certificate authority (CA), whose certificate you have imported into the FortiMail unit
  • Contain a “ca" field whose value matches the CA certificate
  • Contain a “issuer" field whose value matches the “subject" field in the CA certificate
  • Contain a “subject" field whose value contains the subject, or is empty
  • If ldap-query is enable, contain a common name (CN) or Subject Alternative field whose value matches the email address of a user object retrieved using the user query of the LDAP profile

If the client certificate is not valid, depending on whether you have configured the FortiMail unit to require valid certificates (see certificate-required {yes | no} in config policy recipient for email users, and pki-certificate-req {yes | no} in system geoip-override for FortiMail administrators), authentication will either fail absolutely, or fail over to a user name and password mode of authentication.

If the certificate is valid and authentication succeeds, the PKI user’s web browser is redirected to either the web-based manager (for PKI users that are FortiMail administrators) or the mailbox folder that contains quarantined spam (for PKI users that are email users).

After using this command to configure a PKI user, you must also configure the following aspects of the FortiMail unit and the PKI user’s computer:

  • Import each PKI user’s client certificate into the web browser of each computer from which the PKI user will access the FortiMail unit. For details on installing certificates, see the documentation for your web browser.

Control access to each PKI user’s computer. Certificate-based PKI authentication controls access to the FortiMail unit based upon PKI certificates, which are installed on each email user or administrator’s computer. If anyone can access the computers where those PKI certificates are installed, they can gain access to the FortiMail unit, which can compromise the security of your FortiMail unit.

  • Import the CA certificate into the FortiMail unit. For information on uploading a CA certificate, see the FortiMail Administration Guide. For more information, see “CA certificate".
  • For PKI users that are FortiMail administrators, select the PKI authentication type and select a PKI user to which the administrator account corresponds. For more information, see system admin.
  • For PKI users that are email users, enable PKI user authentication for the recipient-based policies which match those email users.

This command takes effect only if PKI authentication is enabled by pki-mode {enable | disable} in the command system geoip-override.

Syntax

config user pki

edit name <name_str>

set ca <certificate_str>

set domain <protected-domain_str>

set ldap-field {cn | subjectalternative}

set ldap-profile <profile_str>

set ldap-query {enable | disable}

set ocsp-ca <remote-certificate_str>

set ocsp-check {enable | disable}

set ocsp-unavailable-action {revoke | ignore}

set ocsp-url <url_str>

set subject <subject_str>

end

Variable

Description

Default

name <name_str>

Enter the name of the PKI user.

ca <certificate_str>

Enter the name of the CA certificate used when verifying the CA’s signature of the client certificate. For information on uploading a CA certificate, see the FortiMail Administration Guide.For more information, see “CA certificate".

If you configure an empty string for this variable, you must configure subject <subject_str>.

domain <protected-domain_str>

Enter the name of the protected domain to which the PKI user is assigned, or enter system if the PKI user is a FortiMail administrator and belongs to all domains configured on the FortiMail unit. For more information on protected domains, see dlp scan-rules.

ldap-field {cn | subjectalternative}

Enter the name of the field in the client certificate (either CN or Subject Alternative) which contains the email address of the PKI user, either subjectalternative (if the field is a Subject Alternative) or cn (if the field is a common name).

This email address will be compared with the value of the email address attribute for each user object queried from the LDAP directory to determine if the PKI user exists in the LDAP directory.

This variable is used only if ldap-query is enable.

subject

ldap-profile <profile_str>

Enter the LDAP profile to use when querying the LDAP server for the PKI user’s existence. For more information on LDAP profiles, see profile ldap.

This variable is used only if ldap-query is enable.

ldap-query {enable | disable}

Enable to query an LDAP directory, such as Microsoft Active Directory, to determine the existence of the PKI user who is attempting to authenticate. Also configure ldap-profile <profile_str> and ldap-field {cn | subjectalternative}.

disable

ocsp-ca <remote-certificate_str>

Enter the name of the remote certificate that is used to verify the identity of the OCSP server. For information on uploading a remote (OCSP) certificate, see the FortiMail Administration Guide. For more information, see “Remote".

This option applies only if oscpverify is enable.

ocsp-check {enable | disable}

Enable to use an Online Certificate Status Protocol (OCSP) server to query whether the client certificate has been revoked. Also configure ocsp-url <url_str>, [ocsp-ca <remote-certificate_str>, and ocsp-unavailable-action {revoke | ignore}.

disable

ocsp-unavailable-action {revoke | ignore}

Enter the action to take if the OCSP server is unavailable. If set to ignore, the FortiMail unit allows the user to authenticate. If set to revoke, the FortiMail unit behaves as if the certificate is currently revoked, and authentication fails.

This option applies only if oscp-check is enable.

ignore

ocsp-url <url_str>

Enter the URL of the OCSP server.

This option applies only if oscp-check is enable.

subject <subject_str>

Enter the value which must match the “subject" field of the client certificate. If empty, matching values are not considered when validating the client certificate presented by the PKI user’s web browser.

The FortiMail unit will use a CA certificate to authenticate a PKI user only if the subject string you enter here also appears in the CA certificate subject. If no subject is entered here, the subject not considered when the FortiMail unit selects the certificate to use.

To disable Subject verification, enter an empty string surrounded by single quotes ( '' ).

If you configure an empty string for this variable, you must configure ca <certificate_str>.

Related topics

system wccp settings

user map

user pki

Use this command to configure public key infrastructure (PKI) users.

A PKI user can be either an email user or a FortiMail administrator. PKI users can authenticate by presenting a valid client certificate, rather than by entering a user name and password.

When the PKI user connects to the FortiMail unit with his or her web browser, the web browser presents the PKI user’s certificate to the FortiMail unit. If the certificate is valid, the FortiMail unit then authenticates the PKI user. To be valid, a client certificate must:

  • Not be expired
  • Not be revoked by either certificate revocation list (CRL) or, if enabled, online certificate status protocol (OCSP)
  • Be signed by a certificate authority (CA), whose certificate you have imported into the FortiMail unit
  • Contain a “ca" field whose value matches the CA certificate
  • Contain a “issuer" field whose value matches the “subject" field in the CA certificate
  • Contain a “subject" field whose value contains the subject, or is empty
  • If ldap-query is enable, contain a common name (CN) or Subject Alternative field whose value matches the email address of a user object retrieved using the user query of the LDAP profile

If the client certificate is not valid, depending on whether you have configured the FortiMail unit to require valid certificates (see certificate-required {yes | no} in config policy recipient for email users, and pki-certificate-req {yes | no} in system geoip-override for FortiMail administrators), authentication will either fail absolutely, or fail over to a user name and password mode of authentication.

If the certificate is valid and authentication succeeds, the PKI user’s web browser is redirected to either the web-based manager (for PKI users that are FortiMail administrators) or the mailbox folder that contains quarantined spam (for PKI users that are email users).

After using this command to configure a PKI user, you must also configure the following aspects of the FortiMail unit and the PKI user’s computer:

  • Import each PKI user’s client certificate into the web browser of each computer from which the PKI user will access the FortiMail unit. For details on installing certificates, see the documentation for your web browser.

Control access to each PKI user’s computer. Certificate-based PKI authentication controls access to the FortiMail unit based upon PKI certificates, which are installed on each email user or administrator’s computer. If anyone can access the computers where those PKI certificates are installed, they can gain access to the FortiMail unit, which can compromise the security of your FortiMail unit.

  • Import the CA certificate into the FortiMail unit. For information on uploading a CA certificate, see the FortiMail Administration Guide. For more information, see “CA certificate".
  • For PKI users that are FortiMail administrators, select the PKI authentication type and select a PKI user to which the administrator account corresponds. For more information, see system admin.
  • For PKI users that are email users, enable PKI user authentication for the recipient-based policies which match those email users.

This command takes effect only if PKI authentication is enabled by pki-mode {enable | disable} in the command system geoip-override.

Syntax

config user pki

edit name <name_str>

set ca <certificate_str>

set domain <protected-domain_str>

set ldap-field {cn | subjectalternative}

set ldap-profile <profile_str>

set ldap-query {enable | disable}

set ocsp-ca <remote-certificate_str>

set ocsp-check {enable | disable}

set ocsp-unavailable-action {revoke | ignore}

set ocsp-url <url_str>

set subject <subject_str>

end

Variable

Description

Default

name <name_str>

Enter the name of the PKI user.

ca <certificate_str>

Enter the name of the CA certificate used when verifying the CA’s signature of the client certificate. For information on uploading a CA certificate, see the FortiMail Administration Guide.For more information, see “CA certificate".

If you configure an empty string for this variable, you must configure subject <subject_str>.

domain <protected-domain_str>

Enter the name of the protected domain to which the PKI user is assigned, or enter system if the PKI user is a FortiMail administrator and belongs to all domains configured on the FortiMail unit. For more information on protected domains, see dlp scan-rules.

ldap-field {cn | subjectalternative}

Enter the name of the field in the client certificate (either CN or Subject Alternative) which contains the email address of the PKI user, either subjectalternative (if the field is a Subject Alternative) or cn (if the field is a common name).

This email address will be compared with the value of the email address attribute for each user object queried from the LDAP directory to determine if the PKI user exists in the LDAP directory.

This variable is used only if ldap-query is enable.

subject

ldap-profile <profile_str>

Enter the LDAP profile to use when querying the LDAP server for the PKI user’s existence. For more information on LDAP profiles, see profile ldap.

This variable is used only if ldap-query is enable.

ldap-query {enable | disable}

Enable to query an LDAP directory, such as Microsoft Active Directory, to determine the existence of the PKI user who is attempting to authenticate. Also configure ldap-profile <profile_str> and ldap-field {cn | subjectalternative}.

disable

ocsp-ca <remote-certificate_str>

Enter the name of the remote certificate that is used to verify the identity of the OCSP server. For information on uploading a remote (OCSP) certificate, see the FortiMail Administration Guide. For more information, see “Remote".

This option applies only if oscpverify is enable.

ocsp-check {enable | disable}

Enable to use an Online Certificate Status Protocol (OCSP) server to query whether the client certificate has been revoked. Also configure ocsp-url <url_str>, [ocsp-ca <remote-certificate_str>, and ocsp-unavailable-action {revoke | ignore}.

disable

ocsp-unavailable-action {revoke | ignore}

Enter the action to take if the OCSP server is unavailable. If set to ignore, the FortiMail unit allows the user to authenticate. If set to revoke, the FortiMail unit behaves as if the certificate is currently revoked, and authentication fails.

This option applies only if oscp-check is enable.

ignore

ocsp-url <url_str>

Enter the URL of the OCSP server.

This option applies only if oscp-check is enable.

subject <subject_str>

Enter the value which must match the “subject" field of the client certificate. If empty, matching values are not considered when validating the client certificate presented by the PKI user’s web browser.

The FortiMail unit will use a CA certificate to authenticate a PKI user only if the subject string you enter here also appears in the CA certificate subject. If no subject is entered here, the subject not considered when the FortiMail unit selects the certificate to use.

To disable Subject verification, enter an empty string surrounded by single quotes ( '' ).

If you configure an empty string for this variable, you must configure ca <certificate_str>.

Related topics

system wccp settings

user map