How to Ensure the Security of Your APIs

Securing APIs

Objectives:

• Define API security requirements.

• Use security schemes to apply resource and method level policies.

• Define custom security scheme for APIs.

• Apply an OAuth2.0 external provider policy to resource methods.

Define a Custom Security Scheme for an API

To define a custom security scheme for your API, you will:

• Create a custom security scheme file.

• Reference the custom security scheme in the main RAML API definition.

• Apply the security scheme to certain resource methods.

Create a security scheme file:

1. Return to API designer.

2. In the file browser section, click the + icon in the Files header section.

3. Select "New folder" and, in the Add new folder dialog box, enter the name as "securitySchemes."

4. Click "Create."

5. Click the + icon next to the securitySchemes folder and select "New file."

6. In the Add new file dialog box, select the file type as Security Scheme and rename the file as
   "customTokenSecurity.raml."

7. Click "Create."

Define a custom security scheme:

In the RAML editor, go to the line that contains type node and press space bar after the colon.

In the shelf below the editor, click x-{other}.

Replace {other} with customToken.

Add a new line below the type node.

In the shelf, click description. Type the value of the description node as  :. This security scheme validates requests to the API using a token provided in the request header.

Press enter to add a new line.

In the shelf, click  describedBy .

In the shelf, click "headers."

Click "Authorization," then "description."

Type the value of the description node as  :. This header should contain a valid security token.

Press enter to add a new line. In the shelf, click "type," then "string." Reference the custom security scheme file in the main API definition.

In the file browser, select acme-banking-api.raml. Go to the empty line after the line that references the traitsLibrary file. Add two new lines below it. Remove the indentation in the second new line created. From the shelf, click securitySchemes .

In the new line, type:  customTokenSecurity: !include securitySchemes/customTokenSecurity.raml .

Apply the custom security scheme to all the resource methods in the API:

Go to the empty line before the /customers resource and press enter. In the shelf, click securedBy .

In the shelf, click customTokenSecurity . Press enter to add a new line.

In API Console, click the top left menu icon. Click GET for the /customers resource. Locate the Headers section of the Request and verify that you can see the Authorization header
field listed.

Note: Go to any other resource method and notice the Authorization header added to all the
resource methods by adding to the root of the RAML definition. Custom security schemes like
the customTokenSecurity are not supported for testing using the Try It option.

Consume an OAuth2.0 Security Scheme for an API and Secure API Resources

You will define a security scheme to secure API resources using OAuth2.0. You will:

• Consume an OAuth2.0 security scheme fragment file.

• Reference the OAuth2.0 security scheme in the RAML API definition.

• Apply the security scheme in the API resource methods.

Consume an OAuth2.0 security scheme fragment file:

Return to API designer. In the file browser section, click the Exchange dependencies icon.

Click the + icon next to the Dependencies header. In the Consume API Fragment dialog box, locate Training: OAuth2.0 Security Scheme and check the box.

Click Add Dependency.

Reference the OAuth 2.0 security scheme inside a RAML API Specification:

In the file browser section, click acme-banking-api.raml ;if the file is not open in the RAML editor. Locate the customTokenSecurity include statement and add a new line below it. In the new line, type: oauth2_0: !include .

In the file browser section, expand the exchange_modules folder to locate the OAuth2.raml
security scheme file. Click the menu icon next to the file name and click Copy path to clipboard.

In the RAML editor, paste the path to the traits file after the !include keyword.

Note: If you imported the OAuth2.raml file from the studentFiles folder into a traits folder, include the path as securitySchemes/OAuth2.raml.

Secure the resource methods that update bank customer and account information with the OAuth2.0 security scheme:

In the /{customer_id} nested resource patch method, add a new line below the line that contains the displayName node. In the shelf, click securedBy .

In the shelf, click  oauth2_0 .

In API Console, click the top left menu icon. Click the GET method link for the /customers resource. Scroll to the Request Headers section and verify that you can see an Authorization header.

Click the "Try it" button. Select the Authorization and verify that you need to fill the Auth data to send a request.