4.7 Securing RESTful Web Services

Define roles, privileges and OAuth Clients to ensure authentication and authorization are required for accessing RESTful web services.

To protect a RESTful web service, you need to:

• Create a role

• Create a privilege selecting the role and modules or resources to protect

To enable access to a protected RESTful service using the OAUTH2 Workflow, create an OAuth client using the role and privilege created for protecting the RESTful service.

The following sections provide information on how to create roles, privileges and OAuth clients:

• Managing Roles
• Managing Privileges
• Managing OAuth Clients
• Example: Creating an OAuth Client

See Also:

• REST Workshop Overview Video
• Tutorial for Protecting and Accessing Resources

4.7.1 Managing Roles

You can create, edit and delete roles for RESTful services in the Roles page.

To navigate to the Roles page, from the REST Overview page, click Roles in Objects, or from the menu in the header, select Security and then select Roles.

The actions available in the context menu are:

• Creating a Role
• Editing a Role
• Deleting a Role
• Viewing Assigned Privileges

See Also:

About Users and Roles in Oracle REST Data Services Developer's Guide.

4.7.1.1 Creating a Role

Create a role with a specific name. After the role is created, you can associate it with a privilege.

1. In the Roles page, click Create Role.
2. In the Role Name field, enter the name of the role to create.
3. Click Create.

   The new assigned role is displayed on the Roles page.

4.7.1.2 Editing a Role

This section describes how to edit a role.

1. In the Roles page, for the specific role, click Actions and select Edit.
2. Enter the changes required and click Save.

   For a description of the fields, see Creating a Role.

4.7.1.3 Deleting a Role

This section describes how to delete a role.

1. In the Roles page, for the specific role, click Actions and select Delete.

   You are prompted to confirm.

2. Click Yes to delete.

4.7.1.4 Viewing Assigned Privileges

This section describes how to view the privileges associated with a role.

In the Roles page, for the specific role, click Actions and select Details. The privilges assigned to the role are displayed.

4.7.2 Managing Privileges

You can create, edit and delete privileges for RESTful services in the Privileges page.

A privilege defines the set of roles, at least one of which an authenticated user must possess to access a RESTful service protected by a privilege.

To navigate to the Privileges page, from the REST Overview page, click Privileges in Objects, or from the menu in the header, select Security and then select Privileges.

The privilege attributes displayed by default in card view are shown in the following figure.

Description of the illustration privilege_card.png

The actions available in the context menu are:

• Creating a Privilege
• Editing a Privilege
• Deleting a Privilege

4.7.2.1 Creating a Privilege

This section describes how to create a privilege.

1. In the Privileges page, click Create Privilege.
2. Enter the following fields. The fields with an asterisk (*) are mandatory:
   • Label: Enter the name of the privilege in a way that it is easy to understand.
   • Name: Enter a unique name for the privilege.
   • Description: Enter a brief description of the purpose of the privilege.
   • Comments: Enter comments.
   • Roles: Enter one or more roles assigned to the privilege.
   • Protected Modules: Select the modules to protect.
   • Protected Resources: Instead of Protected Modules, use the Protect Resources tab to apply security based on a URI pattern.
3. Click Create.

   The new privilege is displayed on the Privileges page.

4.7.2.2 Editing a Privilege

This section describes how to edit a privilege.

1. In the Privileges page, for the specific privilege, click Actions and select Edit.
2. Make the required changes and click Save.

   For a description of the fields, see Creating a Privilege.

4.7.2.3 Deleting a Privilege

This section describes how to delete a privilege.

1. In the Privileges page, for the specific privilege, click Actions and select Delete.
2. You are prompted to confirm. Click Yes.

4.7.3 Managing OAuth Clients

Using OAuth 2.0-based authentication, you can ensure that your RESTful web services are accessed only by specific users or clients.

OAuth 2.0 is a standard Internet protocol that defines flows to provide conditional and limited access to a RESTful API. For more information, see OAuth-Based Authentication .

You can create, edit and delete OAuth Clients in the OAuth Clients page.

To navigate to the OAuth Clients page, from the REST Overview page, click Clients in Objects, or from the menu in the header, select Security and then select OAuth Client.

The OAuth Client attributes displayed by default in card view are shown in the following figure.

Description of the illustration oauth_card.png

The actions available in the context menu are:

• Creating an OAuth Client
• Editing an OAuth Client
• Deleting an OAuth Client

• Get Bearer Token: Provides the access token to call the RESTful service.

See Also:

Tutorial for Protectinng and Accessing Resources

4.7.3.1 Creating an OAuth Client

Creates the OAuth Client and grants the required roles and privileges.

1. In the OAuth Clients page, select Create OAuth Client.
2. Enter the following fields. The fields with an asterisk (*) are mandatory:
   • Name: Name of the client.
   • Description: Description of the purpose of the client.
   • Support URI: Enter the URI where end users can contact the client for support. Example: http:// www.myclientdomain.com/support/
   • Support Email: Enter the email where end users can contact the client for support.
   • Roles: Select roles to be granted.
   • Allowed Origins: Add the list of URL prefixes.
   • Privileges: Select privileges that the client wants to access.
3. Click Create.

   The OAuth Client registered is displayed on the OAuth Clients page.

   The Client ID and Client Secret values represent the secret credentials for the OAuth client. Click Show/Hide to see the values.

   Test the secured REST service endpoint using a REST client or the cURL command line tool.

See Also:

Tutorial for Protecting and Accessing Resources in Oracle REST Data Services Developer's Guide

4.7.3.2 Editing an OAuth Client

This section describes how to edit an OAuth Client.

1. In the OAuth Clients page, for the specific client, click Actions and select Edit.
2. Edit the required fields and click Save.

   For a description of the fields, see Creating an OAuth Client.

4.7.3.3 Deleting an OAuth Client

This section describes how to delete an OAuth Client.

1. In the OAuth Clients page, for the specific client, click Actions and select Delete.
2. You are prompted to confirm. Click Yes.

4.7.4 Example: Creating an OAuth Client

This section describes how to create an OAuth Client using an example.

Create an OAuth Client for the created module "example" in Example: Inserting a Record using a POST Handler. The endpoint for the RESTful service is http://xyz.us.comp.com:1234/ords/pdbdba/example/emp/.

Prerequisites

Create a role named HR Admin. See Creating a Role

Create a privilege named Example.HR. See Creating a Privilege

1. In the OAuth Clients page, click Create OAuth Client.
2. Enter the following fields:

   • Enter Name, Description, Support URI and Support Email for your OAuth Client.

   • In the Roles tab, add the created role (HR Admin).

   • In the Privileges tab, add the created privilege (Example.HR).

   • Click Create.

   The new OAuth Client card appears on the OAuth Clients page.

3. Using cURL, test the service endpoint without OAuth credentials.

   curl --location --request POST --header "Content-Type: application/json" 
   --data '{"DEPTNO": 55, "DEPTNAME": "Sales", "DEPTLOC": "Australia" }' 
   'http://xyz.us.comp.com:1234/ords/pdbdba/example/emp/'

   You see an error.

4. Test the endpoint with OAuth credentials:

   1. To get an access token, select Get Bearer Token from the context menu in the OAuth Client card.

      
      Description of the illustration example_oauth.png

      The OAuth Token dialog appears. Use Copy to Clipboard to copy the token.

      
      Description of the illustration bearer_token.png

   2. In cURL, use the bearer access token in the following statement to request the resource:

      curl -H "Content-Type: application/json" -H "Authorization: Bearer AMccwlnt99gm9kxDs_w1DA" --location --request POST --data 
      '{"DEPTNO": 55, "DEPTNAME": "Sales", "DEPTLOC": "Australia"}' 'http://xyz.us.comp.com:1234/ords/pdbdba/example/emp/'

   The output shows:

   {"deptno":55,"dname":"Sales","loc":"Australia","links":[{"rel":"collection",
   "href":"http://xyz.us.comp.com:1234/ords/pdbdba/example/emp/"}]}

5. In the SQL page, you can verify the new record that has been inserted in the DEPT table by using the following statement:

   SELECT * FROM DEPT;