JWT support across federation protocols

The following table illustrates the support in ADFS for issuing JWTs for each of the authorization protocols supported by it.

In a nutshell, JWTs are the only supported token type for OAuth requests. We proceeded to extend support for JWTs to WS-Fed and WS-Trust as well. In both these protocols, there’s either configuration required on ADFS (for WS-Fed) or JWTs need to be requested explicitly (for WS-Trust). Subsequent sections describe this in further detail.

JWT support for OAuth requests

The OAuth server implementation in ADFS on Windows Server 2012 R2 will issue only JWTs in response to OAuth authorization requests. This applies to both access tokens as well as refresh tokens issued by ADFS in response to an OAuth authorization grant request. There is no way to turn off this behavior in ADFS.

JWT support for WS-Fed requests

By default, ADFS continues to issue SAML tokens in response to WS-Fed requests. However, you can configure ADFS to issue JWTs in response to WS-Fed requests. This configuration is done via PowerShell and is on a per-relying party basis. In other words, you can configure ADFS to issue JWT access tokens to specific applications/relying parties in ADFS.

This is done by using the following PowerShell command.

Once you set this, all access tokens issued by ADFS in response to WS-Fed requests for authorization to access this relying party/application will be JWTs.

JWT Support for WS-Trust requests

You can request JWTs from ADFS in response to WS-Trust requests. This is done by crafting an RST that explicitly demands JWTs from ADFS. This is done by setting the TokenType for the RST to the value “urn:ietf:params:auth:token-type:jwt”.

A code snippet that illustrates how to request JSON Web Tokens (JWTs) from ADFS is below:

Note that the token response in the RSTR returned by ADFS is the Base64 encoding of the JWT. The JWT itself consists of three parts – header, body and signature separated by a “.” (i.e. a period character). You can get hold of the JWT by base64 decoding the payload that is contained within the InnerXML of the security token response to the WS-Trust call.

What does a JWT issued by ADFS look like?

The following snippet illustrates a JSON Web Token issued by ADFS. This access token contains a bunch of claims that were asserted by ADFS after successfully authenticating and authorizing the user to access the relying party.

JWTs issued by ADFS on Windows Server 2012 R2 are signed using ADFS’ issuing certificate. ADFS does not support JWT encryption.

If you’ve seen SAML tokens issued by ADFS in the past, you’ll notice the shorter claim names that enable the token to be represented more compactly. These short claim names are registered with ADFS – to see the short name that corresponds to a claim, use the Get-ADFSClaimDescription PowerShell cmdlet. You can also register your custom claim descriptions and corresponding short names to be used with JWTs using the Add-AdfsClaimDescription PowerShell Cmdlet.

Working with JWTs - JSON Web Token Handler for .Net

You can use the JSON Web Token Handler for .Net to parse and validate JSON Web Tokens. The JSON Web Token Handler extension for Windows Identity Foundation enables you to create and validate JSON Web Tokens (JWT) in your applications. The JWT Token Handler can be configured to run in the WIF pipeline like other built-in security token handlers, but it can also be used independently to perform token validation in lightweight applications. 

The JWT Handler is available for download as a NUGET package at: https://www.nuget.org/packages/System.IdentityModel.Tokens.Jwt/ 

Documentation for the JWT handler is available on MSDN at https://msdn.microsoft.com/en-us/library/dn205065(v=vs.110).aspx 

That’s all for this post. Thanks for reading!

-----------------------

Mahesh Unnikrishnan

OAuth 2.0 is an open standard created by the IETF for authorization and is documented by RFC 6749. The OAuth 2.0 authorization framework is widely implemented across the industry.

Supported authorization grants

Supported client types

Since ADFS on Windows Server 2012 R2 does not support confidential clients, it does not implement any client authentication method described in RFC 6749. Additionally, the ADFS server does not support the use of unregistered clients – clients that are not registered with ADFS will not be issued access tokens. 

Supported token types with OAuth 2.0

ADFS issues access tokens and refresh tokens in the JWT (JSON Web Token) format in response to successful authorization requests using the OAuth 2.0 protocol. JWTs are much easier to work with than SAML tokens and can be easily manipulated in a wide variety of programming languages. Note that ADFS does not issue SAML tokens over the OAuth 2.0 authorization protocol.

Access Tokens: ADFS issues short-lived access tokens whose lifetime is governed by the per-Relying Party Trust setting called TokenLifetime. This defaults to 1 hour and can be configured by administrators to issue longer-lived access tokens. In line with industry-wide security recommendations, we encourage the use of short-lived access tokens.

Refresh Tokens: ADFS issues refresh tokens in response to the authorization code grant. The refresh token lifetime is longer for workplace joined devices (i.e. up to 7 days) and is comparatively short-lived for unregistered devices (i.e. up to 24 hours). This experience is consistent with persistent SSO lifetime semantics on ADFS. Refresh tokens are encrypted and not meant for the consumption of clients.

Registering OAuth 2.0 clients with ADFS

You can register clients with ADFS and manage them using PowerShell cmdlets. The following cmdlets can be used to do so:

• Add-AdfsClient – Registers an OAuth 2.0 client with ADFS.
• Get-AdfsClient - Retrieves registration information for an OAuth 2.0 client.
• Set-AdfsClient - Modifies registration settings for an OAuth 2.0 client registered with AD FS.
• Enable-AdfsClient - Enables the use of an OAuth 2.0 client registration by AD FS.
• Disable-AdfsClient - Disables an OAuth 2.0 client that is currently registered with AD FS.

ADFS enables you to register multiple redirect URIs for a single client. Dynamic client registration is not supported and clients must be registered statically using PowerShell cmdlets. This provides IT administrators greater degree of control over the client applications that are registered on their ADFS server. 

Microsoft’s extensions to RFC 6749

In order to better support enterprise authorization scenarios, we have included a few extensions to the core OAuth 2.0 RFC. These are documented in the MS-OAPX (OAuth 2.0 Protocol Extensions) document available on MSDN.

That’s it for now! I’ll cover OAuth configuration with a sample application in a subsequent blog post.

-----------------------

Mahesh Unnikrishnan

Grab some coffee and settle down for a long read - as you can likely see, we’ve been busy.

Enable users to work from anywhere on devices of their choice (BYOD)

AD Workplace Join

ADFS incudes a device registration service (DRS) that enables users to join their personally-owned BYO devices to the workplace. This self-service act makes the device known to the organization (i.e. a corresponding device object is recorded in AD). A certificate representing this trust is installed on the device. Thereafter, ADFS is able to authenticate the device when it is used to access corporate resources. Device authentication provides a seamless second factor of authentication and enables IT to make corporate resources (SharePoint portals etc.) available to users from their BYO devices.

Workplace Join forms the foundation of our devices story and you’ll hear a lot more about it. It offers the following benefits:

• Improved Single-sign on – users get longer-lived and persistent sessions on workplace joined devices. In other words, fewer password prompts.
• Seamless MFA – device authentication provides a seamless second factor of authentication for improved security. Seamless in that end-users don’t notice it and it is handled silently by the device platform.
• Conditional access control – IT administrators can secure corporate resources so they may be accessed only from known devices (i.e. workplace joined devices).
• Improved audits in ADFS – audit messages in ADFS include device information for better forensics.

More information – Workplace Join.

Web Application Proxy

The Web Application Proxy (WAP), a new role service under the ‘Remote Access’ role in Windows Server 2012 R2 provides an easy way to publish web applications for use outside the corporate network. Think of the WAP as a combination of the ADFS Proxy and an HTTP reverse proxy, deeply integrated with ADFS. The WAP allows you to publish applications secured by ADFS (i.e. relying parties of ADFS) to the extranet. The WAP integrates with your ADFS server (via the ADFS proxy) in order to ensure that extranet access is pre-authenticated at the edge. Users in your organization can now access SharePoint sites or browser-based applications from outside the corporate network with pre-authentication at the edge of your network. All access is subject to the access control policies you configure on your ADFS server.

More information – Web Application Proxy.

Change AD passwords from the extranet

ADFS now supports the ability to change the password for your AD user account. A password change page hosted by the ADFS server can be published (including from the extranet) for end-users to change their passwords. Additionally, if a user’s password has expired and they try to sign in to an application secured by ADFS, they will automatically be taken to the change password page. The user may then change their password and login using the new credentials to access the application.

Enable IT administrators to manage risk to corporate resources

Built-in support for multi-factor authentication (MFA)

With previous versions of ADFS, there was no built-in support for multi-factor authentication. Some customers have reported stringing together solutions that heavily customized their ADFS setup and used third party solutions for additional authentication. With this release, we provide built-in support for multiple factor authentication. ADFS ships with a built-in multi-factor authentication method – i.e. Smartcard authentication.

Support for Azure MFA and 3rd party MFA providers

Additionally it is also possible to use pluggable MFA providers with ADFS. A popular choice is Azure Multi-Factor Authentication, which provides a wide range of multiple factor authentication methods. Alternately, a list of third party MFA providers that are compatible with ADFS is available on TechNet. If you’re so inclined, you may also use our SDK to build your own custom authentication method that can plug in to ADFS. 

Flexible authentication policies

IT Admins now have greater control over how users are authenticated by ADFS. This is possible by configuring a global authentication policy on the ADFS server that specifies which authentication methods should be used for intranet or extranet authentication. When more than one authentication method is enabled in policy, end-users are presented with a choice on their login page. Additionally, you have the ability to force fresh authentication for sensitive applications (for example, a payroll or HR app) where the user must authenticate afresh every time they try to access the application (i.e. no SSO).

Conditional access control

IT administrators can create policies (claim rules) that are a combination of conditions. These policies then govern access to a specific application. For instance you can choose to allow access to an application only if a user belonging to a specific group performed MFA and used a workplace joined device. Such flexible conditional access control policies can be created in ADFS and used to govern access to secured applications. With the addition of device authentication, MFA and network location awareness in ADFS you now have a rich toolkit that can be used to secure applications.

More information.

Global SSO revocation

IT administrators have the ability to revoke SSO that was issued in the past in order to deal with ‘breach’ events. This ensures that users are forced to re-authenticate and prior SSO is ignored by ADFS.

Extranet soft-lockout protection

With an increasing trend to access corporate resources from the extranet, there is a risk of locking out AD accounts using password brute-force attacks. ADFS now includes the ability to configure extranet soft-lockout protection for your AD accounts. This means that authentication from the extranet will be blocked for a configurable observation window, if a configured number of bad password attempts were made. This protects the AD account from being locked out (i.e. intranet access continues to work) and provides protection against password attacks from the extranet.

More information – extranet soft lockout protection.

Lost device protection

If workplace joined devices are lost or stolen, administrators now have the ability to disable or delete the corresponding device object in the directory. This ensures that ADFS revokes existing SSO for that device and protects against the misuse of lost devices in order to access sensitive corporate resources.

Enable IT administrators to deploy ADFS more easily

The Windows Server 2012 R2 release marked the first time ADFS was included as an in-box Windows Server component. We’ve invested significantly to ensure that the deployment experience with ADFS is streamlined and simple for IT administrators. More information on deploying ADFS is available in the ADFS deployment guide.

No more IIS, deploy on domain controllers

Older versions of ADFS were built on IIS and relied on it for their passive protocol authentication requirements (eg. SAML-P, WS-Fed). With this release, ADFS is built directly atop the Windows HTTP stack. This results in improved performance as well as the ability to deploy ADFS on domain controllers.

Fully integrated with Server Manager

ADFS now supports full UI deployment using Server Manager, including the ability to remotely deploy ADFS on a server.

Pre-requisite checks

The ADFS setup experience now performs pre-requisite checks prior to setting up the role. This ensures that most common environment related errors are detected prior to install. These pre-requisite checks are available in both PowerShell as well as UI-based deployment experiences.

Group Managed Service Account (GMSA) support

First introduced in Windows Server 2012, GMSA provides the ability for a multi-node service (such as ADFS) to use a common service account that doesn’t require admin intervention for password changes. This ensures no downtime associated with changing passwords for service accounts.

Improved SQL database support

You can configure ADFS to use a SQL database using the UI wizard, thus greatly simplifying that deployment experience. ADFS now supports SQL merge replication deployments for improved geo-redundant farm deployments. You can now configure SQL clusters in different data centers to replicate the ADFS configuration database using SQL merge replication. ADFS can be deployed across these different data centers with each ADFS farm node targeting its nearest SQL node, thus providing lower latencies and an improved experience in geo-distributed deployments.

More information – SQL database support.

Deliver a more pleasant sign-in experience

Modern, responsive sign-in pages

The ADFS sign-in pages sport a modern look and feel consistent with that of Azure AD (seen when you sign in to Office 365). The Home Realm Discovery page sports a cleaner tiled design. When signing in to ADFS as part of a federated authentication (i.e. redirected to ADFS from Azure AD), you’ll notice the username field is automatically pre-filled for end-users. In this modern world of devices with varying form-factors, the sign-in pages automatically adjust to the available real estate by virtue of employing a responsive design.

Automatic fallback to forms authentication on WIA incapable browsers

ADFS authentication within the intranet defaults to Windows Integrated Authentication (WIA) to deliver a seamless experience. However, if you’re using a browser that is capable only of NTLM style authentication, you end up seeing a jarring credential UI prompt. ADFS detects browsers that are incapable of WIA and will automatically fall back to using forms authentication to deliver a cleaner and more streamlined user experience. The list of user agents that are not WIA capable can be configured by IT administrators.

More information – forms authentication fallback.

Simple, intuitive customization experiences

Customizing older versions of ADFS required one to be a web developer. The new version of ADFS enables simpler customization using PowerShell. This makes it much easier for IT administrators to perform the following types of customization:

• Set a company logo and illustration image for the login page.
• Customize URLs for IT support, home page, privacy link etc.
• Customize a page description message
• Customize the web theme of the sign-in pages  including modifying CSS.
• Customize the error page displayed to end-user (eg. access denied pages).
• Setup a one-click error reporting email address

More information – customizing ADFS sign-in pages.

Improved Home Realm Discovery (HRD) experiences

Some customers have setup their ADFS server to federate with multiple claims providers. In previous versions of ADFS, you would see a drop down box that listed all such claims providers. This made it hard to avoid disclosing organizational relationships via the sign-in page. The following HRD improvements provide a better user experience on Windows Server 2012 R2:

• HRD using organizational suffix – ADFS enables IT administrators to configure the organizational suffixes (eg. @us.contoso.com, @eu.contoso.com) supported by a claims provider. ADFS then automatically selects the right claims provider based on the UPN entered by the user in the sign-in page (eg. ‘bob@us.contoso.com’)
• HRD filtering on a per-Relying Party basis – IT administrators can configure the claims providers that should be available for a given relying party. This removes clutter from the sign-in page and helps end users pick the right claims provider to sign-in at.
• Bypass HRD for intranet access – Most organizations only support AD within their local intranet. This functionality provides a simple way for the admin to configure ADFS such that all intranet access defaults to the local AD claims provider for authentication.

Enable the development of modern applications

With the increased proliferation of devices, we’re seeing an increased trend towards building modern enterprise applications targeted at devices. These applications usually leverage a REST-based service/Web API that is accessed from a native application on the device. Increasingly, these applications are build on the foundation of open standards such as OAuth.

OAuth 2.0 support

To support the development of these modern applications, ADFS includes support for the OAuth 2.0 authorization code grant flow as described in RFC 6749. ADFS issues access token using the JWT bearer profile. These tokens are essentially JSON objects that are easy to work with in a wide variety of programming languages. Additionally, ADFS also issues refresh tokens to workplace joined devices, which enables longer lived sessions (i.e. fewer password prompts) for end-users.

The Active Directory Authentication Library (ADAL) can be used in order to write client-side applications that request access tokens from ADFS. This library is available on a wide range of platforms and makes it really easy to work with ADFS. Additionally for resource side token validation, the JSON Web Token Handler extension is available.

That’s it for now! If you got this far, treat yourself to a cookie – hope you found something useful. Subsequent posts will have more information on these features.

-----------------------

Mahesh Unnikrishnan