Name

OpenXPKI::Server::Authentication::X509 - certificate based authentication.

Description

Use a certificate chain passed by the authenticator to authenticate the user. This is an abstract base class, the actual challenge and extraction of the chain is done in ChallengeX509 and ClientX509 class, the later validation performs several steps:

* look up a suitable root certificate, either in the received chain or in the database. * do a cryptographic validation on the chain. * check if any of the certificates (entity, chain or root) is contained in the trust anchor list.

Any failure results in an exception.

Functions

_load_anchors

Create a list of trust anchor identifiers by calling get_trust_anchors passing the config node trust_anchor as path argument.

login_step

returns a pair of (user, role, response_message) for a given login step. Noop - needs to be implemented by the inherited classes.

configuration

Signature:
type: ChallengeX509
label: Signature
description: I18N_OPENXPKI_CONFIG_AUTH_HANDLER_DESCRIPTION_SIGNATURE
role: User
user:
John Doe:
username: jdoe
realname: John Doe
arg: cn
# trust anchors (see also get_trust_anchors API method)
trust_anchor:
realm:
- my_client_auth_realm
cacert:
- cert_identifier of external ca cert
alias:
- name of alias groups

    trust_rule:
        rule1:
            profile: tls_client
            meta_auth_attribute: value

parameters

role: The role assigned to the user, if not specified a user section that returns the role is mandatory!
user: Hash holding additional user information, usually implemented as a connector reference, see below.
arg: The certificate property used as username. Supported values are:

subject / dn: The full subject/dn as string, this is also the default
serial: Serial in integer notation - as string
certificate: The PEM encoded certificate
cert_identifier / certid: The cert_identifier.
Note: If you use certificates from an external CA you will not be able to resolve the identifier back to any information unless you import them into the certificate database!
*: Any part that is set in the DN hash, if an attribute is multivalued the first item is used.

trust_anchor: Definition of trust anchors used when validating the certificate, this node is mandatory and must have at least one keywords supported by the get_trust_anchors API method.

Examples

Static

Allow all certiticates issued from the internal realm user-ca and set their role to User. Set CN as username (default).

    type: ClientX509
    role: User
    trust_anchor:
        realm: user-ca

Static role, extended user information from CN

Querys the given connector with the full DN as argument, expects a hash that contains at least the key username, all other keys are made available in the "userinfo" structure (e.g. realname and emailaddress).

    type: ClientX509
    role: User
    user@: connector:my.user.info.source
    arg: subject
    trust_anchor:
        realm: user-ca

Dynamic role

Similar to above but as role is not set in the config the hash returned by the connector must also contain role. As arg is also not set the query parameter given to the connector is only the common name.

    type: ClientX509
    user@: connector:my.user.info.source
    trust_anchor:
        realm: user-ca