Backend apps

What is the flow's technical basis?

App ID implements the OAuth 2.0 and the OIDC spec, which uses bearer tokens for authentication and authorization. These tokens are formatted as JSON Web Tokens, which are digitally signed and contain claims that describe the subject that is being authenticated and the identity provider. The APIs of your application are protected by access and identity tokens. Clients that need access to your APIs can authenticate with the identity provider through App ID in exchange for these tokens. The claims in the tokens must be validated to grant access to the protected APIs.

For more information about how tokens are used in App ID, see Understanding tokens.

What does the flow look like?

1. A client makes a POST request to the App ID authorization server to obtain an access token. A POST request generally takes the following form:

   POST /oauth/v4/<tenantID>/token HTTP/1.1
   Content_type: application/x-www-form-urlencoded
   Authorization header = "Basic" + base64encode(<clientID>:<secret>)
   FormData = <grantType>
   

2. If the client meets the qualifications, the authorization server returns an access token.

3. The client sends a request to the protected resource. Requests can be sent in multiple ways, depending on which HTTP client library you're using but a request generally takes the following form:

   curl -H 'Authorization: Bearer <accessToken>' 
   <https://my-protected-resource.com>
   

4. The protected resource or API validates the token. If the token is valid, access to the resource is granted for the client. If the token cannot be validated, access is denied.

For information about how to configure your app to use Liberty for Java, see Quick start: Liberty for Java backend apps tutorial.

Before you begin

Before you get started with the Node.js SDK, you must have the following prerequisites.

• An instance of App ID
• NPM version 4 or higher
• Node version 6 or higher

Installing the Node.js SDK

1. Add the App ID Node.js SDK to your app's package.json file.

   "dependencies": {
      "ibmcloud-appid": "^7.0.0"
   }
   

2. Run the following command.

   npm install
   

Initializing the Node.js SDK

1. Obtain your oauth server url.

   1. Navigate to the Service Credentials tab of the App ID dashboard.
   2. If you don't already have a set of credentials, click New credential and then click Add to create a new set. If you do, skip this step.
   3. Click the View credentials toggle to see your information.
   4. Copy your oauth server url to use in the next step.

2. Initialize the App ID passport strategy as shown in the following example.

   var express = require('express'); 
   var passport = require('passport');
   var APIStrategy = require('ibmcloud-appid').APIStrategy; 
   passport.use(new APIStrategy({ oauthServerUrl: "<oauthServerUrl>" })); 
   var app = express();
   app.use(passport.initialize());
   

Securing the API with the API Strategy

The following snippet demonstrates how to use ApiStrategy in an Express app to protect the /protected GET API.

If your Node.js app runs on IBM Cloud and is bound to your instance of App ID, there's no need to provide the API strategy configuration. The App ID configuration obtains the information by using the VCAP_SERVICES environment variable.

 app.get('/protected_resource', passport.authenticate('APIStrategy.STRATEGY_NAME', { session: false }), function(request, response){
   console.log("Security context", request.appIdAuthorizationContext);
   response.send(200, "Success!");
   }
);

When the tokens are valid, the next middleware in the request chain is called and the appIdAuthorizationContext property is added to the request object. The property contains the original access and identity tokens and the decoded payload information of the tokens.