Certificate Authenticator
Warning 1: This authenticator assumes that some external process can guarantee that the certificate belongs to the authenticating entity. This is typically done by challenging the entity to sign something with the corresponding private key. This is, for example, the case in an SSL handshake involving client certificate verification.
Warning 2: This authenticator does not check whether the certificate was signed by a trusted entity. This must be done prior to calling this authenticator, typically during an SSL handshake.
The credentials passed to this authenticator must be of type
If the credential contains a username (subtype of
If the credential contains a username but no certificate (type CERTIFICATE_REQUIRED. This makes it suitable for usage with the
What checks are done on the certificate and how the user name and granted roles (and possibly other data) are determined is specified by the configuration.
There are two different (and mutual exclusive) ways how this plugin determines the username given the client certificate:
(1) Extract username from client certificate. In this case the username potentially passed as credential is ignored. Look at configuration property user-attribute for this case.
(2) Take user name from the credential. In this case, the credential must contain a username.
Independent of the way the username has been determined, a credential persister can be used to verify that the client certificate really belongs to the username. See property credential-persister for details. If the client certificate does not match the data stored under the determined username, the authentication response AuthenticationFailedCertificate.CERTIFICATE_DOES_NOT_MATCH_USER is returned.
The plugin writes the canonical class name description of this plugin to the context data container. The class name is stored under the key authPluginClassName . A short description of this authentication method is stored under the key authMethodShortDesc . This information may be used by callers.
userAttribute) If a credential persister is configured (see below), the extracted user name is used to look up the credential bean. The bean can be used for further checks.
Note: This can be used to find a user mapped to the certificate (e.g. the CN of the certificate is stored with the username in the persistence layer). To do so, configure the credential persister accordingly to look up the credential data given the value defined by this property(which does not necessarily have to be the real username). Then use the credential-bean-username property below to read the real username from the credential bean.
Note: This property has precedence over the username in the credential object. Thus, if this property is defined, any user information passed as credential is ignored.
Usually the username is part of the DN (distinguished name) of the certified subject.
This attribute specifies the attribute name of the username in the DN. Example: The value "cn" will extract the common name from the DN and use this as username.
The following values are treated especially:
- "dn": use this value to use the whole distinguished name as username.
- "altSubjectName": use this value to use the alternative subject name as username.
If this property is not defined, the plugin takes the username from the credential.
Look at property credential-persister to see how to validate that the user is registered with for this client certificate.
stripDomainFromUsername) This property is ignored if the configuration property "user-attribute" is not defined or set to "dn".
credentialPersister) If this property is defined, the plugin is used to look up a credential bean using the determined username (or other id determined by this plugin). Then a check is performed whether the certificate really belongs to the user. The check is defined by the separate configuration property "matchPolicy".
How this plugin reacts if no credential record can be found is specified by the separate property "treat-no-credential-data-as-not-assigned".
usernameTransformers) Username transformers may transform the name a user states in the login-form into the single unique user-id required for the authentication process.
The transformation of a username takes place after extracting the user name from the presented certificate and before the authenticator reads the user from persistency layer. If a username is supplied from a previous authentication step, then no transformation is done here.
Transfomers can be chained, i.e. a first transformer could normalize the original name, where the next transformer looks-up the normalized name in a database for eventual transformation matches.
A transformer can also signal that it already found the final user-id and the chain must stop after him.
doNotUpdateUserStatistics) This property is only relevant if a user persister is configured.
matchPolicy) This check is only done if a credential bean has been loaded using the configured credential persister.
The credential data of the credential bean is compared to the certificate depending on the value of this property:
- "DNs" : The distinguished names (DN) of the certificate subject and the issuer is compared to the string data of the credential bean. The comparison is case-insensitive. The DNs are encoded in the following form for comparison: <issuer-dn>ISSUER-DN</issuer-dn><subject-dn>SUBJECT-DN</subject-dn>
This is the default value. - "subject-DN" : The DN of the certificate subject is compared to the string data of the credential bean. The comparison is case-insensitive. This setting can be combined with the setting "issuer-dn-property"
- "CN" : The common name (CN) of the certificate subject is compared to the string data of the credential bean. The comparison is case-insensitive. This setting can be combined with the setting "issuer-dn-property"
- "TBS" : The TBS (to-be-signed) part of the certificate is compared to the string or binary data of the credential bean. If the credential data is binary, the comparison is done byte-wise, if it is a string type credential, the TBS-part is base64-encoded before comparing.
- "certificate" : The X509 certificate is compared to the string or binary data of the credential bean. If the credential data is binary, the comparison is done byte-wise, if it is a string type credential, the certificate is base64-encoded before comparing.
- "NONE" : No check is performed.
Note: For backwards-compatibility, the default value of this property is "DNs"!
If a credential record can be found but it contains no credential data, this plugin responds with CREDENTIAL_NOT_ASSIGNED (can for example start a registration process), if credential data can be found but does not match in this check, CERTIFICATE_DOES_NOT_MATCH_USER. How the plugin behaves if no credential record can be found at all is defined property "treat-no-credential-data-as-not-assigned".
issuerDnProperty) This setting is only used in conjunction with match policies "CN" and "subject-DN" and requires that a credential persister is configured: In addition to matching the cn or subject dn the issuer DN is also compared to the value stored in the context property (of the credential context container) referenced by this setting.
The comparison is case-insensitive.
multiFormatDnComparison) - a=A,b=B,c=C
- c=C,b=B,a=A (backwards)
- /a=A/b=B/c=C (slash notation)
- /c=C/b=B/a=A (slash notation backwards)
- a=A,b=B,x.y.z=C (where x.y.z is the OID for attribute c)
This affects match policy "subject-DN" and it affects issuer DN comparison if the property "issuer-dn-property" is defined.
userProperty) This property is used in situations where the username cannot be extracted directly from the certificate but it is determined by looking up a credential bean and reading the username from it. If the referenced context data property cannot be found, an AuthenticatorException is thrown.
If this property is defined, it usually makes sense to also set the property "treat-no-credential-data-as-not-assigned" to true.
treatNoCredDataAsNotAssigned) CREDENTIAL_NOT_ASSIGNED if no credential bean can be found at all. If it is "FALSE" (which is the default), this plugin responds with USER_NOT_FOUND.
This property exists to make this plugin suitable for situations where the username cannot be extracted directly from the certificate but it is determined by looking up a credential bean and reading the username from it. In this case not finding a credential bean at all usually means that the certificate has not yet been assigned. In the other case - i.e. the username is directly read from the certificate - not finding the credential bean usually means that the user does no more exist.
staticRoles) certificateStatusChecker) Note: If this optional property is not defined or empty (and no certificate status checker plugins are configured by the property "Cert Status Checkers"), no status check is performed (i.e. all certificates are considered to be non-revoked).
userPersister) - User is not found
- Username is ambiguous
- User is locked
- User is not valid
maxFailedLogins) expiringCertificateWarningDays) additionalUserValidators) checkValidityPeriod) certStatusCheckers)
type: CertificateAuthenticator
id: CertificateAuthenticator-xxxxxx
displayName:
comment:
properties:
additionalUserValidators:
certStatusCheckers:
certificateStatusChecker:
checkValidityPeriod: true
credentialPersister:
doNotUpdateUserStatistics: false
expiringCertificateWarningDays:
issuerDnProperty:
matchPolicy: DNs
maxFailedLogins: 0
multiFormatDnComparison: false
staticRoles:
stripDomainFromUsername: false
treatNoCredDataAsNotAssigned: false
userAttribute:
userPersister:
userProperty:
usernameTransformers: