SAML in X.509 Validation
From Globus
This document is a draft describing how a relying party should process SAML assertions embedded in an X.509 certificate chain (which may include proxy certificates).
Contents
|
Background
A SAML assertion may be bound to an X.509 v3 end-entity certificate [RFC5280] or an X.509 proxy certificate [RFC3820]. We assume the reader is familiar with end-entity certificates. Some background on proxy certificates is provided in the following subsections.
The Certificate Chain
Assume that X.509 certification path validation (as defined by RFC 5280 and RFC 3820) has been accomplished and we have a valid certificate chain, which includes an end-entity certificate (EEC) and zero or more proxy certificates (PCs). This document refers to the proxy certificates as PC1, PC2, ..., PCn, with PC1 (a "level 1 proxy") being the proxy certificate issued by the EEC, and PCn (a "level n proxy") being the final certificate in the chain (i.e., the certificate containing the public key associated with the private key for which possession was proven). Thus the certificate chain is of length n + 1:
EEC, PC1, PC2, ..., PCn
The entity presenting the certificate chain and proving possession of the private key associated with PCn is referred to as the chain presenter or simply presenter if the presented certificate chain is understood.
Note: While the first certificate in the chain is typically an EEC, technically, the first certificate is a non-impersonation proxy, that is, either an EEC or an independent proxy (defined below). Regardless, this document consistently refers to the first certificate in the chain as the EEC.
Proxy Policies
A proxy certificate [RFC3820] has an associated proxyPolicy extension value, which defines the rights the proxy certificate inherits from its issuer. RFC 3820 defines two such policies:
-
id-ppl-inheritAll - This type of proxy certificate, called an impersonation proxy, inherits all rights from its issuer.
-
id-ppl-independent - This type of proxy certificate, called an independent proxy, inherits no rights from its issuer.
Additionally, the Grid Security Infrastructure, as implemented in Globus Toolkit, defines a third policy for a limited proxy, which inherits all the privileges of its issuer except for the right to launch jobs. For our purposes, a limited proxy is a type of impersonation proxy. Thus a non-impersonation proxy is either an EEC or an independent proxy.
Path Validation
RFC 5280 defines the notion of certification path validation, the process of finding a trusted path from the end-entity certificate to the root certification authority (CA). Similarly, RFC 3820 defines proxy certificate path validation, the process of finding a trusted path from PCn (the last PC in the proxy certificate chain) to the EEC. Proxy certificate path validation [RFC3820] depends on certification path validation [RFC5280]. In what follows, we use the term path validation to refer to proxy certificate path validation. Note: If n = 0, proxy path validation reduces to certification path validation.
The SAML Certificate Extension
Each certificate (PC or EEC) may contain a (non-critical) X.509 certificate extension containing a SAML assertion (or a reference to a SAML assertion, a possibility we ignore for simplicity). As discussed below, an assertion must be signed if it is not issued by the same entity that issued the containing certificate. Otherwise the signature on the certificate (previously verified during path validation) covers the extension. Thus an assertion issued by the same entity that issued the containing certificate (referred to as a self-issued assertion) need not be signed.
Walking the Proxy Certificate Chain
We now apply the following iterative algorithm to the proxy certificate chain (assuming PC0 is the end-entity certificate):
for each certificate in the certificate chain, beginning with PCn, do
if PCi has a SAML extension
process the SAML token
endif
if PCi is a non-impersonation proxy
break
endif
endfor
The above algorithm examines each certificate in the proxy certificate chain (starting with PCn) and further processes those certificates containing SAML assertions. If the current certificate is not an impersonation proxy, we are done processing the certificate chain. In particular, if the certificate is an end-entity certificate, we are done processing the certificate chain.
The SAML extension is bound to a non-critical X.509 extension having a well-known OID. Since the extension is non-critical, a relying party is free to ignore it. Thus an X.509 certificate with a SAML extension may be used anywhere an ordinary X.509 certificate is used.
Determining the SAML Token Type
For each certificate containing an assertion, the SAML token type is determined as follows:
if the assertion is self-issued
// verify optional signature: if the assertion is signed verify the signature if the signature can not be verified discard the assertion endif endif
// determine the method of subject confirmation: if the subject confirmation is holder-of-key if the certificate is an impersonation proxy process self-asserted SAML token else process self-issued SAML token with holder-of-key subject confirmation endif else if the subject confirmation is sender-vouches if the certificate is an impersonation proxy process self-issued SAML token with sender-vouches subject confirmation else discard the assertion endif else discard the assertion endif
else
// verify mandatory signature: if the assertion is signed verify the signature if the signature can not be verified discard the assertion endif else discard the assertion endif
// determine the method of subject confirmation: if the subject confirmation is holder-of-key process signed holder-of-key SAML token else discard the assertion endif
endif
Note that all of the following statements are true:
- If the assertion is signed and the signature can not be verified, the assertion is discarded.
- If the assertion is unsigned, it must be self-issued, that is, the assertion issuer and the issuer of the certificate must be one and the same entity. In this case, the signature on the certificate covers the assertion.
- If the assertion is unsigned but the assertion is not self-issued, the assertion is discarded.
- A self-issued holder-of-key SAML token bound to an impersonation proxy is a self-asserted SAML token.
- A self-issued SAML token bound to a non-impersonation proxy is necessarily a holder-of-key SAML token.
- A self-issued SAML token bound to an impersonation proxy is necessarily a sender-vouches SAML token.
- If the assertion is not self-issued, it must be a signed holder-of-key SAML token.
Of course any assertion that is accepted must be valid as specified in the relevant SAML Core specification.
Self-issued SAML Tokens
To process an assertion, an important distinction must be made:
An X.509-bound SAML token is self-issued if the assertion issuer is the certificate issuer.
Since the certificate issuer is given by a DN, it follows that a DN string comparison is required to determine if an assertion is self-issued. In practice, this is much more difficult than it sounds.
To first order, we require that the issuer of a certificate containing a SAML assertion set the Issuer XML attribute of the assertion to its X.509 Subject DN, formatted as an RFC 2253-conformant DN string. To determine whether or not the assertion is self-issued, a relying party reverses this process (and hopes for the best).
A SAML issuer is not usually known by a DN, however. The unique identifier of a SAML issuer (called an entityID) is very often an URI, and if SAML metadata is used, the entityID MUST be a URI. Thus if the relying party can map the SAML issuer (an URI) to an X.509 issuer (a DN), the assertion is considered to be self-issued.
A self-issued SAML token is an authorization token. Thus a self-issued SAML token must be bound to a trusted X.509 certificate, that is, a certificate that has undergone certification path validation [RFC5280] or proxy certificate path validation [RFC3820]. Put another way, the presenter of the X.509 certificate must be positively identified before a self-issued SAML token can be consumed.
Self-issued SAML tokens need not be signed. However, if a self-issued SAML token is (redundantly) signed, the signature must be verified, and moreover, the signer must be the certificate issuer.
An unsigned, self-issued SAML token should not be passed downstream to additional relying parties. In other words, a self-issued SAML token that is passed downstream should be signed.
Self-Asserted SAML Tokens
A self-asserted SAML token is a self-issued holder-of-key SAML token bound to an impersonation proxy.
Use Case 1. An end user uses an enhanced version of grid-proxy-init to self-assert attributes and bind those attributes to a proxy certificate. The grid service provider validates the presented proxy certificate as usual (i.e., using proxy certificate path validation [RFC3820]) and accepts the self-asserted attributes at its discretion. Presumably the grid service provider maintains a list of (benign) attributes it will accept from any user. For example, a grid service provider may accept a self-asserted e-mail address.
For example, a grid service provider may accept a self-asserted e-mail address from an unknown proxy issuer.
Self-Issued Holder-of-Key SAML Tokens
A self-issued holder-of-key SAML token bound to a non-impersonation proxy is accepted if and only if the certificate issuer is trusted to bind SAML tokens to issued certificates. In particular, the acceptance of a self-issued holder-of-key SAML token bound to a trusted end-entity certificate may require no additional processing at the relying party. That is, if an issuer is trusted to issue end-entity certificates, that issuer may be implicitly trusted to bind SAML tokens to those certificates (subject to policy at the relying party of course).
Use Case 2. A user obtains an end-entity certificate from a trusted certification authority (CA) such as the GridShib CA or the MyProxy CA. The CA binds a holder-of-key SAML token to the end-entity certificate. A grid service provider validates the end-entity certificate as usual (i.e., using certification path validation [RFC5820]) and accepts the SAML content without further processing.
Self-Issued Sender-Vouches SAML Tokens
A self-issued sender-vouches SAML token bound to an impersonation proxy is accepted if and only if the certificate issuer is trusted to bind SAML tokens to proxy certificates. Unlike self-issued holder-of-key SAML tokens issued by CAs, sender-vouches SAML tokens bound to proxy certificates are not automatically accepted at the relying party.
Use Case 3. A gateway uses gridshib-saml-issuer to bind a sender-vouches SAML token to a proxy certificate signed by a community credential. The gateway requests a grid service on behalf of a user, authenticating with the proxy certificate. The grid service provider authenticates the gateway (as itself) and accepts the SAML content describing the end user if the gateway's SAML identifier is on a list of trusted gateways.
Nested SSO SAML Tokens
A self-issued SAML token (that is not self-asserted) may contain an SSO assertion nested inside the <saml:Advice> element.
Use Case 4. (This use case is an extension of Use Case 2.) The GridShib CA is shib-enabled, that is, it is protected by the Shibboleth service provider software, which is an implementation of SAML Web Browser SSO. As a consequence of Web Browser SSO, the GridShib CA is presented with an SSO assertion, which is used to create a security context at the GridShib CA. This SSO assertion may be nested inside the <saml:Advice> element of a self-issued X.509-bound SAML token and forwarded (proxied) to the grid service provider for the purposes of access control. In particular, the authentication context in the SSO assertion may be used by the grid service provider for access control.
Likewise a Science Gateway may be shib-enabled (or more generally, SAML-enabled, since Gateways tend to be more lightweight). This leads to an extension of Use Case 3 for Science Gateways that is analogous to Use Case 4.
Holder-of-Key SAML Assertions
An X.509-bound SAML token that is not self-issued must be a signed holder-of-key SAML assertion. The signature on a signed holder-of-key SAML assertion must be verified (of course) and the subject must be confirmed as indicated in the holder-of-key <saml:SubjectConfirmation> element.
Use Case 5. An end user uses an enhanced version of voms-proxy-init to obtain a signed holder-of-key SAML token from a SAML-enabled VOMS server. Using gridshib-proxy-bind, the SAML token is bound to a proxy certificate signed by the user's trusted X.509 end-entity certificate, which is later presented to a grid service provider. The grid service provider authenticates the user as usual (i.e., using proxy path validation [RFC3820]) and confirms the subject as indicated in the holder-of-key <saml:SubjectConfirmation> element in the token, that is, by requiring the user to prove possession of the private key corresponding to the public key bound to the proxy certificate, and by comparing the subject DN bound to the end-entity certificate to the subject DN bound to the <saml:SubjectConfirmation> element.
A signed holder-of-key SAML token may be both an authentication token and an authorization token. In general, there is no hard requirement that a signed holder-of-key SAML token be bound to a trusted X.509 certificate.
Use Case 6. An end user has an account with a SAML identity provider. The user presents an untrusted X.509 end-entity certificate to the identity provider, proving possession of the corresponding private key (via TLS). If the identity provider can otherwise identify the user (say, by HTTP Basic Authentication), the identity provider issues a holder-of-key SAML token containing an authentication statement and a holder-of-key <saml:SubjectConfirmation> element containing a <ds:X509SKI> element (assuming of course the EEC contains such an element). The user uses an enhanced version of gridshib-proxy-bind to bind the SAML token to a proxy certificate signed by the untrusted end-entity credential such that the same public key is bound to both the end-entity certificate and the proxy certificate. As expected, proxy certificate validation [RFC3820] at the grid service provider will fail (since the end-entity certificate is untrusted), but since the grid service provider trusts the identity provider to issue an authentication statement for the user, and since the user is able to prove possession of the private key corresponding to the public key bound to the proxy certificate, the requirements of the holder-of-key <saml:SubjectConfirmation> element in the SAML token are met.
Processing the SAML Assertion
To process a SAML assertion, a relying party performs the following operations:
- Parse the SAML subject and add the
<saml:NameIdentifier>element to the security context. - Parse the
<saml:AuthenticationStatement>element (if present) and add the resulting authentication context to the security context. - Parse each
<saml:AttributeStatement>element (if any) and add the resulting attributes to the security context.
In each case, the SAML issuer (defined below) accompanies any object added to the security context.
If the assertion contains one or more nested assertions (in a <saml:Advice> element), recursively process each nested assertion. In the case of nested assertions, however, the SAML issuer is a list of issuers (as discussed below).
Validating the SAML Assertion
A SAML V1.1 assertion bound to an X.509 certificate is valid if and only if all of the following statements are true:
- The assertion is valid according to section 2 of SAMLCore.
- The assertion is valid according to the Subject-based Profiles for SAML V1.1 Assertions.
- The assertion is valid according to the X.509 Binding for SAML. (This binding specification has not yet been published. See the foreign wiki topic X509BindingSAML for a preliminary list of requirements.)
Trusting the SAML Assertion
Observe the following relationship between consecutive certificates in the certificate chain:
subject(EEC) = issuer(PC1)
subject(PCi) = issuer(PCi + 1) for i = 1, …, n - 1
Thus for any PC in the chain, the issuer can be traced back to the subject of the EEC. This leads to the following definition:
For an impersonation proxy containing a SAML assertion, if the assertion is self-issued, the SAML issuer is the subject of the EEC. In all other cases, the SAML issuer is the actual assertion issuer (given by the Issuer XML attribute in the assertion).
In particular, for an EEC, the SAML issuer is always the assertion issuer.
Subsequently, the SAML assertion is discarded if the SAML issuer (as defined above) is not on a pre-configured list of trusted SAML issuers. Specifically, every assertion is associated with a SAML issuer, and by inclusion, every attribute is likewise associated with the same SAML issuer. Any given attribute is filtered if its SAML issuer is not on the list of trusted SAML issuers. More generally, an attribute is subject to attribute acceptance policy, which is a function of the trusted SAML issuer and possibly other policy constraints.
Nested SAML Assertions
A SAML assertion may contain a nested SAML assertion in a <saml:Advice> element. Policy associated with nested assertions is more complicated than top-level assertions. To accommodate nested assertions, a list of SAML issuers is maintained per attribute. A list of length 1 indicates the SAML issuer issued the attribute directly (in a top-level assertion). If the list is of length greater than 1, the attribute was asserted indirectly (in a nested assertion).
For example, suppose the SAML issuer consists of a list of two identiifers, ID0 and ID1. The latter is the identifier of the issuer that issued the attribute (in a nested assertion). ID0 is the identifier of the issuer that issued an assertion containing that nested assertion.
In general, suppose the SAML issuer is given by a list of identifiers ID0, ID1, …, IDn. The latter is the identifier of the issuer that issued the attribute (in a level n nested assertion). Issuers ID0, ID1, …, IDn - 1 are intermediary issuers, that is, proxy issuers (not to be confused with proxy certificates).
A relying party trusts the attribute issued by issuer IDn if it trusts all the issuers ID0, ID1, …, IDn. In particular, the relying party trusts the issuers ID0, ID1, …, IDn - 1 to be proxy issuers, while trusting IDn to be an actual attribute issuer. Thus there are at least two types of trusted SAML issuers of interest.
