NativeSPRelyingParty
The <RelyingParty>
element allows the SP to customize its behavior when it interacts with particular identity providers or groups of providers. By default, many properties are set globally to an application. This element allows them to be overridden. Individual options can be selectively overriden within the <RelyingParty>
element.
Selection of an element can be named-based, or in V2.5 and above, can rely on an extensible matching mechanism called an EntityMatcher.
If the Name
attribute is present, then the matching process starts with the IdP's entityID
, and proceeds upwards through the IdP's Metadata matching against <EntitiesDescriptor>
group names that are found. The most specific match wins.
If the Name
attribute is not present, then a type
attribute must be used to indicate the type of EntityMatcher to apply, and other content will be required based on the type of matcher to specify how to match.
Prior to V2.5, only the Name
matching option is supported.
<ApplicationDefaults ... authType="TLS" artifactEndpointIndex="1" signing="false" encryption="false" requireConfidentiality="true" requireTransportAuth="true" signedAssertions="false" chunkedEncoding="false" connectTimeout="15" timeout="30" > ... <RelyingParty Name="SpecialFederation" keyName="special.example.org"/> ... </ApplicationDefaults>
Attributes
Name
(string)- For name-based matching, this is the value used to match against the IdP's
entityID
or parent group names. As of V2.5, this attribute is optional and can be omitted in favor of atype
attribute.
- For name-based matching, this is the value used to match against the IdP's
type
(string) (Version 2.5 and Above)- For extensible matching, specifies the type of EntityMatcher to use. Refer to the associated documentation for additional required content.
entityID
(URI)- Overrides the unique identifier used by the SP to identify itself when communicating with matching relying parties. Normally an SP should be able to use a single name in all its dealings, but this can provide some help when dealing with externally imposed limitations.
authType
(string) (defaults to"TLS"
)- Specifies the transport-layer authentication mechanism that is used for back-channel SOAP messages to an IdP. The values permitted are implementation dependent, but may include:
TLS
- client certificate TLS/SSL authentication
basic
- HTTP Basic-Auth (cleartext name/password)
digest
- HTTP Digest-Auth
ntlm
- Microsoft's NTLM authentication
gss
- GSS-API (SPNEGO)
- Specifies the transport-layer authentication mechanism that is used for back-channel SOAP messages to an IdP. The values permitted are implementation dependent, but may include:
authUsername
(string)- Required for non-TLS and GSS
authType
values, this is the username to use.
- Required for non-TLS and GSS
authPassword
(string)- Required for non-TLS and GSS
authType
values, this is the password to use.
- Required for non-TLS and GSS
signing
(see NativeSPSigningEncryption)- Controls outbound signing of XML messages.
signingAlg
(URI) (defaults to the specifier for RSA-SHA1)- An XML Signature signature algorithm specifier for signatures produced by the SP.
digestAlg
(URI) (defaults to the specifier for SHA1)- An XML Signature digest algorithm specifier for signatures produced by the SP.
encryption
(see NativeSPSigningEncryption)- Controls outbound encryption of XML messages and content.
encryptionAlg
(URI) (defaults to the specifier for RSA-OAEP-SHA1)- An XML Encryption key wrap/transport algorithm specifier for encryption performed by the SP. The actual symmetric encryption algorithm will be derived from it.
keyName
(string)- Specifies a particular credential to use for signing or TLS authentication by attaching a name to the lookup criteria passed to the credential resolver in use. Typically the credential resolver will be able to attach names or aliases to credentials in some fashion. For more on using this feature, see the NativeSPMultipleCredentials topic.
artifactEndpointIndex
(string)- Identifies which
<ArtifactResolutionService>
handler at the SP is used when sending artifact-bound messages to the relying party. Endpoints typically include anindex
attribute to copy here.
- Identifies which
chunkedEncoding
(boolean) (defaults to false)- Controls the use of chunked encoding during back-channel SOAP communication. HTTP clients sending data must either compute and send a Content-Length header to the server (requiring that all data be buffered ahead of time), or use chunked encoding. A lot of servers mis-handle this option, so it is disabled by default.
connectTimeout
(time in seconds) (defaults to 10)- Specifies the timeout for connecting to remote servers during back-channel SOAP communication.
timeout
(time in seconds) (defaults to 20)- Specifies the total time to allow for completing back-channel SOAP communication.
requireConfidentiality
(boolean) (defaults to true)- When true, the SP will require the use of TLS/SSL for all back-channel SOAP communication. This prevents an unsafe exchange of data before an unencrypted channel might be used, since XML encryption depends on the peer's willingness to use it.
requireSignedAssertions
(boolean) (defaults to false)- When true, assertions MUST be digitally signed, regardless of any other signatures used to authenticate them. Typically needed only for advanced auditing or assertion forwarding use cases.
requireTransportAuth
(boolean) (defaults to true, but see NativeSPSigningEncryption)- When true, the SP will require back-channel SOAP communication to be authenticated at the transport layer (TLS/SSL server authentication). Prior to V2.6, must be set to false to permit the relying party to authenticate using only message signatures. See the NativeSPSigningEncryption topic for some additional semantics added in V2.6.
Version 2.5 and Above
sessionHook
(absolute or relative URL)- Specifies a location to send the client after a session has been created (i.e., after login), but before transferring the client to the eventual final resource. This is normally a relative path to ensure that the session will be visible to the hook script, but doesn't have to be. A hook can be used to validate something about the session to check its "fitness for purpose" before delivering the client to an application that may not offer sufficient error handling capability to do the job itself. A common example is checking for required attributes. The hook redirect will include two parameters,
target
andreturn
. Thetarget
parameter contains the resource URL that will eventually be the client's destination, in case the hook cares. Thereturn
parameter is the location to redirect the client back to upon completion of the hook. The hook MUST either redirect back or take complete ownership of the client with no further processing by the SP.
- Specifies a location to send the client after a session has been created (i.e., after login), but before transferring the client to the eventual final resource. This is normally a relative path to ensure that the session will be visible to the hook script, but doesn't have to be. A hook can be used to validate something about the session to check its "fitness for purpose" before delivering the client to an application that may not offer sufficient error handling capability to do the job itself. A common example is checking for required attributes. The hook redirect will include two parameters,
artifactByFilesystem
(boolean) (defaults to false)- Enables the artifact-based "back-door" external authentication mechanism described in NativeSPBackDoor.
Version 2.6 and Above
cipherSuites
(OpenSSL cipher expression) (defaults to "ALL:!aNULL:!LOW:!EXPORT:!RC4:!SSLv2")- Directly configures the TLS ciphers to support when making SOAP connections. The default value is historical and has been in place for a few releases, and has been left alone to prevent upgrades from affecting interoperability. A stronger value is now used in the default files distributed with the software, which was derived from Mozilla's tool.
authnContextClassRef
(space-delimited list of URIs)- Supplies values for the SAML 2.0
<AuthnContextClassRef>
element in requests to applicable IdPs, or for thewauth
parameter in WS-Federation requests. Ignored for other protocols.
- Supplies values for the SAML 2.0
authnContextComparison
("exact", "minimum", "maximum", "better")- Supplies values for the
<RequestedAuthenticationContext>
comparison operator in SAML 2.0 requests to applicable IdPs. Ignored for other protocols.
- Supplies values for the
NameIDFormat
(URI)- Supplies a value for the
<NameIDPolicy>
element'sFormat
attribute in SAML 2.0 requests to applicable IdPs. Ignored for other protocols.
- Supplies a value for the
SPNameQualifier
(URI)- Supplies a value for the
<NameIDPolicy>
element'sSPNameQualifier
attribute in SAML 2.0 requests to applicable IdPs. Ignored for other protocols.
- Supplies a value for the