Build an IBM Cloud Function API and use IBM Cloud App ID to protect it with the IBM Cloud API Gateway
Over the past decade, running software on a network has shifted from monolithic applications deployed on gigantic servers to microservices packaged within containers to individual functions deployed on a serverless platform like IBM Cloud Functions.
This shift in deployment models has also significantly changed how middleware needs to be configured and deployed in support of these application components. With the growing adoption of serverless, the deployment of middleware has shifted from global handlers within application code to placing middleware components in the network itself.
Authentication and authorization are key components for any web app, and APIs built as cloud functions are no exception. This article will show you how to build an IBM Cloud Function API and then use IBM Cloud App ID to protect the function with the IBM Cloud API Gateway—no code change required. Best of all, you can get started for free!
Step 1: Configure App ID
Let’s begin by creating and configuring an App ID service instance.
Navigate to the IBM Cloud catalog.
Search for App ID using the catalog search bar, or select the Security and Identity category on the left.
- Click on the App ID catalog entry:
Select the desired deployment region (this tutorial requires either Dallas, London, or Frankfurt).
- Click Create at the bottom of the screen. The App ID dashboard will be displayed:
Now that App ID is provisioned, it’s time to configure an OAuth2 client.
- Navigate to the Application section from the left-hand navigation bar:
- Click the Add application button to launch the application creation dialog:
- Enter an application name (this name can be anything that you want):
- An entry for the application should now be visible in the Applications table. Select the View credentialsdropdown to expose the credentials for your application. Record these, as we’ll use them in Step 4:
Step 2: Create a cloud function
If you’ve already built an IBM Cloud Function, feel free to skip to Step 3. Now that our App ID service is ready, let’s create the function that we want to protect.
Open the IBM Cloud Functions dashboard in a new tab.
Click Start creating from the getting started page.
- Select Create action:
- Give your action a name (e.g., get-customers) and select Node.js 10 from the Runtime field, then click Create at the bottom of the page:
The function editor will open, containing the “Hello world” sample code. Delete the boilerplate and replace it with the following code:
- Click Save. The editor will look something like the following:
Let’s test the action before proceeding to make sure it works as intended.
Click the Invoke button near the upper-right. The resulting output should look similar to this:
If everything looks good, proceed to Step 3.
Step 3: Expose your function as an API
It’s time to connect everything together with an API. We can accomplish this within the Cloud Functions dashboard.
Select the APIs option from the Functions left-hand navigation, or use this direct link.
- If this is the first time you’re creating a Cloud Functions API, a brief welcome page will appear. Click the Create a Cloud Functions API button:
We can accept many of the defaults, but let’s configure a few options within our new API.
Enter an API name (e.g., “Customer management API”).
Enter a more human-friendly base path (e.g., “/crm”). Next, we need to attach our function to an operation.
Click the Create operation button. The operation configuration dialog will appear.
Provide a path for the operation (e.g., “/customers”).
- Ensure the function that we created in Step 1 is selected in the dropdown. The dialog should now look like this:
- Click Create. A row representing the operation should appear in the Operations table:
Finally, let’s secure our API using the App ID instance created previously.
Scroll down the page and find the section for OAuth user authentication.
Click the toggle switch labeled Require users to authenticate via OAuth social login.
Select IBM Cloud App ID as the provider.
- In the App ID service dropdown, select the instance created in Step 1. The resulting configuration should look something like this:
- Click the Save & expose button at the bottom of the page. The API summary panel should appear. The base URL of the API is displayed near the top:
If you attempt to invoke the API now, it should return a 401 Unauthorized response, since you didn’t provide a valid access token.
Step 4: Get an access token from App ID
Now it’s time to use the App ID application credentials we saved back in Step 1.
We need to generate an access token to authenticate ourselves to the API gateway, which should then allow us to invoke the cloud function. An access token is typically a short-lived credential that is generated from a set of known credentials (e.g., username and password). By using an access token, users can protect their actual credentials from third parties while still being trusted by a remote system. If you want to learn more about how access tokens work, take a look at the App ID documentation.
Generate an access token
From the App ID application credentials, replace the corresponding values in the following `curl` command, then execute it.
The result from the curl command should include an access token that looks something like this:
Copy the token to your clipboard for use in Step 5.
Step 5: Invoke the API
Now that we have a valid access token, we can use it to invoke our customer list API, which is backed by a cloud function.
Copy the following curl command into your terminal.
Replace <access_token> with the token copied in Step 4.
Execute the curl.
The output from the invocation should be a JSON formatted list of customers from our cloud function:
Now, only users with a valid access token from your unique instance of App ID can invoke your application logic. To prove the security of the network flow, try some of these scenarios:
If you change even one character of the access token, what happens?
If you create a new App ID service instance and use a token from it, what’s the result?
Wait for the original token to expire, then try invoking the API again. Does it work?
In this article, you leveraged three IBM Cloud services to build a modern web API powered by Cloud Functions, App ID, and the API gateway. Using this approach with your next project could save you time and money. Since cloud functions only run when invoked, they cost nothing when idle and scale infinitely. App ID takes the pain out of setting up user authentication, whether using an enterprise identity provider (such as Active Directory or Ping Identity) or connecting to popular social authentication services provided by Google, Facebook, and others. The API gateway ties everything together with a highly-performant and resilient proxy capable of protecting backend resources from unauthorized access.
Question and feedback
- If you have technical questions about App ID, post your question on Stack Overflow and tag your question with ibm-appid.
- For questions about the service and getting started instructions, use the IBM Developer Answers forum. Include the appid tag.
- Open a support ticket in the IBM Cloud menu.
- Reach out directly to the development team on Slack!
To get started with App ID, check it out in the IBM Cloud Catalog.