CP4I Modernization Practicum Workshop Singapore
IBM API Connect
##Add OAuth Security to your API and use Lifecycle Controls to Version Your API
Lab prerequisite: “The Developer Portal Experience”
Table of Contents
1. Introduction
In this lab, we will secure the Customer Database API that was created in the “Create and Secure an API to Proxy an Existing REST Web Service” lab to protect the resources exposed by IBM API Connect. Consumers of our API will be required to obtain and provide a valid OAuth token before they can invoke the Customer Database API. In order for the changes to take effect, we must publish the APIs to the Developer Portal and make them available for the API Consumers. The Customer 1.0.0 version is already running and has active subscribers.
API lifecycle management capabilities is an essential part of the API Management platform. The API lifecycle includes the following stages:
-
Plan and design the API
-
Develop the API
-
Test the API
-
Deploy (publish) the API
-
Retire and deprecate the API
In this tutorial, you will explore the following key capabilities:
-
Configure an OAuth 2.0 service (the Resource Owner Password grant type)
-
Clone a new version of an API
-
Secure the new version of your API
-
Create a new API Product
-
Replace the old Product
-
Test the OAuth API in the Developer Portal
2. Configure a New OAuth 2.0 Provider API
IBM API Connect is a full-featured OAuth 2.0 provider. The OAuth exchange works like any other API call, and thus we treat it as its own API.
In this section, you will create a new OAuth provider API, configure which grant type to use, and configure how it will authenticate user credentials.
2a. Configure Authentication URL User Registry
In order to configure user authentication, you must first define the registry to use, which may be LDAP, local user registry, or an authentication URL. For this lab, we will implement an Authentication URL.
1.If you’re not logged before, follow these instructions to access to the API Manager -> Login to the API Manager
2. In the left menu, click on Resources. As you hover over the icon, you will see the item name.
3. Make sure User registries is selected and click Create.
4. Click on Authentication URL user registry.
5. Enter App Registry for the Title and Display name. Enter an authentication URL for Url, and Click Save.
Note: API Connect issues an HTTP GET call to the Authentication URL endpoint, sending the user’s credential. The following example shows a call made to an Authentication URL identity provider with an endpoint defined as https://myauthurl.example.com/user/authenticate:
If the Authentication URL endpoint returns an HTTP status code of 200, the user authenticates successfully. An HTTP status code other than 200 indicates a failed login attempt. API Connect forwards any HTTP Header starting with X- (with the exception of X-Client-Certificate), and Cookie to the Authentication URL identity provider, to aid the authentication decision;
Use this as example: http://user-auth-basic-http-cp4i.apps.daffy-mukhc7i9.cloud.techzone.ibm.com/user/auth or you can deploy your own basic one from Project User-Auth-Basic.zip
3. Create an OAuth Service
1. You should still be in Resources. If not, in the left menu, click Resources.
2. Click on OAuth providers.
3. Click Add and select Native OAuth provider from the drop down.
4. Enter oauth for the Title and select DataPower API Gateway for the Gateway Type. Click Next.
5. The Configuration screen will show the default Authorize and Token paths. For Supported grant types, select Resource owner - Password and deselect Access code. For Supported client types, select Confidential. Click Next.
6. One scope, sample_scope_1, is automatically created.
7. Replace sample_scope_1 with customer for Scope Name and replace Sample scope definition 1 with Access to Customer API for Scope Description. Click Next.
8. Accept the defaults (App Registry for Authenticate application users using) and click Next.
9. Review the OAuth configuration and click Finish.
10. Click Save.
4. Add the OAuth Service to the Sandbox Catalog
1. In the left menu, click on Manage.
2. Click on Sandbox
3. In the top menu, click on Catalog settings.
4. Click on API user registries.
5. Click Edit.
6. Select App Registry and click Save.
7. Click on OAuth providers.
8. Click Edit
9. Select oauth and click Save.
5. Create a New Version of the Customer API
IBM API Connect supports multiple versions of APIs. We will create a new version of the Customer API before making any changes that would break functionality for existing consumers.
First, we will save the API as a new version.
1. In the left menu, click on Develop.
2. Confirm the APIs tab is selected and click on the 3-dot menu next to Customer Database and select Save as New Version from the drop down menu.
3. Enter 2.0.0 for the Save as New Version and click Submit.
5a. Add OAuth Security to the Customer API
We will modify the security policy for our new API version to tell it to use the OAuth 2.0 provider.
1. Confirm the APIs tab is selected and click on version 2.0.0 of Customer Database.
2. Click on the + next to Security Schemes.
3. Enter oauth-1 for the Security Definition Name (Key) and select oauth2 from the Security Definition Type drop down menu. When you select oauth2 from the drop down menu, it will enable additional configuration options.
4.Select Resource Owner from the Flow drop down menu and click Create.
5. Click Save.
Once saved, you will see an indicator window appear that shows that Your API has been updated. Click on the X to close the window.
6. In the Design tab, find the Security section. You will likely have to scroll up. Expand the Security section clicking on the + if it is not already expanded.
7. Click on the clientId, ClientSecret entry and make sure is not select clientId and ClientSecret. This will remove the checkmark that is next to them.
8. Select oauth-1 and click on Scopes and select customer. Click Create.
9. Click Save.
10. Once saved, you will see an indicator window appear that shows that Your API has been updated. Click on the X to close the window.
6. Create a New Product
In IBM API Connect, Plans and APIs are grouped together in Products, with which you can manage the availability and visibility of APIs and Plans.
Products allow related APIs to be bundled together for subscribers.
1. In the left menu, click on Develop.
2. Click on Products
3. Click Add and select Product from the drop down menu.
4. Select New product and click Next.
5. Enter Customer for the Title and change the Version to 2.0.0. Click Next.
6. Select the Customer Database API that is version 2.0.0 and click Next.
7. We are going to create some new Plans. Click Add
8. Replace Plan 1 with Gold for the Title and 500 for the Rate limit.
9. Click on the Trash can icon next to the Default plan to delete it.
10. Click Add to add another Plan.
11. Replace Plan 2 with Silver for the Title and 250 for the Rate limit.
12. Click Add to add another Plan.
13. Replace Plan 3 with Bronze for the Title and 2 for the Rate limit and change the drop down from hour to minute. Click Next.
14. Select Public for Visibility and Authenticated for Subscribability. Click Next.
15. Your Product will be created and associated with the required objects such as APIs and Plans. Click Done.
16. Click on Products.
7. Stage the Product to your API Manager Environment
Before an API Product can be published, we must first stage that Product to a Catalog. When a Product is in the staged state, it is not yet visible to, or subscribable by developers. However, it can be reviewed by the API Product Manager and published once it has been determined that the API Product is ready to be consumed.
If you stage a Product to a Catalog, editing and then restaging that Product through the Products tab of API Designer or API Manager will affect changes to the staged version.
1. Click on the 3-dot menu next to version 2.0.0 of the Customer Product and select Stage.
2. Select Sandbox for the target Catalog and click Stage.
Note: IBM API Connect allows you to publish products to specific gateways associated with the Catalog.
8. Supersede Version 1.0.0 of the Product
IBM API Connect provides capabilities for managing the lifecycle of your API Products. There are various states which an API Product can reside in, as well as controls around when you can move an API Product from one state to another. In this section, you will explore how to replace a running version of an API Product with a new one.
1. In the left menu, click Manage.
2. Click on Sandbox.
3. The Products tab will list all of the API Products that this Catalog is currently managing. Confirm version 2.0.0 of the Customer Product is Staged and version 1.0.0 of the Customer Product is Published.
4. Click on the 3-dot menu next to version 1.0.0 of the Customer Product and click Supersede.
5. Select customer 2.0.0 and click Next.
6. In order to maintain our consumers’ entitlements, we need to migrate their Plan subscriptions.
The customer 1.0.0 Product has a Plan called Default Plan. The customer 2.0.0 Product does not have a Default Plan. Therefore, we need to choose how we are going to move the subscribers. Select Bronze from the Target drop down menu and click Supersede.
7. IBM API Connect will take care of deprecating version 1.0.0 of the Product and publishing version 2.0.0.
9. Test the OAuth Configuration
In this section, you will test the new version of the API to ensure that OAuth is working properly.
1. In the top menu, click Catalog settings.
2. Click on Portal.
3. Copy the Portal URL and paste it in a new browser tab.
4. Click Sign in and use the Username and Password for the Portal account that you created in “The Developer Portal Experience” lab.
5. Click on Apps.
6. Select the app that you created in “The Developer Portal Experience” lab (e.g. Customer Demo).
7. Click on Subscriptions.
8. Under Product subscriptions, click Migrate this subscription to plan ‘bronze’ in product ‘Customer’ at version ‘2.0.0’.
9. Confirm that you want to migrate the subscription but clicking Migrate subscription.
10. You will see that the subscription has been successfully migrated.
11. Click on API Products.
12. Click on Customer 2.0.0.
13. Click on the Customer Database 2.0.0 API.
14. Click GET /customers
15. Click Try it.
16. Notice that we now have an additional Authorization security requirement defined.
17. Confirm that your application is shown in the API Key and enter your application secret for the API Secret.
18. In the Username and Password fields, you can enter any text. Select customer for the Scopes.
Recall that when we configured the OAuth API, we provided an Authentication URL as the method for validating the user credentials. The URL that we provided will respond back OK with any credentials.
Click Get Token.
19. The API Portal will call out to the OAuth Token URL with your client credentials and user credentials. The OAuth API which you built will intercept the request, validate the credentials, and generate a token.
20. Click Send to invoke the API. The request will include the OAuth bearer token in the Authorization header.
21. Scroll down to see the call results.
22. Feel free to test the rest of the operations. Testing will be similar to the testing that was completed in the “Create and Secure an API to Proxy an Existing REST Web Service” lab.
23. To prove that the token is being validated, you can modify the contents of the Access Token field. Click Send again and you will see an error response.
Summary
Congratulations, you have completed the Add OAuth Security to your API and use Lifecycle Controls to Version Your API lab. Throughout the lab, you learned how to:
-
Configure an OAuth 2.0 service with the Resource Owner Password grant type
-
Clone a new version of an API
-
Secure the new version of your API