Hello there,
Probably you are familiar with other Oracle developer tools and frameworks like APEX and ADF. But maybe you are less aware that Oracle entered into the Javascript rumble with the Oracle Javascript Extension Toolkit. Oracle JET is a modular Javascript framework or toolkit formed by several popular Javascript libraries like knockout or jquery. One stand-out feature of the framework is its comprenhensive component library of components, the JET Cookbook. There are a lot of nice articles for getting started (see below) but perhaps you can find the best materials in the Massive Open Online Course (MOOC).
And what nowadays combines very well with Javascript? Yes, you are right, REST, and guess what? With ORDS you have the possibility of "exposing" your relational models (stored in an Oracle Database, what else? :) via REST services. Last but not least we want to expose our services in a secured manner and control who can a. For this we could think in use some authorization framework like OAUTH2. In this entry I want to show you how you can access ORDS services from a JET client using OAUTH2 as the protocol for authorization.
The Implicit Autorization Grant
The first thing to do is to define which authorization grant is the most suitable for this architecture? OAUTH2 defines 4 types of authorization grants. As our client is a javascript application the most suitable for us is the implicit one. I do like this definition of the implicit authorization grant from oracle-base.com: the implicit flow is a three-legged process that requires user interaction. The user accesses a URL in a browser, which prompts for credentials. Once authenticated, the browser is redirected to a specified page with an access token as one of the parameters in the URL. That access token is used to authenticate calls to protected resources. The below diagram, borrowed from the oracle documentation explains quite well this flow:
Register OAUTH2 client in the ORDS service
For this example we will take the deployment service of one of our previous articles, SSO for Oracle REST DataServices. We need to register our JET application as a OAUTH2 client of our service:
| BEGIN OAUTH.CREATE_CLIENT( p_name => 'lurodrig-implicit-client-for-deployment-table', p_grant_type => 'implicit', p_owner => 'Example Inc.', p_description => 'Sample for demonstrating Implicit Flow', p_redirect_uri => 'https://test-mwod-examples.web.cern.ch/?root=deployments', p_support_email => 'lurodrig@cern.ch', p_support_uri => 'http://cern.ch/', p_privilege_names => 'crud-operations-on-deployment-table' ); COMMIT; END; |
We can find here the description of this OAUTH.CREATE_CLIENT function. Two parameters are specially important:
- p_redirect_uri: ORDS will send to this endpoint the OAUTH access token that will be used by the client to access the protected service. In our case the JET application.
- p_privileges_names: tells ORDS which protected service our client wants to access. Remember that for our deployment service we create a privilege named crud-operations-in-deployment-table.
We have to grant our client with the role associated to the privilege that represents the protected service:
| BEGIN OAUTH.GRANT_CLIENT_ROLE( 'lurodrig-implicit-client-for-deployment-table', 'crud-deployments'); COMMIT; END; |
Oracle JET client
If the user has not a valid the session the flow is like this:
- Users request the JET application
- The JET application makes a HTTP request to the service
- The service responds JET with a 401 unauthorized
- JET redirect to the OAUTH Authorization Endpoint. Our JET application has to include three query parameters in the URL:
- response_type: the value must be token.
- client_id: you can query the information of your registered clients in the database with select * from user_ords_clients;
- state: this parameter is not mandatory but highly recommended. Your application must generate an unguessable value. This value works as a session id and its purpose is to avoid Cross Site Request Forgery attacks. Our client should "memorize" this value.
- The ORDS server (Weblogic) wants to authenticate the user, so the user will be challenged for his/her credentials. How this happens depends on the authenticator(s) configured on the Weblogic server side see SSO for Oracle REST DataServices.
- User authenticates
- If this is the first time that this user access the application an approval screen will pop-up.
- User approves
- After approval ORDS server will send back the response to the p_redirect_uri of the client (JET application).
- Tthe client will take the access_token from the reponse and include it as the authorization bearer token header. The client also should verify the state parameter.
- JET application displays the page.
You can find the source code of our client here. In this example I did not make use of the Oauth.js class like in this blog entry from Geertjan (BTW thanks!). The reason was that I wanted to keep the code as much didactic as possible and focus in the different OAuth interactions.
Note: the project includes a simple Dockerfile (thanks Liana for your post!).
Hope it helps and have a nice coding day!
Luis