Extract Attributes From Certificate Assertion

3
gateway90
3
The 
Extract Attributes from Certificate 
assertion extracts information from the X.509 Certificate of the last authenticated user and places them in context variables. Specifically, the subject/issuer DN fields are parsed and made available as context variables, as well as some extended attributes.
You can create a custom prefix to be added to context variables created by this assertion, to help make the context variables more readily identified.
In a policy, the Extract Attributes from Certificate assertion must be preceded by:
  • At least one credential source assertion:
  • Require SSL or TLS Transport with Client Authentication
  • Require WS-Secure Conversation
  • Require WS-Security Signature Credentials
  • Require SAML Token Profile 
    (Subject Confirmation: Holder of Key, Require Message Signature)
  • An identity assertion (for example, Authenticate User or Group)
Context Variables for Subject/Issuer DN
The Extract Attributes from Certificate assertion sets the following context variables for the subject/issuer DN in an X.509 certificate. Note: The default 
<prefix>
 is "certificate" and can be changed in the assertion properties.
The sample values shown are based on the following example subject DN:
cn=jsmith, OU=support, OU=IT, OU=Services, DC=acmecorp, DC=org, C=US
Context variable
Description
${
<prefix>
.subject.dn}
Contains the subject DN in a format that is easier to read.
${
<prefix>
.subject.dn.canonical}
Contains the subject DN in a format suitable for comparisons (limited subset of entity ID names; strict sorting, whitespace, and case rules).
${
<prefix>
.subject.dn.rfc2253}
Contains the subject DN in a format that is technically precise, yet maintains readability. This only includes RFC 2253 entity ID names.
${
<prefix>
.subject.cn}
Contains the "cn" value of the subject (e.g., jsmith)
${
<prefix>
.subject.ou}
Contains the "ou" values of the subject (e.g., support, IT, Services)
${
<prefix>
.subject.dc }
Contains the "dc" value of the subject (e.g., acmecorp, org)
${
<prefix>
.subject.c }
Contains the "c" value of the subject (e.g., US)
${
<prefix>
.subjectPublicKeyAlgorithm }
Contains the Name of the Signature Algorithm for the certificate (e.g., "SHA1withRSA")
${
<prefix>
.subjectEmail}
Contains the email address (if any) from the Subject DN
${
<prefix>
.subjectAltNameEmail}
Contains the email address (if any) for the Subject Alternative Name (rfc288) (e.g., "[email protected]")
${
<prefix>
.subjectAltNameDNS}
Contains the DNS Name address (if any) for the Subject Alternative Name (e.g., "example2.oasis-open.org")
${
<prefix>
.subjectAltNameURI}
Contains the Uniform Resource Identifier (if any) for the Subject Alternative Name (e.g., "http://example2.oasis-open.org/")
${
<prefix>
.issuer.dn}
Contains the issuer DN in a format that is easier to read.
${
<prefix>
.issuer.dn.canonical}
Contains the issuer DN in a format suitable for comparisons (limited subset of entity ID names; strict sorting, whitespace, and case rules).
${
<prefix>
.issuer.dn.rfc2253}
Contains the issuer DN in a format that is technically precise, yet maintains readability. This only includes RFC 2253 entity ID names.
${
<prefix>
.issuer.c }
Contains the "c" (CountryName) value of the issuer
${
<prefix>
.issuer.cn}
Contains the "cn" (CommonName) value of the issuer
${
<prefix>
.issuer.dc }
Contains the "dc" (DomainComponent) value of the issuer
${
<prefix>
.issuer.l }
Contains the "l" (LocalityName) value of the issuer
${
<prefix>
.issuer.o}
Contains the "o" (OrganizationName) value of the issuer
${
<prefix>
.issuer.ou}
Contains the "ou" (OrganizationalUnitName) value of the issuer
${
<prefix>
.issuer.st }
Contains the 'st' (StateorProvinceName) value of the issuer
${
<prefix>
.issuer.street }
Contains the 'street' (StreetAdress) value of the issuer
${
<prefix>
.issuerEmail}
Contains the email address (if any) from the Issuer DN
${
<prefix>
.issuerAltNameEmail}
Contains the email address (if any) for the Issuer Alternative Name (rfc288)
${
<prefix>
.issuerAltNameDNS}
Contains the DNS Name address (if any) for the Issuer Alternative Name
${
<prefix>
.issuerAltNameURI}
Contains the Uniform Resource Identifier (if any) for the Issuer Alternative Name
If an attribute is not recognized, the following variable will be created for it:
${prefix.subject.oid.1.2.3},
where "1.2.3" is the dotted-decimal entity ID of the attribute.
Context Variables for Extended Attributes
The Extract Attributes from Certificate assertion sets the following context variables for the extended attributes of an X.509 certificate. The default 
<prefix>
 is "certificate" and can be changed in the assertion properties.
Context variable
Description
${
<prefix>
.countryOfCitizenship}
Contains the country of citizenship. Since there can be multiple values, this is an array of 2-letter country codes.
${
<prefix>
.signatureAlgorithmName}
Contains the Name of the Signature Algorithm for the certificate (e.g., "SHA1withRSA")
${
<prefix>
.signatureAlgorithmOID}
Contains the entity ID of the Signature Algorithm for the certificate (e.g., "1.2.840.113549.1.1.5")
${
<prefix>
.serial}
Contains the Certificate Serial#
${
<prefix>
.notAfter}
Contains the Certificate Not After Date (e.g., "2018-03-19T23:59:59.000Z")
${
<prefix>
.notBefore
Contains the Certificate Not Before Date (e.g., "2005-03-19T00:00:00.000Z")
Key usage information are stored in the following variables. If no key usage extension is present in the certificate, the criticality is set to "none" and all the Boolean variables are set to "false".
${
<prefix>
.keyUsage.criticality}
Whether the extension is present; if so whether it is critical. The following values are used:
  • none
    = extension not present
  • noncrit
    = extension is present but not critical
  • critical
    = extension is present and critical
${
<prefix>
.keyUsage.digitalSignature}
Digital signature (true/false)
${
<prefix>
.keyUsage.nonRepudiation}
Non Repudiation (true/false)
${
<prefix>
.keyUsage.keyEncipherment}
Key Encipherment (true/false)
${
<prefix>
.keyUsage.dataEncipherment}
Data Encipherment (true/false)
${
<prefix>
.keyUsage.keyAgreement}
Key Agreement (true/false)
${
<prefix>
.keyUsage.KeyCertSign}
Key Certificate Sign (true/false)
${
<prefix>
.keyUsage.cRLSign}
CRL Sign (true/false)
${
<prefix>
.keyUsage.decipherOnly}
Decipher Only (true/false)
Extended key usage information is stored in the ${<prefix>.extendedKeyUsage} variable. If no extended key usage information is present in the certificate, the criticality is set to "none" and the arrays are empty.
${
<prefix>
.extendedKeyUsage.criticality}
Whether extended key usage is present; if so whether it is critical. The following values are used:
  • none
    = extended information not present
  • noncrit
    = extended information is present but not critical
  • critical
    = extended information is present and critical
${
<prefix>
.extendedKeyUsage}
Contains the extended key usage information, stored as an array of strings. Each value is a dotted-decimal entity ID.
${
<prefix>
.certificatePolicies}
Contains certificate policies information, stored as an array of strings. Each value is a dotted-decimal entity ID.
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the Policy Development window, see Adding an Assertion.
    • To change the configuration of an existing assertion, proceed to step 2 below
  2. When adding the assertion, the 
    Certificate Attributes Properties
     automatically appear; when modifying the assertion, right-click 
    Extract Attributes from Certificate 
    in the policy window and select 
    Certificate Attributes Properties
     or double-click the assertion in the policy window. The assertion properties are displayed.
  3. Enter a prefix that will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent the variables from overwriting each other when multiple instances of this assertion appear in a policy.
    The default variable prefix is 
    certificate
    .
    For an explanation of the validation messages displayed, see Context Variable Validation. 
  4. Click [
    OK
    ] when done.