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
• Examples

See Also:

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

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.

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.

   Show code: Select this option to view the PL/SQL code equivalent of the Create Role slider. You can copy and execute this PL/SQL code in the worksheet to perform the same action that occurs when you click Create in the Create Role slider.

3. Click Create.

   The new assigned role is displayed on the Roles page.

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.

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.

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.

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

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.

   Show code: Select this option to view the PL/SQL code equivalent of the Create Privilege slider. You can copy and execute this PL/SQL code in the worksheet to perform the same action that occurs when you click Create in the Create Privilege slider.

3. Click Create.

   The new privilege is displayed on the Privileges page.

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.

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.

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
• Exporting an OAuth Client

• Get Bearer Token: Provides the access token to call the RESTful service for Client Credentials and Implicit OAuth grant types. See Creating an OAuth Client Using the Client Credentials Grant Type

• Auth Details: Displays the Unique Value and Authorization URI for the Auth Code OAuth grant type. See Creating an OAuth Client Using the Auth Code Grant Type

See Also:

Tutorial for Protectinng and Accessing Resources

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:

   Client Definition tab

   • Grant type: Select the authorization grant type. The options are Client_Cred, Auth Code, or Implicit.

     For more information about these grant types, see OAuth Flows in Oracle REST Data Services Developer's Guide.

   • Name: Name of the client.
   • Description: Description of the purpose of the client.
   • Redirect URI: Enter the client-controlled URI to which redirect containing an OAuth access token or error will be sent.
   • 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.
   • Logo: Upload your logo in JPG, BMP or SVG file format. Ensure that the logo is less than 100 KB in size.
   • Roles: Select roles to be granted.
   • Allowed Origins: Add the list of URL prefixes.
   • Privileges: Select privileges that the client wants to access.

   Show code: Select this option to view the PL/SQL code equivalent of the Create OAuth Client panel. You can copy and execute this PL/SQL code in the worksheet to perform the same action that occurs when you click Create in the Create OAuth Client panel.

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

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.

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.

Exporting an OAuth Client

This section describes how to export an OAuth Client.

1. In the OAuth Clients page, for the specific client, click Actions and select Export.
2. In the OAuth Client panel, click the Copy icon or Download to copy or download the OAuth Client information.

Examples

This section provides a few examples on creating an OAuth client with different grant types.

Topics:

• Creating an OAuth Client Using the Client Credentials Grant Type
• Creating an OAuth Client Using the Auth Code Grant Type

Creating an OAuth Client Using the Client Credentials Grant Type

This section describes how to create an OAuth Client using the Client Credential grant type.

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:
   • In the Grant type field, select CLIENT_CRED.

   • Enter Name, Description, Redirect URI, 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;

Creating an OAuth Client Using the Auth Code Grant Type

This section describes how to create an OAuth Client using the Auth Code grant type.

1. In the OAuth Clients page, click Create OAuth Client.
2. Enter the following fields:
   • In the Grant type field, select Auth Code.

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

   • In the Roles tab, add the relevant roles.

   • In the Privileges tab, add the relevant privileges.

   • Click Create.

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

3. In the OAuth Client card, click the Actions icon and select Auth Details.
   The Unique Value and Authorization URI appears.
4. In the Authorization URI field, click the Open in New Tab icon. A new window is displayed with an Unauthorized error message along with a Sign In link.
5. Click Sign in and enter your login credentials again.
6. You are prompted to approve the request to access the protected URI. Click Approve.