Make your RESTful APIs Secured with OAuth2 - Basic, Simple and Easy Steps

Its been a while since my previous article. So, here is my first blog post of 2020. Oracle APEX has an out-of-box and declarative support to create RESTful Web Services using ORDS. Within no-time, you can build and publish your RESTful APIs. Use of ORDS has gradually increased with common standard across different technology strongly adopted via RESTful Web Services and JSON formatted input/output.

With the flexibility of data sharing across the technology or within application, we must also think of how secure my RESTful APIs are. We do believe in strong security of our applications using Authentication and Authorization. But, many times we miss the level of security we should implement in our RESTful APIs.

So, here is the very simple and basic steps to secure your ORDS RESTful APIs using OAuth2:

• We will use a default oracle.example.hr web service module to add OAuth2 for this blog.
• Navigate to SQL Workshop > RESTful Services.
• From the left side of tree - click on "Roles"
• Create new Role as - "MyHRRole"
• From the left side of tree - click on "Privileges"
• Create new Privilege as below
• Name = "HRAccess"
• Title = "HRAccess"
• Roles = "MyHRRole"
• Protected Modules = "oracle.example.hr"
• Now, test one of the method of your web service. It should give you following message.
• 401 Unauthorized
• Access to this resource is protected. Please Sign In to access this resource.
• So, till this step - we have secured the access. Now let's see how to provide the secured access.
• Create New Client
• Execute following script to create new client

BEGIN

  OAUTH.create_client(

    p_name            => 'HR Access Client',

    p_grant_type      => 'client_credentials',

    p_owner           => 'OracleExampleHR',

    p_description     => 'An example client created for my blog.',

    p_support_email   => 'jbosamiya@gmail.com',

    p_privilege_names => 'HRAccess'

  );

  COMMIT;

END;

• Grant Client to Role
• Execute following script to grant newly created client to role

BEGIN

  oauth.grant_client_role(p_client_name => 'HR Access Client',

                          p_role_name   => 'MyHRRole');

  COMMIT;

END;

• Check if record is created for Client ID and Secret using Following Query

SELECT id, client_id, client_secret FROM user_ords_clients WHERE name = 'HR Access Client';

• Generate encoded string of ClientID:ClientSecret
• Method 1: PL/SQL
• Use below query to get the encoded string

select UTL_RAW.CAST_TO_VARCHAR2(UTL_ENCODE.BASE64_ENCODE(UTL_RAW.CAST_TO_RAW('<client_id>:<client_secret>'))) 

  from dual;

• Method 2: JavaScript
• Execute below function from Browser Console to get the encoded string

window.btoa("<client_id>:<client_secret>");

• To make sure, you might want try both the method and it should generate same string output.

• Call Secured RESTful Web Service
• Execute /oauth/token web service to generate Bearer token
• Method = POST
• URL = https://<host>/<application name>/<schema alias>/oauth/token
• Header Parameters
• Name = Authorization
• Value = Basic <encoded string generated in previous step>
• Name = Content-Type
• Value = application/x-www-form-urlencoded
• Body Parameter
• Name = grant_type
• Value = client_credentials
• If everything is valid, it should given you following output

{"access_token":"ot9VLcCmTsW3mrSYqYgkFg","token_type":"bearer","expires_in":3600}

• Now, call HR web service and pass access token in request header
• Method = GET
• URL =  https://<host>/<application name>/<schema alias>/hr/employees/
• Header Parameters
• Name = Authorization
• Value = Bearer <Access Token generated in previous step>

That's it. You have just configured and executed OAuth2 Secured ORDS RESTful web service !!!

Now, start adding OAuth2 security to your unsecured RESTful APIs.

Some useful links to go next level:

• https://oracle-base.com/articles/misc/oracle-rest-data-services-ords-authentication
• https://www.jmjcloud.com/blog/simplifying-apex_web_service-oauth2-client-credentials

Hope this helps !!

Regards,

Jaydip Bosamiya