Oauth 2.0 Protocol Extensions for Broker Clients

[MS-OAPXBC]:

OAuth 2.0 Protocol Extensions for Broker Clients

Intellectual Property Rights Notice for Open Specifications Documentation

§  Technical Documentation. Microsoft publishes Open Specifications documentation for protocols, file formats, languages, standards as well as overviews of the interaction among each of these technologies.

§  Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you may make copies of it in order to develop implementations of the technologies described in the Open Specifications and may distribute portions of it in your implementations using these technologies or your documentation as necessary to properly document the implementation. You may also distribute in your implementation, with or without modification, any schema, IDL's, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications.

§  No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.

§  Patents. Microsoft has patents that may cover your implementations of the technologies described in the Open Specifications. Neither this notice nor Microsoft's delivery of the documentation grants any licenses under those or any other Microsoft patents. However, a given Open Specification may be covered by Microsoft Open Specification Promise or the Community Promise. If you would prefer a written license, or if the technologies described in the Open Specifications are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting .

§  Trademarks. The names of companies and products contained in this documentation may be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. For a list of Microsoft trademarks, visit www.microsoft.com/trademarks.

§  Fictitious Names. The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in this documentation are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.

Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than specifically described above, whether by implication, estoppel, or otherwise.

Tools. The Open Specifications do not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments you are free to take advantage of them. Certain Open Specifications are intended for use in conjunction with publicly available standard specifications and network programming art, and assumes that the reader either is familiar with the aforementioned material or has immediate access to it.

Revision Summary

Date / Revision History / Revision Class / Comments /
10/16/2015 / 1.0 / New / Released new document.

Table of Contents

1 Introduction 5

1.1 Glossary 5

1.2 References 6

1.2.1 Normative References 6

1.2.2 Informative References 7

1.3 Overview 7

1.4 Relationship to Other Protocols 7

1.5 Prerequisites/Preconditions 8

1.6 Applicability Statement 8

1.7 Versioning and Capability Negotiation 8

1.8 Vendor-Extensible Fields 8

1.9 Standards Assignments 8

2 Messages 9

2.1 Transport 9

2.2 Common Data Types 9

2.3 Directory Service Schema Elements 9

3 Protocol Details 10

3.1 OAuthBrokerExtension Client Details 10

3.1.1 Abstract Data Model 10

3.1.2 Timers 10

3.1.3 Initialization 10

3.1.4 Higher-Layer Triggered Events 11

3.1.5 Message Processing Events and Sequencing Rules 11

3.1.5.1 Token endpoint (/token) 11

3.1.5.1.1 POST (Request for Nonce) 11

3.1.5.1.1.1 Request Body 11

3.1.5.1.1.2 Response Body 11

3.1.5.1.1.3 Processing Details 11

3.1.5.1.2 POST (Request for Primary Refresh Token) 11

3.1.5.1.2.1 Request Body 12

3.1.5.1.2.2 Response Body 12

3.1.5.1.2.3 Processing Details 12

3.1.5.1.3 POST (Exchange Primary Refresh Token for Access Token) 12

3.1.5.1.3.1 Request Body 12

3.1.5.1.3.2 Response Body 12

3.1.5.1.3.3 Processing Details 12

3.1.6 Timer Events 13

3.1.7 Other Local Events 13

3.2 OAuthBrokerExtension Server Details 13

3.2.1 Abstract Data Model 13

3.2.2 Timers 13

3.2.3 Initialization 13

3.2.4 Higher-Layer Triggered Events 13

3.2.5 Message Processing Events and Sequencing Rules 13

3.2.5.1 Token endpoint (/token) 13

3.2.5.1.1 POST (Request for Nonce) 14

3.2.5.1.1.1 Request Body 14

3.2.5.1.1.2 Response Body 14

3.2.5.1.1.3 Processing Details 14

3.2.5.1.2 POST (Request for Primary Refresh Token) 15

3.2.5.1.2.1 Request Body 15

3.2.5.1.2.1.1 Username Password Authentication 15

3.2.5.1.2.1.2 User JWT Authentication 16

3.2.5.1.2.1.3 Refresh Token Authentication 16

3.2.5.1.2.2 Response Body 16

3.2.5.1.2.3 Processing Details 17

3.2.5.1.3 POST (Exchange Primary Refresh Token for Access Token) 18

3.2.5.1.3.1 Request Body 18

3.2.5.1.3.2 Response Body 19

3.2.5.1.3.3 Processing Details 19

3.2.6 Timer Events 20

3.2.7 Other Local Events 20

4 Protocol Examples 21

4.1 Obtain a Nonce 21

4.2 Obtain a Primary Refresh Token 21

4.3 Obtain an Access Token 22

5 Security 24

5.1 Security Considerations for Implementers 24

5.2 Index of Security Parameters 24

6 Appendix A: Product Behavior 25

7 Change Tracking 26

8 Index 27

1  Introduction

The OAuth 2.0 Protocol Extensions for Broker Clients specify extensions to [RFC6749] (The OAuth 2.0 Authorization Framework) that allow a broker client to obtain access tokens on behalf of calling clients. When no operating system version information is specified, information in this document applies to all relevant versions of Windows. Similarly, when no AD FS behavior level is specified, information in this document applies to all AD FS behavior levels.

In addition to the terms specified in section 1.1, the following terms are used in this document:

From [RFC6749]:

§  access token

§  access token request

§  access token response

§  authorization server

§  client identifier

§  confidential client

§  refresh token

§  resource owner

From [OIDCCore]:

§  ID token

Sections 1.8, 2, and 3 of this specification are normative and can contain the terms MAY, SHOULD, MUST, MUST NOT, and SHOULD NOT as defined in [RFC2119]. Sections 1.5 and 1.9 are also normative but do not contain those terms. All other sections and examples in this specification are informative.

1.1  Glossary

The following terms are specific to this document:

Active Directory: A general-purpose network directory service. Active Directory also refers to the Windows implementation of a directory service. Active Directory stores information about a variety of objects in the network. Importantly, user accounts, computer accounts, groups, and all related credential information used by the Windows implementation of Kerberos are stored in Active Directory. Active Directory is either deployed as Active Directory Domain Services (AD DS) or Active Directory Lightweight Directory Services (AD LDS). [MS-ADTS] describes both forms. For more information, see [MS-AUTHSOD] section 1.1.1.5.2, Lightweight Directory Access Protocol (LDAP) versions 2 and 3, Kerberos, and DNS.

Active Directory Domain Services (AD DS): A directory service (DS) implemented by a domain controller (DC). The DS provides a data store for objects that is distributed across multiple DCs. The DCs interoperate as peers to ensure that a local change to an object replicates correctly across DCs. For more information, see [MS-AUTHSOD] section 1.1.1.5.2 and [MS-ADTS]. For information about product versions, see [MS-ADTS] section 1. See also Active Directory.

Active Directory Federation Services (AD FS): A Microsoft implementation of a federation services provider, which provides a security token service (STS) that can issue security tokens to a caller using various protocols such asWS-Trust, WS-Federation, and Security Assertion Markup Language (SAML) version 2.0.

AD FS behavior level: A specification of the functionality available in an AD FS server. Possible values such as AD_FS_BEHAVIOR_LEVEL_1 and AD_FS_BEHAVIOR_LEVEL_2 are described in [MS-OAPX].

AD FS server: See authorization server in [RFC6749].

JavaScript Object Notation (JSON): A text-based, data interchange format that is used to transmit structured data, typically in Asynchronous JavaScript + XML (AJAX) web applications, as described in [RFC4627]. The JSON format is based on the structure of ECMAScript (Jscript, JavaScript) objects.

JSON Web Token (JWT): A type of token that includes a set of claims encoded as a JSON object. For more information, see [IETFDRAFT-JWT].

relying party (RP): A web application or service that consumes security tokens issued by a security token service (STS).

Uniform Resource Identifier (URI): A string that identifies a resource. The URI is an addressing mechanism defined in Internet Engineering Task Force (IETF) Uniform Resource Identifier (URI): Generic Syntax [RFC3986].

X.509: An ITU-T standard for public key infrastructure subsequently adapted by the IETF, as specified in [RFC3280].

MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as defined in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.

1.2  References

Links to a document in the Microsoft Open Specifications library point to the correct section in the most recently published version of the referenced document. However, because individual documents in the library are not updated at the same time, the section numbers in the documents may not match. You can confirm the correct section numbering by checking the Errata.

1.2.1  Normative References

We conduct frequent surveys of the normative references to assure their continued availability. If you have any issue with finding a normative reference, please contact . We will assist you in finding the relevant information.

[FIPS180-2] National Institute of Standards and Technology, "Secure Hash Standard", FIPS PUB 180-2, August 2002, http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf

[MS-ADA1] Microsoft Corporation, "Active Directory Schema Attributes A-L".

[MS-ADA2] Microsoft Corporation, "Active Directory Schema Attributes M".

[MS-ADSC] Microsoft Corporation, "Active Directory Schema Classes".

[MS-ADTS] Microsoft Corporation, "Active Directory Technical Specification".

[MS-OAPX] Microsoft Corporation, "OAuth 2.0 Protocol Extensions".

[OIDCCore] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and Mortimore, C., "OpenID Connect Core 1.0 incorporating errata set 1", November 2014, http://openid.net/specs/openid-connect-core-1_0.html

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997, http://www.rfc-editor.org/rfc/rfc2119.txt

[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000, http://www.rfc-editor.org/rfc/rfc2818.txt

[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006, http://www.rfc-editor.org/rfc/rfc4648.txt

[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012, http://www.rfc-editor.org/rfc/rfc6749.txt

[RFC7515] Jones, M., Bradley, J., and Sakimura, N., "JSON Web Signature (JWS)", RFC 7515, May 2015, http://www.rfc-editor.org/rfc/rfc7515.txt

[RFC7516] Jones, M., and Hildebrand, J., "JSON Web Encryption (JWE)", RFC 7516, May 2015, http://www.rfc-editor.org/rfc/rfc7516.txt

[SP800-108] National Institute of Standards and Technology., "Special Publication 800-108, Recommendation for Key Derivation Using Pseudorandom Functions", October 2009, http://csrc.nist.gov/publications/nistpubs/800-108/sp800-108.pdf

1.2.2  Informative References

None.

1.3  Overview

Active Directory Federation Services (AD FS) implements parts of the OAuth 2.0 Authorization Framework, as defined in [RFC6749] as well as the extensions described in [MS-OAPX]. In addition to these, AD FS also implements extensions to enable broker clients to retrieve tokens from an authorization server on behalf of other clients. These extensions for broker clients are specified in this document.

Note Throughout this specification, the fictitious names "client.example.com" and "server.example.com" are used as they are used in [RFC6749].

1.4  Relationship to Other Protocols

The OAuth 2.0 Protocol Extensions for Broker Clients (this document) specify extensions to the industry standard OAuth 2.0 Authorization Framework that is defined in [RFC6749] and the extensions described in [MS-OAPX]. These extensions are therefore dependent on the OAuth 2.0 protocol and the extensions in [MS-OAPX] and use HTTPS [RFC2818] as the underlying transport protocol.

Figure 1: Protocol dependency

1.5  Prerequisites/Preconditions

The OAuth 2.0 Protocol Extensions for Broker Clients define extensions to [RFC6749] and [MS-OAPX]. A prerequisite to implementing the OAuth 2.0 Protocol Extensions is that the REQUIRED parts of [RFC6749] have been implemented on the AD FS server.

These extensions also assume that if the OAuth 2.0 client requests authorization for a particular resource, or relying party, secured by the AD FS server, the client knows the identifier of that resource. These extensions also assume that the OAuth 2.0 client knows its own client identifier and all relevant client authentication information if it is a confidential client.

The client runs on a device for which there is a corresponding msDS-Device object in Active Directory with the following additional requirements:

§  The client has access to the private key of a device certificate. The public portion of the device certificate is stored in the altSecurityIdentities attribute of the device's msDS-Device object in Active Directory.

§  The client has access to the private key of a session transport key (STK). The public portion of the STK is stored in the msDS-KeyCredentialLink attribute of the device's msDS-Device object in Active Directory.

1.6  Applicability Statement

The OAuth 2.0 Protocol Extensions for Broker Clients are supported by all AD FS servers that are at an AD FS behavior level of AD_FS_BEHAVIOR_LEVEL_2 or higher. See [MS-OAPX] section 3.2.1.1 for the formal definition of AD FS behavior level.

1.7  Versioning and Capability Negotiation

This document covers versioning issues in the following areas:

Supported Transports: The OAuth 2.0 Protocol Extensions for Broker Clients support only HTTPS [RFC2818] as the transport protocol.

Protocol Versions: The OAuth 2.0 Protocol Extensions for Broker Clients do not define protocol versions.

Localization: The OAuth 2.0 Protocol Extensions for Broker Clients do not return localized strings.

Capability Negotiation: The OAuth 2.0 Protocol Extensions for Broker Clients do not support capability negotiation.

1.8  Vendor-Extensible Fields

None.

1.9  Standards Assignments

None.

2  Messages

2.1  Transport

The HTTPS protocol [RFC2818] MUST be used as the transport.

2.2  Common Data Types

None.

2.3  Directory Service Schema Elements

This protocol accesses the Directory Service schema classes and attributes that are listed in the following table(s).

For the syntax of <Class> or <Class<Attribute> pairs, refer to one of the following:

§  Active Directory Domain Services (AD DS) [MS-ADA1] [MS-ADA2] [MS-ADSC]

Class / Attribute /
msDS-Device / altSecurityIdentities
msDS-KeyCredentialLink
user / msDS-KeyCredentialLink

3  Protocol Details

3.1  OAuthBrokerExtension Client Details

The client role<1> of the OAuth 2.0 Protocol Extensions for Broker Clients is the initiator of requests for access tokens on behalf of other clients. The client role also stores data that is important to these requests such as a nonce and the primary refresh token.