Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

How to Ensure the Security of Your APIs

DZone's Guide to

How to Ensure the Security of Your APIs

Learn how to implement security measures for your APIs by following the steps in this detailed tutorial on defining a custom OAuth2.0 security scheme.

Free Resource

The Integration Zone is brought to you in partnership with Cloud Elements.  What’s below the surface of an API integration? Download The Definitive Guide to API Integrations to start building an API strategy.

Securing APIs

Image title

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.

Image title

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."Image title

  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}.

Image title

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.

Image title

In the shelf, click  describedBy .

In the shelf, click "headers."

Image title

Click "Authorization," then "description."

Image title

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 .

Image title

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

Image title

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 .

Image title

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

Image title

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.

Image title

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.

Image title

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.

Image title

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.

Image title

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 .

Image title

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.

Image title

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

Image title

The State of API Integration Report provides data from the Cloud Elements platform and will help all developers navigate the recent explosion of APIs and the implications of API integrations to work more efficiently in 2017 and beyond.

Topics:
mulesoft ,raml api ,mule ,api ,api security ,integration

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}