Skip to main content
Version: 7.2405.x.x LTS

Dynamic X.509 certificate generation AuthState

Introduction and overview

X.509 certificates can be generated dynamically based on input from the authentication process. It is a very powerful integration feature for personalized authentication between our caller (proxy) and an SSL-enabled server in the back end, using the SSL connection's client certificate to identify the calling user.

Dynamic certificate generation has been enabled by implementing the AuthState DynCert and a number of certificate generators. The profile property of the AuthState defines which certificate generator the AuthState will use.

Description

The following table and chapters describe the characteristics of the AuthState.

TopicDescription
Classch.nevis.esauth.auth.states.dyncert.DynCert
LoggingDynCert, DynCertSlave
Auditingnone
Markernone
Methodsauthenticate, stepup, unlock

Properties

  • profile (string {basic,extended,microsoft,<class>}, basic)

    X.509 certificate generation profile. The profile specifies which fields in the certificate should be populated to be compatible with the application server used. Available profiles are:

    • basic (default)

      Generates simple X509 certificates without special extensions.

    • extended

      Generates X509 certificates with the following X509 extensions, required, e.g., for Microsoft SharePoint or IIS integration:

      • AuthorityKeyIdentifier
      • SubjectKeyIdentifier
      • KeyUsage
      • SubjectAltName (containing UPN, i.e., universal principal name)
      • ExtendedKeyUsage
    • microsoft

      Alias for "extended".

    • <class>

      The name of a java class that implements the ch.nevis.esauth.util.dyncert.DynCertGenerator interface.

  • keyLength (number [bit], 1024)

    Size of the RSA key to be generated.

  • preComputeKeys (number, 0)

    Maximum number of key-pairs that should be generated in the background (for performance optimization).

    info

    Since key pair generation is an expensive operation, we recommend enabling the background pre-computation feature with a sufficient queue size. The property preComputeKeys should reflect the number of concurrent user logins, asking for a dynamic certificate.

Generic Profile

  • dyncert.subject (string, -)

    X.509 principal to be identified by the certificate.

    info

    No standardized string representation for DNs exists. The DynCert AuthState supports Java notation (that is, most significant component first, e.g., "CN=user1,OU=my organization,O=my company,C=CH") or OpenSSL notation (starting with a slash, e.g., "/C=CH/O=my company/OU=my organization/CN=user1"). If OpenSSL notation is used, the DN will be reversed.

  • dyncert.validityPeriod (number [minutes], 1440)

    Validity period of the generated X.509 certificate (the validTo field is set to "now+dyncert.validityPeriod").

  • dyncert.dateback (number [min], 1)

    Amount of time in minutes that the certificate should be pre-dated to compensate for clock drift. Some application servers do not accept certificates, issued in the future. By default, certificates are pre-dated by one minute to allow for some slack.

  • dyncert.sigalg (JCE Cryptography Alogrithm Name, "SHA256withRSA")

    The signature algorithm to be used. Only RSA algorithms are supported:

    • SHA1withRSA
    • SHA224withRSA
    • SHA256withRSA
    • SHA384withRSA
    • SHA512withRSA

Basic Profile

  • dyncert.subjectAltName (string, -)

    Sets a Subject Alternative Name in the issued certificate. The value can be of the form email:<name> or otherName:<ObjectIdentifier(RFC3061)>:<name>. For example: otherName:1.3.18.0.2.4.501:dummyUserName.

Microsoft Profile

  • dyncert.upn (string, -)

    This will set the SubjectAlternativeName field. In scenarios of integration with Microsoft products, this field usually has to be filled with the User Principal Name (UPN) of the respective user in Active Directory.

  • dyncert.crlDistributionPoint (string, -)

    Configures a CRL distribution URL in the generated certificate.

  • dyncert.authorityInfoAccess (string, -)

    Configures an Authority Info Access URI in the generated certificate.

Input

none (except a required role in the input message, when "stepup" is used)

Transitions

default (a transition to the next state is expected)

Output

  • dyncert.cert

    PEM encoded X509 certificate

  • dyncert.key

    PEM encoded RSA private key

Errors

none

Notes

none

Example

Microsoft
<AuthState name="DynCert" class="ch.nevis.esauth.auth.states.dyncert.DynCert">
<ResultCond name="default" next="AuthDone"/>
<Response value="AUTH_DONE">
<Gui name="AuthDoneDialog"/>
</Response> <!-- keystore reference for CA signer certificate -->
<property name="keystoreref" value="DefaultKeyStore"/>
<property name="keyobjectref" value="DynCertSigner"/>
<property name="profile" value="microsoft"/>
<property name="keyLength" value="1024"/>
<property name="preComputeKeys" value="100"/>
<property name="dyncert.subject" value="CN=${request:userId},O=SIVEN,C=CH"/>
<property name="dyncert.validityPeriod" value="600"/>
<property name="dyncert.upn" value="${request:userId}"/>
<property name="dyncert.sigalg" value="SHA1withRSA"/>
<property name="dyncert.dateback" value="5"/>
</AuthState>