TIBCO Mashery® OAuth 2.0 Implementation Guide

Table of Contents

• About this Guide
• Introduction
  • Assumptions
  • Contents Overview
• Overview
  • Benefits of Using the Accelerator
  • Implementation Process Checklist
  • Things You Should Know
• The OAuth 2.0 Configuration Interface
• The Mashery OAuth 2.0 API
• Supported Grants and Flows
  • Authorization Flow
  • Implicit Grant Flow
  • Resource Owner Password Credentials Flow
  • Client Credentials Flow

About this Guide

Introduction

This guide describes how to use the TIBCO Mashery® OAuth 2.0 Accelerator to integrate OAuth 2.0 capabilities into your API. The OAuth 2.0 authorization protocol enables an application to obtain access to your HTTP service without divulging user secrets such as username and password.

Assumptions

This guide assumes that you:

• Have registered and signed in at http://support.mashery.com and requested Mashery API Keys
• Can setup the various pages needed to integrate OAuth 2.0, for example, an authentication endpoint and page to authenticate the resource owner and obtain authorization
• Are thoroughly familiar with the concepts contained in the OAuth 2.0 specification

Contents Overview

The Mashery Configuration Guide is divided into the following chapters:

• Overview. Describes the structure and benefits of the Mashery OAuth 2.0 Accelerator
• The OAuth 2.0 Portal User Interface. Describes how to configure OAuth 2.0 using the associated portal settings.
• The Mashery OAuth 2.0 API. Describes the resources of the Mashery OAuth2.0 API.
• Supported Grants and Flows. Describes the supported OAuth 2.0 grants and flows.

Overview

The Mashery OAuth2 Accelerator consists of an oauth2 configuration user interface and an API which are described in detail later in this manual:

The OAuth 2 Accelerator acts as an integrated component of your Authorization and Resource servers. Capabilities provided include:

• Authorization Server: Authorization Code, Access Token and Refresh Token issuance, persistence and management
• Resource Server: Verification of access tokens, access control to resources (endpoints)
• Rate Limiting : End users (access tokens) rate limiting

Note: The Mashery OAuth 2.0 Accelerator components shown in the figure above represent the functionality provided and are not deployed within your Resource Server and the Authorization Server; and are not in and of themselves the Resource Server and Authorization Server.

Benefits of Using the Accelerator

Item	Without Accelerator	With Accelerator
Data management services necessary to issue and manage authorization codes and tokens
Rate limit end users using access tokens
Reporting and analytics on resource access
Access token verification

Implementation Process Checklist

Use the implementation Process checklist below to ensure that you and Mashery are working effectively together to implement OAuth 2.0:

Things You Should Know

• Redirection URL Check ?Mashery does not perform any check against the supplied redirect_uri. However, the field is exposed on the application registration form to collect this. Service provider Authorization server must perform the check by comparing the client supplied value and value returned in the fetchApplication API call.
• Mashery does not perform any scope checking ? The scope provided by the service provider during authz code and access token creation is stored and passed on to the service provider in the X-Mashery-Oauth-Scope HTTP Header. The provider may use this information for access control rules in their tier.
• Foreign codes and tokens ? Foreign authorization codes, access or refresh tokens cannot be imported into Mashery. Mashery must always generate these.
• Client credentials are per API ? If there are multiple oauth2 protected APIs, authorization codes, tokens, etc. must be generated for each service and the correct token used for resources in the corresponding service.

The OAuth 2.0 Configuration Interface

This chapter describes how to access the OAuth settings on the portal and describe them briefly. These settings assume that you are very familiar with the OAuth 2.0 specification.

To access the OAuth settings, click the OAuth 2.0 tab as shown below:

The following table describes the OAuth 2.0 portal settings:

The Mashery OAuth 2.0 API

The complete technical documentation for the Mashery OAuth 2.0 API is available online at http://support.mashery.com/docs/read/mashery_api/20/OAuth_Supporting_Methods.

The following table describes the API at a high level:

Supported Grants and Flows

Authorization Flow

The Authorization Code grant type is optimized to support your untrusted clients. To support this, you must setup an endpoint for the partner application to call to obtain end user authorization per the OAuth 2.0 spec. The authorization server will then call Mashery?s API, fetchApplication, to obtain application metadata - the information necessary to confirm the redirect_uri and populate the login window.

The authorization server will serve the appropriate login window to the end user. Once the end user is authenticated (authorizing the app to access it?s protected resources), the authorization server will call Mashery?s API, createAuthorizationCode, providing a specific user_context, scope and redirection url. Mashery will return an authorization code to the authorization server, which will return the code to the client application via the redirection url.

During setup, you may configure a TTL for the Authorization Code.

Once the client application has an authorization code, it may request an access token by calling the token endpoint on the Mashery Traffic Manager directly. Mashery creates, stores, and issues an access token to the client application. The response also includes a refresh_token (if enabled), expiration period, token type, and scope. Alternatively, the authorization server may host the token endpoint and call the Mashery API, createAccessToken to obtain the access token that will then be returned to the client application.

During setup, you may configure a TTL for the Access Token.

The client application may then call protected resources (ex: Profile) with the access token issued by Mashery. Mashery will verify the access token and forward calls to the API with the matching user_context and scope in the HTTP header.

Implicit Grant Flow

The Implicit Grant type is optimized to support public clients (JavaScript clients). To support this, you must setup an endpoint for the partner application to call to obtain end user authorization per the OAuth 2.0 spec.

The authorization server will call Mashery?s fetchApplication and serve an appropriate login window as described above. Once the end user is authenticated (authorizing the app to access it?s protected resources), the authorization server will call Mashery?s API, createAccessToken. Mashery will create, store, and respond with an access token and expiration period. The authorization server will return this data to the client application via the redirection url.

The client application is now empowered to call protected resources. Mashery will verify the access token and forward calls to the API with the matching user_context and scope in the HTTP header.

Resource Owner Password Credentials Flow

The Resource Owner Password Credentials grant type is optimized to support trusted clients that wish to access their own data or the data of an end user for which they have a trust relationship. This grant type is suitable for clients capable of obtaining the resource owner's credentials (username and password, typically using an interactive form). To support this, you must setup an endpoint for the partner application to call to requests an access token from the authorization server?s by including the end user credentials received. This flow does not require Client to serve a login window. The client When making the request, the client

The authorization server will then call Mashery?s API, createAccessToken. Mashery will create, store, and respond with an access token and expiration period, which will be returned this data to the client application.

The client application is now empowered to call protected resources. Mashery will verify the access token and forward calls to Client?s API with the matching user_context and scope in the HTTP header.

Client Credentials Flow

The Client Credentials Flow grant type is optimized to support your developer partners that wish to access information from that is not associated with a particular user account. In this case, the Mashery client ID and shared secret replace the need for a username and password. Since the client authentication is used as the authorization grant, no additional authorization request is needed.