Category Archives: PointSharp

Back to the Home Realm Discovery in 2012 R2

Hello all.  You may recall from older posts on this blog (2012) that we’ve played around in the past with Home Realm Discovery (HRD) in AD FS.

First with IWA and forms logon here and then a little bit more for good measure. Since then it’s been a little quiet on the HRD fence and not a subject delved into much since. That is, until an issue a colleague and I  ran into an issue recently… confronted with the following AD FS R2 access conundrum:

How can we route (automatically) external  logon requests to a third-party claims provider,  continue to route internal logon requests to the native AD claims provider (i.e. maintain transparent SSO), eliminating any Home Realm Discovery (HRD) for our users to have to walk through and select?

Or… to put it more simply. How can one automatically route external route requests to claims provider A, continue to route internal requests to (AD) claims provider B, whilst altogether avoiding Home Realm Discovery (HRD) for all users?

We’ll discuss the exact use case in a moment. This is a RP-initiated work-flow. No IDP-initiated flow or smart links are allowed.

First, a bit of background. Let’s head back to the first look posts on AD FS 2012 R2 in 2013/2014. In there I wrote:

In AD FS R2, HRD customization options through PowerShell now allow us to determine how the UI is presented to the end-user during logon, based on:

1. target suffix resolution – providing suffix routing on a per claims provider basis
2. limiting the claims providers visible for the relying party concerned

With the move to kernel-mode in R2, customization previously possible under IIS in AD FS 2.0 was no longer applicable. To redress this issue and to provide greater flexibility, the above customization options were provided. Suffix routing enables AD FS 2012 R2 to select an appropriate claims provider based on the domain suffix credentials provided by that user. Broadly speaking, this is just how O365/Azure AD works in attempting to discover the Federated home realm v Microsoft realm of the connecting user. Similarly, for on-premise AD FS, suffix routing enables us to refine our logon decision-making based on the home realm of the connecting user. Here’s an example:

  • Users from the Cranky Nuts organization, connecting via AD FS, use a @crankynuts.nl domain suffix. Accordingly, we need to send authentication requests to the Cranky Nuts Identity Provider.
  • Users from the Wobbly Wheels organization, connecting via AD FS, use a @wobblywheels.be domain suffix. Accordingly,  we need to send authentication requests to the Wobbly Wheels Identity Provider.

In AD FS 2012 R2 we can configure this within Powershell:

Set-AdfsClaimsProviderTrust –TargetName “Cranky Nuts IdP” –OrganizationalAccountSuffix @(“crankynuts.nl”)
Set-AdfsClaimsProviderTrust –TargetName “Wobbly Wheels IdP” –OrganizationalAccountSuffix @(“wobblywheels.be”)

Wonderful! Using this approach can be a little hit and miss though. It’s making certain assumptions about the level at which we’re prepared to divert authentication on, i.e. the domain level. That’s not always the case.

We could, alternatively, opt for the other method: targeting claims provider selection at the Relying Party Trust level. Again, this is  useful functionality. Here’s an example.

Set-AdfsRelyingPartyTrust -TargetName “BodgeIT Inventory ” -ClaimsProviderName @(“crankynuts.nl”)

This makes the “BodgeIT Inventory” Relying Party/Web Application, available to users of the Cranky Nuts organization, bypassing the local AD claims provider.  Should we need to extend access to additional claims providers, such as our local Active Directory, then we can add that issuer to the mix. The downside of this option, is that we’re forced into making a home-realm discovery selection during logon.

The Suffix and RP-specific claims provider options, therefore, do have some limitations.  Indeed, for the scenario that we were faced with, neither option fit.  In  our situation,  two claims providers existed for a single organization,  with each CP containing the same set of users. The use case?  Two-factor authentication.  The upstream claims provider (CP) provides two-factor authentication (2FA) for users connecting from the outside , while the incumbent local AD claims provider covers local Windows logon.

Of course, two claims providers means Home Realm Discovery (HRD) and HRD can be confusing.  We can remedy this for internal users, ensuring they don’t get the HRD prompt by defaulting to the use of the local AD claims provider via Powershell:

Set-ADFSProperties –IntranetUseLocalClaimsProvider $True

This doesn’t solve the problem for access from the outside. Moreover, we expressly wish to send all connecting users to our 2FA claims provider, rather than to the in-build AD claims provider…. We could use auxiliary authentication provided by the MFA Adapter in AD FS 2012 R2, thereby eliminating the use of the upstream claims provider. However, that might not be feasible as:

  1. Leading with the AD password as the primary authentication credential  may not be allowed.
  2. The vendor has an MFA adapter for AD FS 2012 R2.

Even where the latter is available, the (security) policy prerogative might be that use of  1) is not allowed, thereby overriding (2).

<PLUG>To demonstrate issue, cue favorite authentication platform PointSharp (</PLUG>

PointSharp possess both a Security Token Service (STS) that can stip atop AD FS as a 2FA claims provider role and also have an MFA adapter for AD FS 2012 R2 / 2016. Since use of the MFA adapter has been prohibited by the customer according to the rules above (not wanting to lead with AD password as a primary authentication credential), the STS as a Claims Provider was selected instead.

You’ll recall we turned off HRD for internal users by setting the IntranetUseLocalClaimsProvider setting to TRUE. With the PointSharp STS configured as a claims provider, external users will get continue to get the HRD screen as AD FS cannot determine where the user lives without the appropriate “hint”.  In AD FS 2.0 it was possible to workaround this by customizing the AD FS 2.0 proxy configuration, modifying the Page_Init section of the homerealmdiscovery.aspx.cs file.  We could then remove Active Directory as a claims provider (0)

PassiveIdentityProvidersDropDownList.Items.RemoveAt(0);

Once that was done, default realm selection would fall to our other claims provider (STS)

SelectHomeRealm ( PassiveIdentityProvidersDropDownList.SelectedItem.Value );

As you are no doubt aware, IIS has been supplanted in AD FS 2012 R2 with everything running in kernel-mode. Thankfully, all is not lost though. Some of the functionality previously possible under IIS has moved to Javascript and customization of the onload.js script is covered in a couple of scenarios here..

Variables previously living in .NET code-behind are visible in the View Source of the web page of the HRD screens. Options for both claims providers are visible.

….HRD.selection(‘http://adfs.mydomain.com/adfs/services/trust&#8217;);” onclick=”HRD.selection(‘http://adfs.mydomain.com/adfs/services/trust’); …….
….HRD.selection(‘
https://sts.mydomain.com/login/&#8217;);” onclick=”HRD.selection(‘https://sts.mydomain.com/login/’); …….

HRD.selection is the main feature of interest. There’s an action on clicking the realm manually that specifies the HRD we require. We can automate this by moving the selection to the onload.js script, thereby automating selection of the PointSharp Claims Provider. First, we need to customize our AD FS setup.

We create a new theme called PointSharp based on the default AD FS theme

New-AdfsWebTheme –Name PointSharp –SourceName default

Export the default theme to allow our customization

Export-AdfsWebTheme –Name default –DirectoryPath c:\scripts

Copy the default onload.js to the C:\Scripts folder and edit it. At the end of the script, we simply add the reference to the PointSharp claims provider using the following syntax (replace with your own CP) :

HRD.selection(‘https://sts.mydomain.com/login/’);

We then import the new PointSharp theme including the modified onload.js.

Set-AdfsWebTheme -TargetName PointSharp -AdditionalFileResource @{Uri=’/adfs/portal/script/onload.js’;path=”c:\scripts\onload.js”}

Activate the new theme.

Set-AdfsWebConfig -ActiveThemeName PointSharp

External users will be now routed to the PointSharp claims provider for login, whilst AD logon for internal users is still preserved. Please note that this is a GLOBAL change affecting all users of the AD FS farm and test extensively as it might not be your cup of tea…

Claims-based access with AD FS 2.0 and PointSharp Identity Federation

In previous articles we’ve looked at inter-op scenarios with AD FS using gateway solutions such as Juniper SA, Microsoft Forefront UAG 2010 and access management platforms such as OpenAM.  In this post,  we’ll look at using AD FS 2.x with a Windows Identity Federation (WIF)-based Security Token Service (STS) from PointSharp (www.pointsharp.com). This provides us with a broader authentication platform than AD FS from which to make access control decisions.

In a default configuration, AD FS 2.0 makes use of the local Active Directory as an authentication service. As administrators, we may also wish to further extend authentication options available to AD FS.  A number of mechanisms are available, allowing us to hook into third-party authentication services.

  1. via plug-ins/agents exposed through IIS, either on the AD FS Proxy/Farm to connect to other authentication providers;
  2. customization/ coding sign-in pages to connect directly to authentication providers via web services  or other custom methods;
  3. through a federation trust to another provider, e.g. an IP-STS/IdP. 

Option 1 is the traditional access management method, using non-federated agents/filters to wrap around IIS. This approach is often independent of AD FS. Option 2 involves customizing the logon process within AD FS, e.g. customizing forms-sign-in pages to hook into back-end web services APIs that the third-party authentication service may provide.  Option 3 is the claims provider route using the federation trust model. PointSharp cater for all three solutions. However, I’ll concentrate on Option 3, using their Security Token service (STS) as a strong/two-factor authentication provider .

To highlight a working scenario, let’s set out some basic requirements:

  • External users, including corporate users, must connect through the third-party STS using  various authentication types, according to the desired requirements:
    • Two-factor authentication (hardware token, soft token or SMS)
    • An alternate password credential store (non-AD)
    • Credentials from the Corporate directory (e.g. AD)
  • Internal users, connected to the corporate LAN, should be able to connect to relying parties using their Windows logon credentials (Kerberos/NTLM).
  • Applications must support SAML or WS-Federation in an external facing scenario and IWA (Kerberos/NTLM) for internal users.
  • The solution should support claims-based access control to the federated web application according to the desired authentication method

The PointSharp Identity Federation component (STS) is a .NET / Windows Identity Federation (WIF) application. It services authentication requests by connecting to a core-access management application via web services.

image

In logon flow terms, an abridged view of the process is:

  1. The external User connects to Relying Party Web Application
  2. Browser redirect to AD FS Proxy. AD FS local authentication types are disabled. A claims provider  is defined and the authentication request is passed to this.
  3. Browser redirect to PointSharp Identity Federation STS. User logs on. Policy-based access control and claims processing is performed. SAML token is issued.
  4. Browser redirect to AD FS (RP-STS). Perform claims processing on Claims Provider and Relying Party.
  5. Browser redirect to Relying Party for authorization and access to application.

Users connect to  the PointSharp Identity Federation claims provider (configured) via AD FS, to provide two-factor authentication for external access scenarios.  In order to bypass the (in-built) AD claims provider for AD FS external access, whilst continuing to provide a Windows SSO experience to corporate users, we make a  couple of configuration changes in AD FS proxy and farm nodes:

  • Disable all local authentication types on the AD FS Proxy to pass authentication requests to the PointSharp STS. This is done to bypass home realm discovery (HRD) mechanisms and remove the proxy as an authentication layer. We do this by removing the forms, basic and X509 authentication types within the web.config of the AD FS Proxy in the microsoft.identityServer.web section:

  <localAuthenticationTypes>
  </localAuthenticationTypes>

  • On the local AD FS farm we adjust settings to ensure that the default Active Directory claims provider, not the PointSharp claims provider, is used for authentication of users connecting via the internal/corporate network.  We do so by customizing the homerealmdiscovery.aspx.cs on the AD FS farm to ensure that the AD claims provider is used for Windows logon. Refer to this blog article on how to accomplish this.

With the above changes, all logon requests via the AD FS proxy will now be handled by the PointSharp STS.

Before continuing further, let’s look at how the PointSharp Identity Federation component (STS) and the backend PointSharp authentication services work to support desired authentication types.  To accomplish this, we’ll need to dig a little deeper into how identities are stored/used within the configuration.

Configuration Storage

As with the majority of Access Management (AM) solutions out there, it’s worthwhile pointing out the distinction between a store used for identity (read-only) lookup purposes, such as a user repository,  versus the store the AM solution uses for holding (writing) configuration options concerning user/profile/preferences. Typically, configuration or data storage is represented in a single aggregate store where information about access identities is written. Conversely, user storage(s), may consist of multiple repositories, which we read user information from.  PointSharp uses an LDAP store, e.g. AD LDS, AD or other LDAP v3 compliant servers for configuration/data storage. The store retains information concerning the users profile, the authentication methods used/supported, additional secrets etc. Sensitive information within the store is encrypted or (optionally) the entire storage container itself.

User Storage

In PointSharp lexicon, user storage is used to define an entry point within a repository for basing scoped searches/extractions from. We can then subsequently target items extracted for authentication/authorization processing. User storage may be one or many directories (AD/LDAP) or specific containers (organizational units) within one or many directories.  Optionally, we may then target a desired authentication method against defined user storage types.

image

With a given user storage, via scoping options and the use of an LDAP filter , we define objects of “interest” in the storage and, at an attribute level, define various attributes, e.g. logon ID, to be used. This could be a security principal such as  sAMAccountName, userPrincipalName or uid, subject to the object class. In the above screenshot, a User Storage called “inetOrgPerson” has been created,  and within this store (AD),  searches have been limited to include object classes of the inetOrgPerson type from given OUs. The (LDAP) search filter in the chosen user storage is:

(&({usernameAttribute}={username})(objectClass=inetOrgPerson)(objectCategory=person))

There’s some latitude here on what we may wish to include/exclude as objects of interest, for logon purposes, abstracted from the logon process normally associated to the native directory. For example, disabled accounts, which might sound bizarre, can also be exposed via user storage. Attributes such as UserAccountControl are available to expose/include in a scoped search within user storage, thereby allowing subsets of users for remote access,  not normally available in a local authentication context to be used. We may wish to make these available purely for external access. In practical terms, imagine that we have a subset of users that we don’t want to be able to interactively logon to AD, from a domain-joined PC, yet should be able to logon externally (only) via our Identity Federation STS. Here’s an example of an LDAP scope that targets disabled users to be defined at a storage level. 

(&(objectCategory=person)(objectClass=user)(userAccountControl:1.2.840.113556.1.4.803:=2))

User storages are processed iteratively. We can include a number of user storage types according to access needs and once we’ve defined them, identify the types of authentication we wish to use directly (via the storage) or indirectly through access policy.

Authentication Services

image

PointSharp, through back-end authentication services, provide authentication types available directly through listeners via web services or RADIUS, according to the access scenario. Since we’re dealing with identity federation here,  this equates to web services. At this point, we can make available a given authentication type to be used in the identity federation process (e.g. SMS) or elect to use a more fine-grained policy-based authentication process. Smart Authentication (SmartAuth) refers to a policy-based / attribute-based access  workflow executed during logon. Through these policies the authentication type to use for a connecting user is determined. This allows for more granular authentication flows to meet requirements. Moreover, this can also be further refined at the (front-end) Identity Federation component (STS) via claims-based access control.

Using the user storage concepts, let’s have a look at two identity federation scenarios. The first is a “basic” approach using the default Active Directory, available as a user store for moderating external access.

Basic Scenario (Single Storage)

image

In the above setup, we’re “scoping” our storage based around using various OU’s within AD. The first storage uses sAMAccountName for internal users using their Windows logon ID, the second uses userPrincipalName (UPN) for external users. In this example, sAMAccountName is analogous to EmployeeID and userPrincipalName to the emailaddress of the external user. Each respective set of identities live within their own OU’s within Active Directory.

Complex Scenario (Multiple Storage)

image

Similar to the basic setup, we’re also scoping our user storage at OUs within a given store. In this case we’re also adding additional repositories, such as a Partner/Affiliates store (e.g. Extranet), to pull in their identities for usage in logon scenarios ….

With the user storages defined, we then define individual authentication types within the back-end PointSharp authentication service and expose these as individual listeners, invoked directly by the caller. In our case, this is the PointSharp Identity Federatrion component calling a smart authentication rule. to adopt more fine grained authentication decisions at logon.

image

In the above policy, I’ve elected to use membership of a Windows group (in user stores) to target required authentication types.  This involves static management of  a group, so it may be less desirable than using something like a UPN or Email address, matched against a particular suffix to offer a more dynamic evaluation.

image

For example, a dynamic evaluation can be used, as in the above example, to attach an authentication method to users with an @auth360.net UPN suffix to use an OATH token. I’ll cover dynamic evaluation using directed authentication types and responses in a later post.

With PointSharp Identity Federation, we specify the use of a smart authentication rule as the authentication method

image

Users logging on from a relying party externally are  redirected to the PointSharp STS. (Note: I’ve already setup the PointSharp STS up as a claims provider within AD FS).

image

Within the PointSharp authentication service, if you recall from the earlier MemberOf smart rule graphic, we’ve identified four authentication types: OATH, SMS, PointSharp Password and AD Password. OATH tokens are event or time-based OTP schemes using hardware, software and SMS-based logon mechanisms. Both support (optional) challenge/response password/OTP combinations from the user repositories and the login process adapts to this according to the rules defined with the PointSharp authentication service.  In addition, the PointSharp Password is an alternate login credential that can be called upon and is used in cases where customers do not wish to employ two-factor authentication, nor expose the AD password to external access. Instead, they wish to use a separate password source, independent of AD, with separate password/lockout policies, that can be used to provide claims-based access via the PointSharp STS to their web applications. Should we also we wish to make AD password-access available as a possible authentication type, this is also included in the example. Remote lockout conventions can also be applied to AD users, independent of the AD password policy, to ensure that remote access lockout does not necessarily incur a AD password lockout, and to prevent Denial of Service (DoS) lockout on a given user.

Within the PointSharp authentication service admin UI, in a storage called AUTH360, four users have been created for testing:

image

  •  oathman is a user using an OATH token (hardware token / soft token)
  •  smsboy is a user using an SMS authentication method
  •  psidgal is a user using a PointSharp password
  •  adkid is a user using an AD password

From within PointSharp Identity Federation (STS ) we can define claims-based access rules to be passed onto AD FS. To accomplish this, we create custom claims rules on the STS that conform to the authentication type we desire. This is then injected in the SAML token and consumed as a claim by AD FS, as the RP-STS, for further processing, and passed on to the RP. For example, the four authentication types defined within the SmartAuth rule are now processed at the STS :

image

These are passed back via the custom claims definition:

http://schemas.auth360.net/ws/2008/06/identity/claims/access

On AD FS, we create a claims description that conforms to the above description

image

On the PointSharp Identity Federation claims provider, we pass the above claims as well as any additional claims that we also elect to emit.  On the claims provider pipeline in AD FS, we configure Acceptance Transform rules to pass the Access Type claims and any other rules that the Claims Provider STS has made available:

image

On the relying party application we define our issuance transform rules.

image

I’m using SimpleSAMLphp, a SAML 2.0 Service Provider, as my Relying Party. AD FS, as a broker, provides the necessary bridging between the WS-Federation passive STS of PointSharp and, in this case our SAML 2.0 RP. In the “groups” claim we pass an inbound custom customs claims definition that transforms the authentication method http://schemas.auth360.net/ws/2008/06/identity/claims/access and emit this as a  SAML attribute that SimpleSAMLphp can then consume:

c:[Type == http://schemas.auth360.net/ws/2008/06/identity/claims/access] => issue(Type = “groups”, Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType);

I’ve setup up a basic “Hello World” PHP application, which calls the SimpleSAMLphp libraries and then display the processed attributes in the web page. In our example, the access type (and authentication type) is expressed via the groups SAML assertion in array [0] –LOA4-AD. This is a user logging on who is a member of group LOA4-AD (using AD credentials).

Array
(
    [groups] => Array
        (
            [0] => LOA4-AD
            [1] => users
            [2] => members
        )

    [http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn] => Array
        (
            [0] => adkid@auth360.net
        )

)

At the relying party, we’re now at liberty to make authorization decisions based on the incoming claim, according to the strength of the authentication type. I’m using SimpleSAMLphp here as an example, but the same conventions can be applied to other WIF-based RPs/STS such as SharePoint.

In a future post,  I’ll look at more refined policy assessments using access based on dynamic evaluation and SAML authentication contexts such as SAML AuthNContextClassRef and WS-Fed AuthenticationMethod in RP/SP initiated-sign-on scenarios. Meanwhile, I hope you enjoyed the post.