A new security feature that we have been working on is enhancing the way an X.509 certificate chain gets mapped to an underlying identity. This feature will be included in WildFly 18. This blog post gives an overview of this new feature.

X.509 certificate chain evidence

For certificate-based authentication, the client presents its X.509 certificate chain to the server. The server then verifies this certificate chain. Elytron’s security realm APIs support using this type of X.509 certificate chain evidence to locate and load an identity. For example, after verifying a certificate chain, a server may need to check if the corresponding identity is authorized to access a particular resource. This would involve interacting with the security realm to locate and load an identity based on the X.509 certificate chain in order to determine the roles that are associated with that identity.

Mapping using the subject distinguished name

Currently, the mapping of an X.509 certificate chain to an identity is done by taking the subject distinguished name from the first certificate in the X.509 certificate chain as an X.500 principal. This principal then gets rewritten using any principal decoders or principal transformers that have been configured, as shown below:

Mapping using a subject alternative name

The X.509 v3 Subject Alternative Name extension provides the ability to specify one or more alternative names that can be used in addition to or instead of the subject distinguished name in an X.509 certificate. From WildFly 18, it will also be possible to map an X.509 certificate chain to an identity by using a subject alternative name from the first certificate in the X.509 certificate chain. This principal will then get rewritten using any principal decoders or principal transformers that have been configured, as shown below:

In particular, to specify that a subject alternative name from a certificate should be used as the principal associated with that certificate, it will be possible to configure an x509-subject-alt-name-evidence-decoder in the mappers configuration in the Elytron subsystem. This element will have two attributes:

• alt-name-type - The subject alternative name type to decode. This required attribute must be one of the subject alternative name types that can be represented as a String:
  • rfc822Name
  • dNSName
  • uniformResourceIdentifier
  • iPAddress
  • registeredID
  • directoryName
• segment - The 0-based occurrence of the subject alternative name to map. This attribute is optional and only used when there is more than one subject alternative name of the given alt-name-type. The default value will be 0.

For example, to associate the X.509 certificate in the diagram above with the principal "bob.smith@example.com", it will be possible to configure the following x509-subject-alt-name-evidence-decoder:

/subsystem=elytron/x509-subject-alt-name-evidence-decoder=emailDecoder:add(alt-name-type=rfc822Name)

This evidence decoder can then be referenced when creating an Elytron security-domain:

/subsystem=elytron/security-domain=exampleSD:add(...,evidence-decoder=emailDecoder)

Other types of evidence decoders

It will also be possible to configure an x500-subject-evidence-decoder that will just extract the subject from the first certificate in the certificate chain, as an X.500 principal, as shown below:

/subsystem=elytron/x500-subject-evidence-decoder=subjectDecoder:add()

Finally, it will also be possible to configure an aggregate-evidence-decoder that is made up of two or more evidence decoders, as shown in the following example:

/subsystem=elytron/x509-subject-alt-name-evidence-decoder=emailDecoder:add(alt-name-type=rfc822Name)
/subsystem=elytron/x509-subject-alt-name-evidence-decoder=dnsDecoder:add(alt-name-type=dNSName)
/subsystem=elytron/x500-subject-evidence-decoder=subjectDecoder:add()
/subsystem=elytron/aggregate-evidence-decoder=aggregateDecoder:add(evidence-decoders=[emailDecoder,subjectDecoder,dnsDecoder])

The evidence decoders that make up an aggregate-evidence-decoder will be attempted in order until one returns a non-null principal or until there are no more evidence decoders left to try.

Summary

This blog post has described how we are enhancing the mapping of an X.509 certificate to an underlying identity in WildFly 18.