How URIs Are Used in AD FS
Applies To: Windows Server 2012
A Uniform Resource Identifier (URI) is a string of characters that is used as a unique identifier. In AD FS, URIs are used to identify both partner network addresses and configuration objects. When used to identify partner network addresses, the URI is always a URL. When used to identify configuration objects, the URI may be a URN or a URL. For more general information about URIs, see RFC 2396 and RFC 3986.
URIs as partner network addresses
The following are the network address URLs that are most often handled by administrators in AD FS.
The URLs of the Federation Service, including WS-Federation, SAML, WS-Trust, Federation Metadata, WS-MetadataExchange, Privacy and Organization URLs
The URLs of a relying party trust, including WS-Federation, SAML, and Federation Metadata URLs
The URLs of a claims provider trust, including WS-Federation, SAML, and Federation Metadata URLs
URIs as object identifiers
The following table describes the identifiers that are most often handled by administrators in AD FS.
Identifier name |
Description |
Comparisons |
|---|---|---|
Federation Service identifier |
This identifier is used to identify the Federation Service. It is used by relying parties that use claims from this Federation Service, as well as claims providers that issue claims to this Federation Service. |
When a user requests claims from a claims provider for this Federation Service, the Federation Service identifier will be used to identify the target for the claims. When this Federation Service receives the claims from a claims provider, it will check to ensure the claims are scoped for it by looking for its Federation Service identifier. When a relying party is receiving claims from this Federation Service, the relying party will check that the issuer of the claims matches the Federation Service identifier. |
Relying party identifier |
This identifier is used to identify the relying party to this Federation Service. It is used when issuing claims to the relying party. |
When a user requests claims from this Federation Service for the relying party, the relying party identifier will be used to identify the relying party for which the claims should be targeted. This comparison is done using prefix matching (see below). When the relying party receives the claims, it will check for its identifier in the security token to ensure the claims are targeted for it. |
Claims provider identifier |
This identifier is used to identify the claims provider to this Federation Service. It is used when receiving claims from the claims provider. |
When this Federation Service is receiving claims from the claims provider, this Federation Service will check that the issuer of the claims matches the claims provider identifier. |
Claim type |
This identifier is used to define the type of claim. It is used by this Federation Service, claims providers, and relying parties when sending and receiving claims. |
When the Federation Service receives claims from a claims provider, the claim rules associated with the corresponding claims provider trust allow the administrator to compare claim types and process claims. The claim rules associated with a relying party trust also allow the administrator to compare claim types from the claims coming out of the claims provider trust rules, and decide which claims to issue. |
URI prefix matching for relying party identifiers
The path syntax of a URI is organized hierarchically and is delimited by either all “/” characters or all “:”characters. Thus the path may be split into path sections based on the delimiting character. When prefix matching, each section must be a full match according to the matching rules (these rules govern the casing of matches). For more information about matching rules, see the RFC’s mentioned above.
When a relying party is identified in a request to the Federation Service, AD FS uses prefix matching logic to determine if there is a matching relying party trust in the AD FS configuration database.
For example, if the relying party identifier in the AD FS configuration database (URI1) is a prefix to the relying party identifier in the incoming request (URI2), then the following must be true:
Trailing delimiters (slashes and colons) of path sections or authorities must be ignored
The scheme and authority parts of URI1 and URI2 must be a case insensitive exact match
Each path section of URI1 must be an exact match (based on the case sensitivity chosen) to the corresponding path section of URI2
URI2 may have more path sections than URI1, but URI1 must not have more path sections than URI2
URI1 cannot have more path sections than URI2
If URI1 has a query string, it must match exactly to a URI2 query string
If URI1 has a fragment, it must match exactly to a URI2 fragment
The following table provides additional examples.
Relying party identifier in AD FS configuration database |
Relying party identifier in request message |
Request identifier matches the configuration identifier? |
Reason |
|---|---|---|---|
https://contoso.com |
https://contoso.com |
TRUE |
Exact match |
https://contoso.com/ |
https://contoso.com |
TRUE |
Trailing slashes are ignored |
https://contoso.com |
https://contoso.com/ |
TRUE |
Trailing slashes are ignored |
https://contoso.com |
https://contoso.com/hr |
TRUE |
URI1 has no path and matches scheme and authority to URI2 |
https://contoso.com/hr |
https://contoso.com/hr/web |
TRUE |
First path sections match, URI1 has no second path section |
https://contoso.com/hr |
https://contoso.com/hr/web/?m=t |
TRUE |
Same reasons as above, query string doesn’t change anything |
https://contoso.com/hr/ |
https://contoso.com/hrw/main |
FALSE |
URI1 path section 1 does not match URI2 path section 1 |
https://contoso.com/hr |
https://contoso.com |
FALSE |
URI1 has more path sections than URI2 |
https://contoso.com/hr |
https://contoso.com/hrweb |
FALSE |
First path sections do not match |
https://contoso.com/?m=t |
https://contoso.com/?m=f |
FALSE |
Query string parts do not match |
https://contoso.com |
https://contoso.com |
FALSE |
Scheme parts do not match |
https://sts.contoso.com |
https://contoso.com |
FALSE |
Authority parts do not match |
https://contoso.com |
https://sts.contoso.com |
FALSE |
Authority parts do not match |