[MS-UPSCWS]: User Profile Service Application Caching Web ...... · The User Profile Service Application Caching Web Service Protocol enables a protocol client to retrieve user information
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
[MS-UPSCWS]: User Profile Service Application Caching Web Service Protocol
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 [email protected].
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, email 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.
3.1.5 Timer Events ................................................................................................. 27 3.1.6 Other Local Events ......................................................................................... 27
4 Protocol Examples .................................................................................................. 28 4.1 Retrieving a User Profile by NT Name ..................................................................... 28 4.2 Retrieving Multiple User Profiles by Record Identifier ................................................ 29
5 Security .................................................................................................................. 32 5.1 Security Considerations for Implementers ............................................................... 32 5.2 Index of Security Parameters ................................................................................ 32
6 Appendix A: Full WSDL ........................................................................................... 33
The User Profile Service Application Caching Web Service Protocol enables a protocol client to retrieve user information from a database that stores user profile data for a site.
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 defined in [MS-OFCGLOS]:
application server authentication back-end database server
base64 encoding colleague
email address endpoint GUID Hypertext Transfer Protocol (HTTP) Hypertext Transfer Protocol over Secure Sockets Layer (HTTPS) login name
SOAP fault detail stream Transmission Control Protocol (TCP) Unicode Uniform Resource Identifier (URI) user profile User Profile Service
user profile store Web Services Description Language (WSDL) WSDL message WSDL operation XML namespace XML namespace prefix
XML schema
The following terms are specific to this document:
user profile record identifier: An integer that uniquely identifies a user profile record.
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.
References to Microsoft Open Specification documents do not include a publishing year because links are to the latest version of the documents, which are updated frequently. References to other
documents include a publishing year when one is available.
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 [email protected]. We will assist you in finding the relevant information.
[MS-SPSTWS] Microsoft Corporation, "SharePoint Security Token Service Web Service Protocol".
[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
[RFC2616] Fielding, R., Gettys, J., Mogul, J., et al., "Hypertext Transfer Protocol -- HTTP/1.1", RFC
2616, June 1999, http://www.rfc-editor.org/rfc/rfc2616.txt
[SOAP1.1] Box, D., Ehnebuske, D., Kakivaya, G., et al., "Simple Object Access Protocol (SOAP) 1.1", May 2000, http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
[SOAP1.2/1] Gudgin, M., Hadley, M., Mendelsohn, N., Moreau, J., and Nielsen, H.F., "SOAP Version 1.2 Part 1: Messaging Framework", W3C Recommendation, June 2003, http://www.w3.org/TR/2003/REC-soap12-part1-20030624
[WSDL] Christensen, E., Curbera, F., Meredith, G., and Weerawarana, S., "Web Services Description Language (WSDL) 1.1", W3C Note, March 2001, http://www.w3.org/TR/2001/NOTE-wsdl-20010315
[XMLNS] Bray, T., Hollander, D., Layman, A., et al., Eds., "Namespaces in XML 1.0 (Third Edition)", W3C Recommendation, December 2009, http://www.w3.org/TR/2009/REC-xml-names-20091208/
[XMLSCHEMA] World Wide Web Consortium, "XML Schema", September 2005,
http://www.w3.org/2001/XMLSchema
[XMLSCHEMA1] Thompson, H., Beech, D., Maloney, M., and Mendelsohn, N., Eds., "XML Schema Part 1: Structures", W3C Recommendation, May 2001, http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/
[XMLSCHEMA2] Biron, P.V., Ed. and Malhotra, A., Ed., "XML Schema Part 2: Datatypes", W3C Recommendation, May 2001, http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/
1.2.2 Informative References
[MS-OFCGLOS] Microsoft Corporation, "Microsoft Office Master Glossary".
[MS-SPTWS] Microsoft Corporation, "Service Platform Topology Web Service Protocol".
This protocol allows protocol clients to gain access to user profile information through a middle-tier application server, instead of a back-end database server. A typical scenario is a protocol client
fetching user profile properties, such as the name, email address, picture URL, or colleagues of one or more users, by using user credentials, such as an user name or security identifier (SID), or another field, such as the user profile record identifier, that identify those users. The middle-tier application server caches user profile fields that are commonly used and exposes them to protocol clients through this protocol. Consequently, this protocol helps distribute the load from the database tier to the application tier; it helps the protocol server scale to handle higher loads because read requests for commonly used fields are the operations performed most frequently. In
addition, this protocol is designed for bulk operations. Protocol clients can use this protocol to gain access to user profile information for many users simultaneously, and the corresponding response can contain data for as many users as requested. This feature optimizes the efficiency of operations for a large user base.
1.4 Relationship to Other Protocols
This protocol uses the Simple Object Access Protocol (SOAP) message protocol for formatting request and response messages, as described in [SOAP1.1], [SOAP1.2/1] and [SOAP1.2/2]. It transmits those messages by using Hypertext Transfer Protocol (HTTP), as described in [RFC2616].
The User Profile Service Application Caching Web Service Protocol uses SOAP over HTTP(S) as shown in the following layering diagram.
Figure 1: This protocol in relation to other protocols
1.5 Prerequisites/Preconditions
This protocol operates against a protocol server that exposes one or more endpoint (4) URIs that are known by protocol clients. Both the protocol server endpoint (4) URI and transport are either known by the protocol client or are obtained by using the discovery mechanism described in [MS-SPTWS].
The protocol client can obtain the ApplicationClassId and ApplicationVersion of the protocol server with which it communicates. The endpoint (4) URI of a protocol server is required to provide
the discovery mechanism described in [MS-SPTWS].
This protocol requires the protocol client to have the necessary permission settings to call methods on the protocol server. The protocol also requires that the protocol client implements the token-based security needed for the protocol server and the security protocols described in [MS-SPSTWS].
This protocol is designed to retrieve user profile data for multiple users in one call. The number of users for which that data is retrieved is limited only by the configuration of the transport layer.
1.7 Versioning and Capability Negotiation
Supported Transports: This protocol can be implemented by using transports that support sending SOAP messages, as described in section 2.1.
In the following sections, the schema definition might differ from the processing rules imposed by the protocol. The WSDL in this specification matches the WSDL that shipped with the product and provides a base description of the schema. The text that introduces the WSDL might specify differences that reflect actual Microsoft product behavior. For example, the schema definition might allow for an element to be empty, null, or not present but the behavior of the protocol as specified restricts the same elements to being non-empty, not null, and present.
2.1 Transport
Protocol servers MUST support Simple Object Access Protocol (SOAP) over Hypertext Transfer Protocol (HTTP), Hypertext Transfer Protocol over Secure Sockets Layer (HTTPS), or TCP.
All protocol messages MUST be transported by using HTTP or TCP bindings at the transport level.
Protocol messages MUST be formatted as specified in either [SOAP1.1] section 4 or [SOAP1.2/1]
section 5. Protocol server faults MUST be returned by using HTTP status codes, as specified in [RFC2616] section 10, or SOAP faults, as specified in [SOAP1.1] section 4.4 or [SOAP1.2/1]
section 5.4.
If the HTTPS transport is used, a server certificate MUST be deployed.
This protocol MAY transmit an additional SOAP header, the ServiceContext header, as specified in [MS-SPSTWS].
This protocol does not define any means for activating a protocol server or protocol client. The protocol server MUST be configured and begin listening in an implementation-specific way. In
addition, the protocol client MUST know the format and transport that is used by the server, for example, the SOAP format over an HTTP transport.
2.2 Common Message Syntax
This section contains common definitions that are used by this protocol. The syntax of the definitions uses XML schema, as specified in [XMLSCHEMA1] and [XMLSCHEMA2], and WSDL, as specified in [WSDL].
2.2.1 Namespaces
This specification defines and references various XML namespaces using the mechanisms specified in [XMLNS]. Although this specification associates a specific XML namespace prefix for each XML namespace that is used, the choice of any particular XML namespace prefix is implementation-specific and not significant for interoperability.
This specification does not define any common WSDL message definitions.
2.2.3 Elements
This specification does not define any common XML schema element definitions.
2.2.4 Complex Types
The following table summarizes the set of common XML schema complex type definitions defined by this specification. XML schema complex type definitions that are specific to a particular operation are
described with the operation.
Complex type Description
ArrayOfUserData ArrayOfUserData is a sequence of zero or more UserData complex types.
ConfigurationFault The ConfigurationFault complex type describes errors that occur because of configuration failures either at the service endpoint (4) of this protocol or in transport layers. It is an extension of the UserProfileFault complex type.
InputFault The InputFault complex type describes errors that occur because of invalid UserSearchCriteria input from a protocol client. The InputFault complex type is an extension of the UserProfileFault complex type.
UnknownFault The UnknownFault complex type describes errors that occur for unknown reasons in the service endpoint (4) of this protocol. The UnknownFault complex type is an extension of the UserProfileFault complex type.
UserData UserData is a complex type that contains the commonly used properties of the user profile data for a specific user in the user profile store.
UserProfileFault The UserProfileFault complex type describes errors that occur because of errors
The InputFault complex type describes errors that occur because of invalid UserSearchCriteria input from a protocol client. The InputFault complex type is an extension of the UserProfileFault complex type.
FailureDetail: Specifies an error string. The protocol does not impose any restriction on the
behavior of the protocol client with respect to this field.
FaultCode: Specifies a numerical indicator of the error that occurred. The protocol does not impose any restriction on the behavior of the protocol client with respect to this field.
Department: The department at work to which the user belongs.
Email: The work-related email address of the user.
LastUpdate: The timestamp, in UTC format, when the user's user profile data was last modified.
MasterRecordID: The identifier of the primary record that stores the user profile data. If the MasterRecordID equals the RecordID, then this record MUST be the primary record of the user profile data of the user. The primary record is the main record for the user if the user has two user profiles.
NTName: The user name string that uniquely identifies the user within the authentication domain
that is used to authenticate the user.
PartitionID: A GUID used to filter the current request. This value MUST NOT be null or empty.
PictureUrl: The URL of a picture by which the user prefers to be recognized.
PictureTimestamp: A string that serves as a version identifier for the user's picture. The value of this property SHOULD change whenever the contents of PictureUrl and/or the contents of the picture stored at PictureUrl are altered.
PicturePlaceholderState: An integer that indicates whether the picture located at the URL stored in the PictureUrl property is a placeholder image. Valid values are "0" (not a placeholder) and "1" (placeholder).
PictureExchangeSyncState: An integer that indicates whether the picture located at the URL stored in the PictureUrl property was retrieved from Microsoft Exchange Server. Valid values are "0"
(not retrieved from Microsoft Exchange Server) and "1" (retrieved from Microsoft Exchange Server).
PreferredName: The display name of the user by which the user prefers to be addressed.
ProfileSubtypeID: An integer that indicates the type of profile. Valid values are "1" (user) and "2" (organization).
RecordID: An 8-byte, user profile record identifier.
SID: A security identifier (SID) that uniquely identifies the user within the authentication domain that is used to authenticate the user.
SipAddress: The Session Initiation Protocol (SIP) address of the user.
Title: The work title of the user.
UserID: A 16-byte GUID that uniquely identifies the user.
PersonalSpace: The URL of the personal site for the user.
FeedIdentifier: A string that identifies the feed source for the user. The format of the string is feed application defined.
FeedPrivacyActivity: An integer that, if nonzero, indicates that changes to the user profile may generate feed activities.
IsPeopleListPublic: A Boolean that, if true, indicates that other users are permitted to obtain this users list of followed people.
EmailOptin: An integer field containing bitmask values that indicate the user-specified preferences for receiving emails related to feed activities. Emails are sent to the user under the following conditions:
If the bit corresponding to value 0x08 is set, emails are sent to this user when a feed entry is
posted to this user by any other feed user.
If the bit corresponding to value 0x10 is set, emails are sent to this user when any other feed
user replies to a feed entry posted by this user.
If the bit corresponding to value 0x20 is set, emails are sent to this user when any other feed
user replies to a reply posted by this user.
StatusNote: The body of the most recent non-reply feed entry generated by the user.
2.2.5 Simple Types
The following table summarizes the set of common XML schema simple type definitions defined by this specification. XML schema simple type definitions that are specific to a particular operation are described with the operation.
Simple
type Description
char The char simple type is a Unicode character that is stored in a 4-byte integer.
duration The duration simple type is the length of time, as specified in [XMLSCHEMA].
FaultCodes The FaultCodes simple type is an enumeration of the possible errors that the service endpoint (4) of this protocol communicates with protocol clients. The protocol imposes no restriction on the behavior of the protocol client with respect to this type.
The FaultCodes simple type is an enumeration of the possible errors that the service endpoint (4) of this protocol communicates with protocol clients. The protocol imposes no restriction on the
behavior of the protocol client with respect to this type.
In the following sections, the schema definition might differ from the processing rules imposed by the protocol. The WSDL in this specification matches the WSDL that shipped with the product and provides a base description of the schema. The text that introduces the WSDL might specify differences that reflect actual Microsoft product behavior. For example, the schema definition might allow for an element to be empty, null, or not present but the behavior of the protocol as specified restricts the same elements to being non-empty, not null, and present.
This protocol is a server-side protocol. The client side of this protocol is simply a pass-through. That
is, no additional timers or other state is required on the client side of this protocol. Calls that are made by the upper protocol or application are passed directly to the transport, and the results returned by the transport are passed directly to the higher-layer protocol or application.
3.1 Server Details
This protocol is based on stateless interaction between the protocol client and protocol server. The
protocol client MUST be authenticated with the credentials of a user who has access to the User
Profile Service (referred to as ‘UPA Standard Authentication’ in the following figure). The protocol simply exposes the data that is currently stored in the User Profile Service that is deployed and running. There is no interdependency between the information exchanged between the protocol client and protocol server during one instance of their interaction using this protocol and the next instance. The following diagram illustrates the control flow for retrieving cached information about user profiles and returning it to the protocol client.
Figure 2: Control flow of the user profile caching service
When errors are returned to the protocol client, the service endpoint (4) of this protocol specifies complex types as described in sections 2.2.4.1 through 2.2.4.4 for each error.
3.1.1 Abstract Data Model
This section describes a conceptual model of possible data organization that an implementation
maintains to participate in this protocol. The described organization is provided to facilitate the explanation of how the protocol behaves. This document does not mandate that implementations adhere to this model as long as their external behavior is consistent with that described in this document.
A key aspect of this protocol is that it allows protocol clients to gain quick and scalable access to a commonly used subset of User Profile Service properties and it does so through a WCF service
endpoint (4) that caches these properties from the back-end database server. Protocol clients can use the services that are offered by this protocol for commonly used user profile properties, such as
email, picture URL, user name, display name, and user profile record identifier. Protocol clients cannot use this protocol to update user profile information; this protocol does not support write requests.
Because this protocol does not support write requests, the cache of user profile properties behind the service endpoint (4) of this protocol can potentially be out-of-date with the database layer before the cache is refreshed internally within the service. The following diagram captures these dependencies.
Figure 3: Dependencies on the cache
The preceding diagram illustrates that protocol clients that use this protocol MUST be able to tolerate a small delay, in the order of minutes, before a change that is made to the user profile data in the database is reflected in the cache. The cache refresh timer cannot be manipulated by using
this protocol. It can be controlled only on the application server itself.
Initialization is not needed for the cache in the service endpoint (4) because the cache is populated on demand and transparently whenever the protocol client accesses data that is missing in the cache but present in the database. The protocol client interface is a very simple stateless
request/response protocol.
3.1.2 Timers
None.
3.1.3 Initialization
None.
3.1.4 Message Processing Events and Sequencing Rules
The following table summarizes the list of operations as defined by this specification.
The protocol client sends an IProfileDBCacheService_GetUserData_InputMessage request
message and the protocol server responds with an IProfileDBCacheService_GetUserData_OutputMessage response message. If the user profile store has user profile data that corresponds to the input UserSearchCriteria complex type, then this operation returns and packages that data for the protocol client as an output UserData
complex type. The protocol client MAY send a request to retrieve multiple user profiles in one call to this operation, as specified in section 3.1.4.1.3.1. The operation returns one UserData complex type for each input that it receives if the operation finds the user data. Otherwise, the operation MUST return NULL in place of UserData corresponding to the UserSearchCriteria. In case of any error, the operation MUST return an error.If the operation returns a SOAP fault as specified in
[SOAP1.1] section 4.4 or [SOAP1.2/1] section 5.4, the SOAP fault detail MUST contain one of the
error complex types as specified in sections 2.2.4.1 through 2.2.4.4.
GetUserDataResult: Contains StreamedDataOfArrayOfUserDatajHCugpoN complex type. The
collection of UserData complex types specified in StreamedDataOfArrayOfUserDatajHCugpoN complex type have a one-to-one relationship with input searchCriteria complex types. If the user
profile data for a specific UserSearchCriteria is not found, the corresponding UserData structure is nil.
3.1.4.1.3 Complex Types
The following table summarizes the XML schema complex type definitions that are specific to this operation.
Complex type Description
ArrayOfbase64Binary ArrayOfbase64Binary is a sequence of zero or more base64Binary types.
ArrayOfguid ArrayOfguid is a sequence of zero or more 16-byte GUIDs.
ArrayOflong ArrayOflong is a sequence of zero or more 8-byte, long integers.
ArrayOfstring ArrayOfstring is a sequence of zero or more strings.
MarshalByRefObject MarshalByRefObject is the base class for objects that communicate across application domain boundaries by exchanging messages using a proxy.
MemoryStream MemoryStream is a complex type that specifies a stream (1) whose backing store is memory.
Stream Stream is a complex type that specifies a stream (1).
StreamedDataOfArrayOfUserDatajHCugpoN StreamedDataOfArrayOfUserDatajHCugpoN is a complex type that contains a stream (1) with serialized contents of ArrayOfUserData complex type.
UserSearchCriteria The UserSearchCriteria complex type specifies the list of properties that the service endpoint (4) MUST
use when searching for user profile data. In case of any error, the protocol server MUST return either an InputFault, ConfigurationFault, or UnknownFault complex type to the protocol client.
The UserSearchCriteria complex type specifies the list of properties that the service endpoint (4) MUST use when searching for user profile data. In case of any error, the protocol server MUST return either an InputFault, ConfigurationFault, or UnknownFault complex type to the protocol client.
AllowAlternateAccountName: A single user can have multiple accounts in an organization. For
example, a user can have an account "DOMAIN1\user1" for primary authentication (1) and another account "DOMAIN2\User1First.User1Last" for email. When a user's user profile information is created, a distinct record for each user account is created in the user profile store, but the service ensures that all of the accounts have the same user profile data associated with them in the user profile store. The service also marks one of the accounts, for example "DOMAIN1\user1" as the
master account, which is used primarily to identify the user. If this value is "true", it indicates that the UserSearchCriteria can be applied to any of the user’s accounts. If this value is "false", it indicates that UserSearchCriteria MUST be applied only to the master account for the user.
CorrelationID: The optional request identifier for the current request.
EmailCollection: The list of email addresses for users, based on which the search for their user profile data MUST be conducted by the service. A commonly used format is
NTNameCollection: The list of user names for users, based on which the search for their user profile data MUST be conducted by the service. A commonly used format is "DOMAIN\user".
PartitionID: A GUID used to filter the current request. This value MUST NOT be null or empty.
RecordIDCollection: The list of 8-byte user profile record identifiers, based on which the search for the user profile data MUST be conducted by the service.
SIDCollection: The list of security identifiers (SIDs), based on which the search for the user profile data MUST be conducted by the service.
SearchColumn: Specifies which of the following search criteria fields to use when searching for user profile data:
If the SearchColumn is the string "Email" it specifies EmailCollection.
If the SearchColumn is the string "UserID" it specifies UserIDCollection.
If the SearchColumn is the string "NTName" it specifies NTNameCollection.
If the SearchColumn is the string "SID" it specifies SIDCollection.
If the SearchColumn is the string "RecordID" it specifies RecordIDCollection.
The service never matches against more than one of these fields at a time. The service chooses exactly one string specified by SearchColumn to conduct a search. This value MUST NOT be null or empty.
UserIDCollection: The list of 16-byte GUIDs that uniquely identify a user, based on which the
search for the user profile data MUST be conducted by the service.
This section provides specific example scenarios for retrieving a single user profile by login name and retrieving multiple user profiles by user profile record identifier.
Consider that the following two user profiles are part of the user profile store:
The information in this specification is applicable to the following Microsoft products or supplemental software. References to product versions include released service packs:
Microsoft SharePoint Server 2010
Microsoft SharePoint Server 2013
Exceptions, if any, are noted below. If a service pack or Quick Fix Engineering (QFE) number appears with the product version, behavior changed in that service pack or QFE. The new behavior also applies to subsequent service packs of the product unless otherwise specified. If a product edition appears with the product version, behavior is different in that product edition.
Unless otherwise specified, any statement of optional behavior in this specification that is prescribed using the terms SHOULD or SHOULD NOT implies product behavior in accordance with the SHOULD or SHOULD NOT prescription. Unless otherwise specified, the term MAY implies that the product