Cloud Blog

Category Archives: API Cloud

New and Improved Live Log Viewer

Debugging APIs can be a challenge when things go wrong. A lot can go unexpectedly while the calls travel from a user application to the API gateway, through transformation engine, to the backend service, and back.  Luckily, WSO2 API Cloud comes with a live Log Viewer screen and we have just released its improved version.

Whenever you want to see what’s going on under the hood of API Gateway:

1. In API Cloud, on the Configure menu, click Admin Dashboard:

2. In the API Cloud Admin Dashboard, navigate to Log Analyzer / Live Log Viewer.

3. Invoke the API that you want to troubleshoot (for example, in the Developer Portal or curl or from your application.)

4. See the log in the Log Viewer:

The new Log Viewer:

  • Has a clear visual separation of information, warning, and error messages,
  • Works across all regional gateways around the globe.

Note:

  • API call tracing is off by default, so you will likely not be able to get the detailed information on the actual API and response URLs, headers, and body. To get those, enable tracing before making the calls. Then turn tracing off when you are done troubleshooting.

 

Adding request headers to published APIs

Suppose you have a REST API and besides parameters also want to prompt subscribers for custom HTTP headers. WSO2 API Cloud makes this easy.

In the example below, we will add a custom header called setName to an existing API and invoke it from the Developer Portal.

1. In API Cloud’s Publisher interface, open the API for editing, and on the second screen (Implement), select the Enable API based CORS Configuration checkbox:

2. In the Access Control Allow Headers edit box, type the name of the header that you would like to add (in our case setName) and press Enter. Then click the Save button.

3. Now, go back to the first step of API editing (Design), open the resource that you want to request that header as a parameter, add the parameter with the name of the header, and change the Parameter Type from query to header:

4. If the API has already been published, you can just click Save to make the change go into effect. If not, go to the last step of the wizard and click the Save & Publish button there.

5. Now, you can go to the Developer Portal (also known as API Store), subscribe to the API if you have not done so yet, and expand the method that we have just modified – you will see that our new header setName is there, listed as one of the parameters:

6. When you invoke the method, you can see that the new header is indeed getting added to the API call and passed to your backend. Notice that the generated curl command example also has the new header:

That is it! WSO2 API Cloud makes it easy to design your APIs the way you want them and have them published for your consumers in a way that is intuitive and easy to understand.

Integrating OAuth API Gateway with SAML Identity Provider

OAuth2 is the modern standard of providing security for REST and SOAP APIs. However, a lot of enterprises have existing SAML Identity Providers (IdP) and that they use as their internal authentication standard. They would like their web and mobile applications to have end-users authenticate with these existing providers and then translate that to OAuth, enforce access and policies, and pass the calls to the backend.

Today we will talk about how this works in case of WSO2 API Cloud:

Configuration:

  • Configure the cloud to trust the IdP.
  • In the Developer Portal (API Store), create your application and get its OAuth consumer secret and consumer key.

Now, let’s look at the way the actual authentication and API usage happens in the diagram above:

  1. Your web or mobile app asks the end-user to log in as it normally would.
  2. Your corporate Identity Provider (IdP) checks credentials and issues the SAML2 token.
  3. Now the application needs to generate the personalized OAuth2 token for that end-user and that app. For that, it invokes the API gateway’s Token API and passes consumer secret, consumer key, and the SAML2 token.
  4. API gateway validates the SAML assertions with the IdP. If particular API Scopes are requested, the gateway also checks to see if the roles with which the scopes are associated match the roles in the SAML assertions.
  5. If validation is successful, API gateway returns the OAuth token and refresh token. The refresh token can be used to renew the OAuth token when it expires.
  6. Now the application has the OAuth token it needs and can use it to invoke the actual APIs.
  7. API gateway uses the OAuth token to identify the end-user, apply security and throttling policies, collect analytics data, and pass the calls to the backend. When the backend is invoked, end-user and application information is passed as JWT token.

That is it. See our documentation page for the specific configuration steps and token API calls, and use API Cloud’s Support menu if you need any help.

 

WSO2Con Europe: Call for Presentations and Early Discounts

November 6-8 in London we will be holding our biggest European event of the year – WSO2Con Europe 2017. I will personally be there as well as our other key leaders, architects, and engineers, and many of our customers.

My personal request to all our cloud customers is to go ahead and submit a session proposal!

Conference talks are a great way to increase your own visibility and boost your career. And you also get perks including free airfare, hotel, and conference pass! There is a deadline of July 28 – so please try to meet it. If you cannot – please let me know so I can apply some lobbying for you. 🙂

If submitting your talks is not your thing (yet) go ahead and buy your conference pass today while the early bird discount is still in place.

Plus, the website also has lots of great recordings from earlier conferences.

I hope to see you in London in November!

Custom Roles

WSO2 API Cloud allows publishers to set API visibility to specific roles and also to use roles for OAuth scopes. With today’s update, we have made both of these easier because now there is a new user interface for custom role creation.

To add a new custom role to your organization in WSO2 Cloud:

1. Click  Roles in the 9-dot menu at the top right:

2. In the Roles dialog box, click the Add Role button at the top left:

3. Give it a name and permissions (for API Cloud scenarios, they would likely at the very least need to have the subscriber permission), then click the Create Role button:

That’s it! Your role is now ready: you can add members to it, and use it for API visibility and OAuth scopes.

 

Yearly discounts and wire transfer payments

We have made it easier to pay for WSO2 Cloud services (API, Integration, Device, and Identity). When we launched initially, monthly credit card payments were the only option we provided. Now we changed two things:

1. You can pay for a year ahead and save 10% of your subscription price:

2. And, if credit card is not something that your purchasing department likes, you can get a regular invoice and pay via a wire transfer instead:

Whatever is the WSO2 Cloud service of your choice, we would like you to be able to pay for it conveniently (and save money on the way!)

OAuth and Authentication Type: Application vs Application User

On the 3rd step of editing APIs in WSO2 API Cloud, you can set required authentication type for each resource:

We have already covered None as the option to allow invoking APIs without any authentication whatsoever.  Today we will discuss the other options.

Application type means that the API will require OAuth tokens generated with client grant type. That grant type produces tokens specific to the subscription but not the end-users.

So if there is a web- or mobile application that subscribed to this API and it has multiple end-users, they will all be sharing the same token and the API backend will not “know” which end-user is invoking the API:

Application User type means that the API accepts OAuth tokens generated with password grant type. These tokens are specific to the end-user – they require not just the application key but also end-user’s username and password.

In this case, each end-user gets their own OAuth tokens even though they are using the same API subscription. API Gateway then generates a JWT token and uses it to pass application and user information to the API backend:

Application and Application User type means that both kinds of tokens are acceptable by the API.

 

 

 

Limit API access with OAuth Scopes

OAuth scopes are a great way to segregate access to APIs and data. Combined with roles they can also be a powerful way to limit who gets access to what.

Let’s have a look at how you can implement scopes in WSO2 API Cloud.

Sample API

Let’s start with a sample WorldBank API that has two resources: /countries and /indicators – both taking a code parameter:

We have it published in Developer Portal and can invoke either of them with no problem (as long as we are subscribed to the API):

Adding Scopes

Now let’s add two different scopes: one that would only give access to /countries and the other one that only gives access to /indicators.

To do this:

  1. Open the API for editing,
  2. Go to the third step (Manage),
  3. Scroll down and click the Add Scopes button:
  4.  In the Define Scope dialog box, add the wb_geo scope for geographic data:
  5. Repeat the process to add wb_eco scope to the API.
  6. Now you can see both scopes available for the API. Click the + Scope button next to the /countries resource to assign its scope:
  7. Pick Geographic data for /countries and Economic data for /indicators:
  8. That’s it: we defined two new scopes and applied them to two different REST resources. Now click Save and Publish to update the API:

Generate scope-limited OAuth token

Now if you open the API in Developer Portal’s API Console, you will see two things: resources have notes about the scopes they need and attempts to invoke them with a regular OAuth key fail:

To generate an OAuth token with the OAuth scope included:

  1. In Developer Portal (a.k.a. API Store), click Applications,
  2. In the application list, click the application which you used to subscribe to the API (for example, DefaultApplication),
  3. Click the Production Keys tab,
  4. Scroll down to the Scopes section, select the scopes you want (for example, Geographic data), and click the Re-generate button (I picked “-1” as the validity period to have a non-expiring token):
  5. Now if you go back to the API, you can use the new token and successfully invoke the API:

Adding Roles

If you want to limit scope access to particular groups of users, you follow the same procedure but this time also list the roles when adding your scopes. For example, in the screenshot below, I am limiting the wb_geo scope access to users in the researches role:

Multiple endpoints per API

Dynamic Endpoint functionality of API Cloud allows you to dynamically pick the backend to which each call is routed based on the call’s properties.

For example, suppose you have an API that has two resources /countries and /regions:

And suppose the actual implementation of the functionality is at two different backends. /countries is implemented by first.backend.url and /regions by something.different.url.

Fear not, this is fairly easy to implement with API Cloud. You simply need to select Dynamic Endpoint as the Endpoint Type and upload the In Flow sequence that defines the rules to route the traffic:

In our sample scenario, the In Flow sequence might look similar to this:

<sequence name=”dynamic_ep” trace=”disable” xmlns=”http://ws.apache.org/ns/synapse“>
    <switch source=”get-property(‘To’)”>
        <case regex=”.*/countries/.*”>
            <property name=”service_ep” value=”https//first.backend.url“/>
        </case>
        <case regex=”.*/regions/.*”>
            <property name=”service_ep” value=”https://something.different.url“/>
        </case>
        <!– add endpoints as needed –>
        <default>
            <property name=”service_ep” value=”http://some.default.url”/>
            <!–default endpoint if required. However there should be a matching resource–>
        </default>
    </switch>
    <header name=”To” expression=”get-property(‘service_ep’)”></header>
    <property expression=”get-property(‘service_ep’)” name=”ENDPOINT_ADDRESS”></property>
    <!–Please note that “ENDPOINT_ADDRESS” (additional) property is defined here in order to populate
    destination address for statistics (API Usage by Destination). –>
</sequence>

You can obviously define more complex rules if needed.

Do you have multiple backend services that need to become a single API? Dynamic Endpoints can get you going!

 

Now with WebSockets

WSO2 API Cloud now fully supports publishing WebSocket APIs. WebSocket is a TCP-based protocol that is a part of the HTML5 specification, enables full-duplex communications and streaming, and reduces network traffic and delays.

In API Cloud, you can now treat WebSockets just the same way as you treat regular HTTP protocols. It is just another option when you add a new API:

The wizard then guides you through the rest of the process so you can define your policies and make the WebSocket endpoint fully managed.

If you need details, just read this API Manager tutorial that covers the functionality: Create a WebSocket API – now this page applies to API Cloud as well.

Categories

Recent Posts

Most Popular Posts