Oracle® Fusion Middleware Oracle API Gateway OAuth User Guide 11g Release 2 (11.1.2.4.0)           July 2015 Oracle API Gateway OAuth User Guide, 11g Release 2 (11.1.2.4.0) Copyright 1999, 2015, Oracle and/or its affiliates. All rights reserved.  This software and related documentation are provided under a license agreement containing restrictions on use and  disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed  by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform,  publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this  software, unless required by law for interoperability, is prohibited.  The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any  errors, please report them to us in writing.  If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S.  Government, the following notice is applicable:  U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S.  Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable  Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure,  modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government  contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227- 19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA  94065.  This software is developed for general use in a variety of information management applications. It is not developed or  intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If  you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup,  redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any  liability for any damages caused by use of this software in dangerous applications.  Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective  owners.  This software and documentation may provide access to or information on content, products, and services from third parties.  Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to  third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or  damages incurred due to your access to or use of third-party content, products, or services. This documentation is in  prerelease status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which  you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of  any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the  use of this documentation.  The information contained in this document is for informational sharing purposes only and should be considered in your  capacity as a customer advisory board member or pursuant to your beta trial agreement only. It is not a commitment to  deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development,  release, and timing of any features or functionality described in this document remains at the sole discretion of Oracle.  This document in any form, software or printed matter, contains proprietary information that is the exclusive property of  Oracle. Your access to and use of this confidential material is subject to the terms and conditions of your Oracle Software  License and Service Agreement, which has been executed and with which you agree to comply. This document and  information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without  prior written consent of Oracle. This document is not part of your license agreement nor can it be incorporated into any  contractual agreement with Oracle or its subsidiaries or affiliates.  27 July 2015 Contents Preface 8 Who should read this document 8 How to use this document 8 What's new 10 1 OAuth and OpenID Connect concepts 11 OAuth 2.0 11 OpenID Connect 1.0 12 2 Introduction to API Gateway OAuth 2.0 server 13 API Gateway OAuth concepts 13 OAuth server example workflow 14 API Gateway OAuth server features 15 Further information 16 3 API Gateway OAuth 2.0 authentication flows 17 Run the sample scripts 18 Authorization code grant (or web server) flow 18 Obtain an access token 19 Run the sample client 22 Further information 24 Implicit grant (or user agent) flow 24 Obtain an access token 25 Run the sample client 27 Further information 28 Resource owner password credentials flow 29 Request an access token 29 Handle the response 30 Run the sample client 30 Further information 31 Client credentials grant flow 31 Request an access token 32 Handle the response 32 Run the sample client 33 Further information 33 JWT flow 33 Create a JWT bearer token 34 Request an access token 36 OracleAPIGateway  11.1.2.4.0 OAuthUserGuide  3 Handle the response 36 Run the sample client 37 Further information 37 Revoke token 37 Run the sample client 38 Response codes 39 Further information 39 Token information service 39 Run the sample client 40 Response codes 41 Further information 42 4 Set up API Gateway as an OAuth 2.0 server 43 Enable OAuth management 43 Enable OAuth endpoints 45 Import sample client applications 45 Migrate existing client applications 46 5 API Gateway as an OAuth 2.0 authorization server 48 Manage access tokens and authorization codes 48 6 OAuth 2.0 authorization server filters 51 Get access token information 52 Overview 52 Token settings 52 Monitoring settings 52 Advanced settings 53 Get access token using authorization code 53 Overview 53 Application validation settings 54 Access token settings 54 Monitoring settings 55 Get access token using client credentials 55 Overview 55 Application validation settings 56 Access token settings 56 Monitoring settings 57 Get access token using JWT 58 Overview 58 Application validation settings 58 Access token settings 59 Monitoring settings 60 Get access token using SAML assertion 61 Overview 61 OracleAPIGateway  11.1.2.4.0 OAuthUserGuide  4 SAML assertion validation settings 61 Access token settings 62 Monitoring settings 63 Consume authorization requests 64 Overview 64 Validation settings 64 Authorization code settings 65 Access token settings 66 Advanced settings 67 Refresh access token 68 Overview 68 Application validation settings 68 Access token settings 68 Monitoring settings 69 Get access token using resource owner credentials 70 Overview 70 Application validation settings 70 Access token settings 71 Monitoring settings 72 Revoke token 73 Overview 73 Revoke token settings 73 Monitoring settings 74 7 API Gateway as an OAuth 2.0 resource server 75 Register and manage OAuth client applications 75 Manage client applications 75 Manage OAuth scopes 76 Client Application Registry 78 8 OAuth 2.0 resource server filters 80 Validate access token 80 Overview 80 General settings 80 Response codes 81 9 API Gateway as an OAuth 2.0 client 83 Introduction to API Gateway OAuth client 83 API Gateway OAuth client features 84 OAuth 2.0 example client workflow 85 Set up API Gateway OAuth client 86 Configure OAuth client application credentials 86 Add application credentials 87 Add OAuth provider 91 OracleAPIGateway  11.1.2.4.0 OAuthUserGuide  5 Create a callback URL listener 91 Manage client access tokens 91 10 OAuth 2.0 client filters 93 Delete an OAuth client access token 93 Overview 93 General settings 94 Get OAuth client access token 94 Overview 94 General settings 94 SSL settings 94 Additional settings 95 Redirect resource owner to authorization server 95 Overview 95 General settings 95 Refresh an OAuth client access token 96 Overview 96 General settings 96 SSL settings 97 Additional settings 97 Retrieve OAuth client access token from token storage 97 Overview 97 General settings 98 Save an OAuth client access token 98 Overview 98 General settings 98 11 API Gateway and OpenID Connect 100 Introduction to API Gateway OpenID Connect 100 OpenID Connect concepts 101 Relationship to OAuth 2.0 101 Prerequisites 103 OpenID Connect flow 104 Build an OpenID Connect IdP server 105 Build an OpenID Connect client 105 Use the API Gateway OAuth client demo 106 Deploy the client demo 108 Client policies 108 12 OpenID Connect filters 110 Create an OpenID Connect ID token 110 Overview 110 General settings 111 Verify an OpenID Connect ID token 111 OracleAPIGateway  11.1.2.4.0 OAuthUserGuide  6 Overview 111 General settings 112 Appendix A: OAuth 2.0 message attributes 113 OAuth 2.0 server message attributes 113 accesstoken methods 113 accesstoken.authn methods 114 authzcode methods 114 oauth.client.details methods 115 Example of querying a message attribute 116 OAuth scope attributes 118 OAuth SAML bearer attributes 119 OAuth 2.0 client message attributes 119 oauth.client.accesstoken methods 119 oauth.client.application methods 120 OracleAPIGateway  11.1.2.4.0 OAuthUserGuide  7 Preface   This document describes how to use the OAuth 2.0 and OpenID Connect features of API Gateway. It  describes how to configure API Gateway as an OAuth server and as an OAuth client. It also describes  the OpenID Connect support provided by API Gateway. Who should read this document The intended audience for this document is policy developers and system integrators who are  responsible for configuring OAuth and OpenID Connect flows.  Before configuring OAuth or OpenID Connect flows in API Gateway you should understand exactly  what message filters are, and how they are chained together to create a message policy. These  concepts are documented in detail in the API Gateway Policy Developer Guide. You should also have  an understanding of API Gateway concepts and features. For more information, see the API Gateway  Concepts Guide. How to use this document This document should be used in conjunction with the other documents in the API Gateway  documentation set. Before you begin using the OAuth features of API Gateway, review this document thoroughly. The  following is a brief description of the contents of each chapter: OAuth and OpenID Connect concepts on page 11 – Describes OAuth 2.0 and OpenID Connect  concepts. Introduction to API Gateway OAuth 2.0 server on page 13 – Describes the features of API Gateway  as an OAuth server. API Gateway OAuth 2.0 authentication flows on page 17 – Describes the OAuth flows supported by  API Gateway. Set up API Gateway as an OAuth 2.0 server on page 43 – Describes how to set up API Gateway as an  OAuth server. API Gateway as an OAuth 2.0 authorization server on page 48 – Describes the OAuth authorization  server features of API Gateway. OAuth 2.0 authorization server filters on page 51 – Describes how to configure the OAuth  authorization server filters. API Gateway as an OAuth 2.0 resource server on page 75 – Describes the OAuth resource server  features of API Gateway. OracleAPIGateway  11.1.2.4.0 OAuthUserGuide  8 Preface OAuth 2.0 resource server filters on page 80 – Describes how to configure the OAuth resource server  filters. API Gateway as an OAuth 2.0 client on page 83 – Describes the OAuth client features of API  Gateway. OAuth 2.0 client filters on page 93 – Describes how to configure the OAuth client filters. API Gateway and OpenID Connect on page 100 – Describes how to use the OpenID Connect features  of API Gateway. OpenID Connect filters on page 110 – Describes how to configure the OpenID Connect filters. OAuth 2.0 message attributes on page 113 – Describes the message attributes used in the OAuth  filters. OracleAPIGateway  11.1.2.4.0 OAuthUserGuide  9 What's new   This release of the API Gateway OAuth User Guide contains the following changes:   New concepts section – See OAuth and OpenID Connect concepts on page 11. l   New section on OpenID Connect features – SeeAPI Gateway and OpenID Connect on page 100. l   Restructuring of the section on API Gateway as an OAuth server into two parts: l  o API Gateway as an OAuth 2.0 authorization server on page 48  o API Gateway as an OAuth 2.0 resource server on page 75   Changes to the OAuth authorization server filters section – The Authorize Transaction filter  l has been removed and the functionality moved to the Authorization Code Flow filter. See  Consume authorization requests on page 64   Changes to the OAuth client filters section – The Redirect resource owner to Authz Server  l and Get OAuth Access Token filters have been modified. See Redirect resource owner to  authorization server on page 95 and Get OAuth client access token on page 94.   Changes to the monitoring settings in all OAuth server filters. l   The section on OAuth message attributes has been moved to an appendix. See OAuth 2.0  l message attributes on page 113.   The default user names and passwords have been removed from all documentation for security  l reasons. You can obtain the default user names and passwords from your Oracle Account  Manager. OracleAPIGateway  11.1.2.4.0 OAuthUserGuide  10