In this tutorial you will learn how to secure an API with an access token from Google, when Google is the OAuth provider. The API Connect API Security definition uses the Appid for its identity and the OAuth Token Introspection support. Google does not support the OAuth Token introspection support (RFC 7662) standard, so you will employ a workaround to make things work properly as follows:

• start the API connect toolkit with DataPower
• import the utility_1.0.0.yaml and weather-provider-api_1.0.0.yaml API files into APIC v5.0.7.2 or greater system.
• get an access token using the bridging service from Google – OAuth 2.0 Playground
• convert the token from Google format to introspection format using the utility.yaml API in API Connect
• test using Postman to call the weather API
• secure the weather API using the resulting token

Why third-party OAuth in Mobile applications?
Web / Mobile applications that provide access to third-party API services make it easy to share resources. The OAuth provider (in this case Google) store the ‘permission’ granted to the third-party OAuth application so they don’t need to re-ask your permissions again and again. This allows you to login to the Web / Mobile application using your Google credentials without being prompted repeatedly to perform the OAuth handshake to maintain data privacy.

Prerequisites

• A Gmail account
• An IBM Bluemix account
• API Connect Developer Toolkit 5.0.7+ installed
• Postman installed
• Curl installed if not already supplied by you OS
• Files for this lab can be downloaded from here. Import the following API definitions files by using Import API from a file or URL from the Developer Toolkit: weather-provider-api_1.0.0.yaml, utility_1.0.0.yaml. Add Postman files to a local file folder: PostmanCollection.json, lab.postman_environment.json.

Important

• These instructions assume a Mac system.
• Ensure that Postman and curl are installed. Mac system’s command line interface comes with curl already installed.
• If you are unfamiliar with configuring Oauth with API Connect see this blog.

Introduction

In this tutorial, you will learn how to secure an API with an access token from Google as the OAuth provider. The API Connect API Security definition uses the APPid and the introspection endpoint. Since Google does not support the introspection endpoint standard you will employ a workaround to bridge the Google format to introspection format.

Instructions

1. To get started, import the utility_1.0.0.yaml and the weather-provider-api_1.0.0.yaml API files into API Connect v5.0.7.2 or greater system by copying the supplied files into your working directory such as …/apic_projects/google.

2. Next, from the working directory, start the API connect toolkit with DataPower. If you are unfamiliar with running the API Connect Developer toolkit, you can follow the instructions here.

Note: The imported API definitions contain pre-configured OAuth configurations to make it easier for you.

3. We need to get an access token using the bridging service from Google – OAuth 2.0 Playground. Use the OAuth 2.0 Playground to obtain an access token by expanding the first entry in the list and clicking the URL. Then click the Authorize APIs button.


Click your Gmail account and click the Allow button in the subsequent window as shown below.


Click Exchange authorization code for tokens and note that that the access token expires in 3600 seconds (1 hour).


Copy the access token to a note pad for later use.


4. Confirm that the access token gets a 200 OK by substituting it into the following curl commad:

bills$ curl -k -v https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=ya29.GlvOBK6AuYvYyobG4jt1Sw7VenROH97MhuKLB5ss06k-PIZLKDPtv0iMqJk4G1TSu1EME0u0HdTmXeeABDYLLcRmpgwL2BCbaX5Imllrym-i7AjBKMDG-tkq4wUf
...
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: Mon, 01 Jan 1990 00:00:00 GMT
< Date: Fri, 22 Sep 2017 20:45:03 GMT
< Vary: X-Origin
< Content-Type: application/json; charset=UTF-8
< X-Content-Type-Options: nosniff
< X-Frame-Options: SAMEORIGIN
< X-XSS-Protection: 1; mode=block
< Server: GSE
< Alt-Svc: quic=":443"; ma=2592000; v="39,38,37,35"
< Accept-Ranges: none
< Vary: Origin,Accept-Encoding
< Transfer-Encoding: chunked
<
{
"azp": "407408718192.apps.googleusercontent.com",
"aud": "407408718192.apps.googleusercontent.com",
"scope": "https://www.googleapis.com/auth/adexchange.buyer",
"exp": "1506116512",
"expires_in": "3409",
"access_type": "offline"
}
* Connection #0 to host www.googleapis.com left intact

Change the token a little and try again as a test

bills$ curl -k -v https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=ya29.GlvOBK6AuYvYyobG4jt1Sw7VenROH97MhuKLB5ss06k-PIZLKDPtv0iMqJk4G1TSu1EME0u0HdTmXeeABDYLLcRmpgwL2BCbaX5Imllrym-i7AjBKMDG-tkq4wUf
...
>
< HTTP/1.1 400 Bad Request
< Vary: X-Origin
< Content-Type: application/json; charset=UTF-8
< Date: Fri, 22 Sep 2017 20:46:16 GMT
< Expires: Fri, 22 Sep 2017 20:46:16 GMT
< Cache-Control: private, max-age=0
< X-Content-Type-Options: nosniff
< X-Frame-Options: SAMEORIGIN
< X-XSS-Protection: 1; mode=block
< Server: GSE
< Alt-Svc: quic=":443"; ma=2592000; v="39,38,37,35"
< Accept-Ranges: none
< Vary: Origin,Accept-Encoding
< Transfer-Encoding: chunked
<
{
"error_description": "Invalid Value"
}
* Connection #0 to host www.googleapis.com left intact

5. Start the API Connect Toolkit with IBM® DataPower

Note: Ensure that Docker is started on your workstation before doing the next steps.

If not already done, start the API Connect Designer with the DataPower gateway and confirm that the APIs are in place.
…/apic_projects/google apic edit


Ensure that the DataPower gateway is selected. Click the select provider icon to show the test gateways. Choose DataPower Gateway policies. When you select a gateway, the features that are available to it become visible in the policy palette. Click the save icon to save your preference in the YAML file.


From another CLI window start the gateway …/apic_projects/google apic start

Copy the IP address:port for later use.


6. Convert the token from Google format to introspection format using the utility.yaml API.

Note the /third-party-oauth/introspect/google-microservice path.


Click the Assemble tab and then click the POST /third-party-oauth/introspect gatewayscript. Examine the gatewayscript. It simulates a 3rd party Oauth provider endpoint and then returns a response based on the validity of the access token.


Paste the IP address:port and access token into the curl command and run it.

Note: This request is passing the token from Google to the google-microservice path in the utility API. The microservice converts the Google formatted request to the introspect formatted request needed by API Connect with the required client ID and scope. In other words, it changes the introspect request to a Google request and converts the Google response to an introspection response.

bills$ curl -k -v https://172.27.35.160:4001/utility/third-party-oauth/introspect/google-microservice -d 'token_type_hint=access_token&scope=weather&client_id=default&token=ya29.GlvOBK6AuYvYyobG4jt1Sw7VenROH97MhuKLB5ss06k-PIZLKDPtv0iMqJk4G1TSu1EME0u0HdTmXeeABDYLLcRmpgwL2BCbaX5Imllrym-i7AjBKMDG-tkq4wUf'
...
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: POST
< Access-Control-Allow-Credentials: false
< X-RateLimit-Limit: name=rate-limit,100;
< X-RateLimit-Remaining: name=rate-limit,98;
<
* Connection #0 to host 172.27.35.160 left intact
{"active":true}Bills-MBP:google billbarrus$

Change the token a little and verify the “active”:false response.

bills$curl -k -v https://172.27.35.160:4001/utility/third-party-oauth/introspect/google-microservice -d 'token_s_token&scope=weather&client_id=default&token=ya29.GlvOBK6AuYvYyobG4jt1Sw7VenROH97MhuKLB5ss06k-PIZLKDPtv0iMqJk4G1TSu1EME0u0HdTmXeeABDYLLcRmpgwL2BCbaX5Imllrym-i7AjBKMDG-tkq4wUf'
...
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: POST
< Access-Control-Allow-Credentials: false
< X-RateLimit-Limit: name=rate-limit,100;
< X-RateLimit-Remaining: name=rate-limit,97;
<
* Connection #0 to host 172.27.35.160 left intact
{"active":false}Bills-MBP:google billbarrus$

7. Review security configuration of the weather API using the API Connect designer.

Open the weather-provider-api and click /info under Paths on the left side. Click Get /info, scroll down to the Security section, and note the Option 1 selections checked.


Scroll up a little and see the Introspection URL.


8. Test the API using the built-in API Connect tester.

With the weather-provider-api opened, click the Assemble tab, ensure that the API Connect Designer with the DataPower gateway is started, and click the Test button.


Click the get /info operation, paste the Access Token, and click the Invoke button.


A similar response appears as follows:


9. Test the API using using Postman

If not already done, install Postman and then import the collection request file by clicking Import and selecting PostmanCollection.json from your file repository.


Verify that the two header values pairs appear as follows:


Import the environment file by clicking Settings icon and Manage Environments.


Click Choose Files and select lab.postman_environment.json from your file repository.


Click the Settings icon and verify that the environment key value pairs as shown below. Substitute your gateway values for URL as indicated.


Paste the authorization token as shown and click the Send button.


A successful response appears similar to the one above in the Pretty tab.

Congratulations! You secured an API with an access token from Google as the OAuth provider.

Special thanks to Shiu-Fun Poon for help in putting together these examples.

5 comments on"Integrate third party OAuth provider (Google) to secure APIs"

  1. How do I manage the client ID. If the 3rd party OAuth provider has a Client ID. Do I need to register that client, how do I manage it (Their system or the API management system)

    • APIc, introspect call -> the API that has the proxy policy (this contains the client_id and client_secret that 3rd party needs) -> call the 3rd party introspect endpoint.

    • Paul, APIc, introspect call -> the API that has the proxy policy (this contains the client_id and client_secret that 3rd party needs) -> call the 3rd party introspect endpoint.

  2. Hi, Do we have APIs available to do provisioning on API Connect itself. So we want to create account on API connect by Identity Manager Solution. Do you have any APIs that we can use to create account on API connect and assign roles to user.

  3. Hi There, I found the 2 yaml files at this location: https://github.com/ozairs/apiconnect/tree/master/openid
    Are they the same?

Join The Discussion

Your email address will not be published. Required fields are marked *