8. Vocabulary

8.1. Connection parameters explained

List of properties used to set up connection between DNN and AD FS.

8.1.1. Issuer

The “Issuer” property is an URL address of the security token service (STS), login service, to which to send WS-Federation sign-in and sign-out requests. The “Issuer” usually consists of two parts. Part one it’s a AD FS identifier. Second part it’s adfs/ls/. The AD FS identifier can be found here:

_images/base-configuration-connection-issuer_01.png

In our case “Issuer” will be: https://W-Server12R2.cloudapp.net/adfs/ls/

More info about that property here

8.1.2. Issuer Name Registry

“Issuer Name Registry” is a string (usually a url) that represents the Federation Service. To obtain the “Issuer Name Registry” for ADFS, follow steps from figure below:

_images/base-configuration-connection-issernameregistry_01.png

In our case “Issuer Name Registry” will be: https://W-Server12R2.cloudapp.net/adfs/services/trust

8.1.3. Certificate thumbprint

This thumbprint is taken from a “Token-signing” certificate on AD FS. The “ADFS-Pro Authentication” accepts only thumbprint not separated by the space. See figures below for reference.

_images/base-configuration-connection-certificate_01.png _images/base-configuration-connection-certificate_02.png

Applied thumbprint without spaces.

_images/base-configuration-connection-certificate_03.png

8.1.4. Realm

“Realm” is a identifier of your DNN application, that is used by the AD FS to know who you are. “Realm” usually has a format of URL. To obtain the “Realm” follow steps from the figure below.

_images/base-configuration-connection-realm_01.png

In our case “Realm” will be: https://w-server12r2-vs.cloudapp.net/

8.1.5. Home realm

The “Home Realm” is a identity provider (IdP) address, which is usually AD FS address By default “Home Realm” is equal to “Issuer”. In the WS-Federation sign-in request, the query string parameter whr is equal to the “Home realm”.

In our case “Home Realm” will be: https://W-Server12R2.cloudapp.net/adfs/ls/

8.1.6. Audience Uri

“Audience URI” is an address (or a list of addresses) where user will back after sign in process. After sign-in process, AD FS will send message back to “Audience URI”, which is our DNN website address. This parameter will make sure that the token was really meant for our own DNN web application.

In our case “Audience Uri” will be: https://w-server12r2-vs.cloudapp.net/

8.1.7. Authentication Type

The “Authentication Type” property is an URI that identifies the type of authentication that is used. Value of the “Authentication Type” property will be injected into the sign-in requet, as a query string parameter, behind the wauth key. This property is optional and by default should be empty. The allowable types for “Authentication Type” are:

  • urn:federation:authentication:windows for Windows integrated authentication,
  • urn:oasis:names:tc:SAML:1.0:am:password http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password for user name/password authentication i.e. Forms,
  • urn:ietf:rfc:2246 for SSL client authentication,

8.1.8. Passive Redirect Enabled

The “Passive Redirect Enabled” property specifies whether the WSFAM is enabled to automatically redirect unauthorized requests to an STS. This property is optional and by default should has value “true”, where unauthorized requests will be automatically redirected.

8.1.9. Unique claim

This property will inform DNN which type of the claim should be treated as unique. This property is optional and by default should be empty or equal to: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn.

8.2. Active Directory Federation Services (ADFS)

A Windows Server 2003 R2 component (2003 or above) that provides Web single-sign-on (SSO) technologies to authenticate a user to multiple Web applications over the life of a single online session.

ADFS accomplishes this by securely sharing digital identity and entitlement rights across security and enterprise boundaries. Reference Terminology used in ADFS

8.3. WS-Federation

WS-Federation (which is short for Web Services Federation) is a protocol that can be used to negotiate the issuance of a token. You can use this protocol for your applications (such as a Windows Identity Foundation-based app like DNN) and for identity providers (such as Active Directory Federation Services or Azure AppFabric Access Control Service).

8.4. ADFS Federation Metadata

Information about the services offered by the AD FS server. These information are served by following endpoint:

https://YourAdfsDomain/FederationMetadata/2007-06/FederationMetadata.xml

for example:

https://adfs.server2012.org/FederationMetadata/2007-06/FederationMetadata.xml

8.5. Claim

“Claim” is a piece of identity information such as name, e-mail address, age, membership in the Sales role. In our case “AD FS” sends claims to the “DNN”.

You may be wondering why these are called “Claims”, rather than “Attributes”, as is commonly used in describing enterprise directories. The reason has to do with the delivery method. In this model, your application doesn’t look up user attributes in a directory. Instead, the user delivers claims to your application, and your application examines them. Each claim is made by an issuer, and you trust the claim only as much as you trust the issuer. For example, you trust a claim made by your company’s domain controller more than you trust a claim made by the user herself. WIF represents claims with a Claim type, which has an Issuer property that allows you to find out who issued the claim .

8.6. Single SignOn - SSO

The “Single SignOn” is really nothing else but an application of the widely used “Remember Me” function. In other words it’s a optimization of the authentication sequence to remove the burden of repeated logon actions by an end user. Say you have two web applications, “SiteA” and “SiteB” that share the same STS (AD FS).

  1. You start the day by logging in to “SiteA” and do some work there. The STS will establish a login session with the client. The browser will send the “FedAuth” cookie with all subsequent requests.
  2. Then at some point you need to use “SiteB”. “SiteB” also needs authentication and redirects the user to the same STS. However, the STS will recognise the user’s FedAuth cookie and will issue another token for “SiteB” without having to log in again.

Therefore we get “Single SignOn” accross all applications that use the same STS (AD FS).

8.7. Security Token Service (STS)

A “Security Token Service” is a web service that issues security tokens, commonly it’s a “AD FS”. The “AD FS” can generate tokens, but it can also rely on a separate STS. The “Azure AD” could be that kind of separate STS.

8.8. Home Realm Discovery (HRD)

“HRD” it’s a key in the query string of the URL that point’s to ADFS login page. “HRD” has value equal to “Home realm” that will redirects the user to a particular IdP, without an option to choose one from the list. More info:

8.9. Login URL parameters

Below are described other parameters which may exist in the login URL behind the query string.

  • wa - the version of the sign-in protocol. For example wsignin1.0 (default value),
  • wtrealm - the identifier of a “Relying party” created on AD FS, aka “Realm”. Value of “wtrealm” is a encoded url.
  • wct - a time stamp,
  • wctx - specifies state, more info chapter below wctx

8.10. wctx

This is a query string param passed to the login URL, that specifies state (context) of the DNN application. It has following format:

ru=returnUrl&cx=SignInContext&rm=rememberMeSet&id=uniqueId
  • ru is the value of the “returnUrl” parameter. It specifies the URL that the AD FS should redirect the browser after successful authentication. The DNN website address should be here.
  • cx parameter is set to the value of the SignInContext property. This property is exposed to enable you to set any application-defined context that should be stored in the wctx string; however, WSFAM does not expose a method to extract this value in the response. If the value is needed by your application, you must provide the code to parse the wctx string and read this value when processing the response. You might accomplish this by overriding the GetReturnUrlFromResponse method.
  • rm value, which is set to the value of the rememberMeSet parameter, nor the id parameter, which is set to the value of the uniqueId parameter are used by WSFAM. These can be set to any value.

8.11. MSISIPSelectionPersistent

The “MSISIPSelectionPersistent” is the name of persistent cookie which is written to the file system on the client side. It holds the value of the identity provider (IdP), an “EntityID”. The “MSISIPSelectionPersistent” cookie data is base64 encoded, so you can use your favorite base64 decoder to see the value of the identity provider.

If the client does not already have this cookie set, and there are multiple IdP-s to choose from, AD FS will prompt the user to select an IdP through a process called Home Realm Discovery (HRD).

8.12. MSISAuth

The MSISAuth (MSISAuth + MSISAuth1 + …) are the encrypted cookies used to validate the SAML assertion produced for the client. The cookie is used for subsequent authentications against the ADFS. These are what we call the “authentication cookies”, and you will see these cookies ONLY when AD FS 2.0 is the IdP. Without these, the client will not experience SSO. It has an /adfs/ls path on them so you cannot delete them from a page executing outside of this context.

8.13. MSISAuthenticated

The “MSISAuthenticated” is the name of cookie that contains a base64-encoded timestamp value for when the client was authenticated.

8.14. MSISSignout

The “MSISSignout” is the name of cookie that is used to keep track of the IdP and all RPs visited for the SSO session. This cookie is utilized when a WS-Federation sign-out is invoked. You can see the contents of this cookie using a base64 decoder.

8.15. MSISLoopDetectionCookie

The “MSISLoopDetectionCookie” is the name of the cookie that is used by the AD FS 2.0 infinite loop detection mechanism to stop clients who have ended up in an infinite redirection loop to the Federation Server.

For example, if an RP is having an issue where it cannot consume the SAML assertion from AD FS, the RP may continuously redirect the client to the AD FS 2.0 server. When the redirect loop hits a certain threshold, AD FS 2.0 uses this cookie to detect that threshold being met, and will throw an exception which lands the user on the AD FS 2.0 error page rather than leaving them in the loop. The cookie data is a timestamp that is base64 encoded.

8.16. More info

For more info about AD FS see following articles: