Enterprise Integration Patterns
Conversation Patterns
Acquire Token FirstConversation Patterns » Starting a Conversation

Developer Key, Brokered Authentication [21]

A participant has identified a provider and is about to initiate a conversation.

How can a provider ascertain the identity of a requestor?

  • Many providers like to track usage of their service or limit access.
  • Providers may throttle the number of requests they allow from an individual participant within a given time frame. Therefore, they need to reliably distinguish conversation partners.
  • A provider wants to minimize the effort involved in authenticating participants.
  • When sending messages over some bidirectional channels (e.g. TCP), the originator can relatively easily fake its address, because the provider will never use that address to connect to the consumer. Therefore, a client's claimed address may not be a reliable form of identification.

require participants to first acquire an identification token from a token provider and include it in subsequent messages to the provider.

The Acquire Token First conversation involves the following participants:

  • The Initiator sends a Token Request to the Token Provider to obtain a Token. Subsequently, it includes the token in Request messages to the Provider.
  • The Token Provider generates unique tokens upon request from Initiators and returns them to the Initiator. It can also validate tokens received by the Provider.
  • The Provider accepts Request messages that include a token. The Provider may validate the token directly or by asking the Token Provider.

Requesting a token from the Token Provider may happen over a separate channel from the Request. For example, public Web services available over HTTP may require an e-mail request to generate a developer token and associate it with a user. Token Request messages may need to include additional information, for example the participant's e-mail address for the Token Provider to issue the token. The Token Provider may require additional steps such as Verify Identity.

Fixed tokens per client can be easy to forge or steal. They are therefore not suitable for authorizing sensitive operations. The length of the token determines how difficult it is to generate a fake token, i.e. one not produced by the Token Provider but accepted by the Provider.

Tokens do not always have to be secure or difficult to forge. For example, services use it simply to track and limit usage without tying authorization to the token. If tokens are easy to obtain, some initiators may game the system by using Rotate Tokens" to increase the number of requests they can make.

Tokens used for quota enforcement can become a challenge when building a composite service. A successful public service that is accessed by many users may quickly exhaust its usage quota if it access a back-end service with a fixed token. Rotate Tokens can stretch the limit to a certain degree but is not a scalable approach. Alternatively, the public service can require its clients to pass in a valid token, which it propagates to the back-end service, for example using User Grants Access. This is not only inconvenient for the clients, as an additional step is required before the service can be used, but can also break encapsulation as the client should have no knowledge of the back-end services the composite service uses. Lastly, some providers stop issuing tokens, so that it is impossible for the client to supply its own token (for example, Google stopped issuing tokens for its SOAP Search Service).

Some tokens can be verified without the Provider having to contact the Token Provider for each token submitted, for example, if the Token Provider and the Provider share a public/private key combination. In this case, the Token Provider can sign tokens with a private key and the Provider can validate the signature with the Token Provider's public key.

Known Partners [20] describes a robust version of this approach that can be used for services that require mutual trust. More detailed implementation guidance can be found in [21], which describes Brokered Authentication using X.509, Kerberos, and a Security Token Service.

Example: Amazon Web Services

Before you can make a request to Amazon's e-Commerce Web services you need to create an account and obtain a developer token, which has to be passed with all service requests.

Related patterns: Rotate Tokens, User Grants Access, Verify Identity

Table of Contents
Describing Conversations
Hypermedia State
Conversation Vocabulary
Dynamic Discovery
Advertise Availability
Consult Directory
Leader Election
Starting a Conversation
Three-Way Hand Shake
Acquire Token First
Rotate Tokens
Verify Identity
User Grants Access
Basic Conversations
Asynchronous Request-Response
Request-Response with Retry
Quick Acknowledgment
Load Balancer
Managing Distributed Systems
Resource Management
Incremental State Build-up
Renewal Reminder
Ensuring Consistency
Ignore Error
Compensating Action
Tentative Operation
Coordinated Agreement