Oracle® Fusion Middleware
Part 1. API Gateway as an OAuth server

Client applications that send OAuth requests to the API Gateway’s Authorization Server must be registered with the Authorization Server. This chapter describes the registry used to store these client applications, and how to manage them using a REST API-based HTML interface. This topic also includes details on the relational database schema, and SSL commands used for the example client applications.

	Note
	This topic assumes that you have already performed the steps described in Set up API Gateway OAuth 2.0. These include enabling the OAuth endpoints, importing sample applications, and migrating existing client applications.

Every client application that sends OAuth requests to the API Gateway's OAuth Authorization Server must be registered with the Client Application Registry. The API Gateway provides the Client Application Registry web-based HTML interface for managing registered client applications. If you have API Manager installed, the Client Application Registry is available in the API Manager web-based interface. The API Gateway also provides the Client Application Registry REST API to enable you to manage registered clients on the command line.

Access the Client Application Registry web interface

You can access the Client Application Registry web interface at the following URL:

https://localhost:8089

The default username/password is admin/changeme.

You can select a client registration entry to update its details. For example, you can configure APIs, user sharing, API keys, credentials, quota plans, and scopes by expanding the appropriate link at the left:

By default, the Client Application Registry is backed by an embedded Apache Cassandra database.

The API Gateway includes sample Jython client applications for all supported OAuth flows in the following directory your API Gateway installation:

INSTALL_DIR/samples/scripts/oauth

To run a sample script, open a UNIX shell or DOS command prompt in the following directory:

INSTALL_DIR/samples/scripts

Windows

For example, run the following command:

run.bat oauth\implicit_grant.py

UNIX/Linux

For example, run the following command:

sh run.sh oauth/implicit_grant.py

API Gateway can store generated authorization codes and access tokens in its caches, in an embedded database, or in a relational database. The Authorization Server issues tokens to clients on behalf of a Resource Owner to use when authenticating subsequent API calls to the Resource Server. These issued tokens must be persisted so that subsequent client requests to the Authorization Server can be validated.

The following figure shows the OAuth stores in Policy Studio:

The Authorization Server can cache authorization codes and access tokens depending on the OAuth flow. The steps for adding an authorization code cache are similar to adding an access token cache.

The Authorization Server offers the following persistent storage options for access tokens and authorization codes:

The following figure shows these options in Policy Studio:

The Purge expired tokens every setting enables you to configure the time in seconds that a background process polls the cache or database looking for expired access/refresh tokens or authorization codes.

Store in a relational database

To store access tokens or authorization codes in a relational database, perform the following steps:

1. Create the supporting schema required for the storage of access tokens, refresh tokens, and authorization codes using the SQL commands in $VDISTIR\system\conf\sql\<DBMS>\oauth-server.sql where <DBMS> is the database management system being used. Schema are provided for Microsoft SQL Server, MySQL, Oracle, and IBM DB2.

2. Right-click Access Token Stores in the Policy Studio tree, and select Add Access Token Store.

3. In the dialog that enables you to choose the persistence type, select Store in a database, and select the browse button to display a database configuration dialog.

4. Complete the database configuration details. The following example uses a MySQL instance named oauth_db. For more details, see the API Gateway User Guide.

For more details, see the section called “Relational database-backed Client Application Registry”.

An OAuth scope is a text string used to control access to resources. The resource that the scope is associated with determines the meaning of the scope. For example, if a vehicle_data scope is associated with a particular resource, and a client application is associated with the vehicle_data scope, the client application will have access to that resource. Client applications and resources can have multiple OAuth scopes.

You can configure the scopes that a client application can access in the Client Application Registry web interface. You can specify scopes as free-form text or choose from a list of known configured scopes. You can also select a scope as a default scope for client applications. Default scopes are used when an authorization or token request does not contain scopes. The full list of scopes (default and non-default) represent the list of scopes that can be included in an authorization or token request.

You can manage scopes in the Client Application Registry web interface by expanding OAUTH SCOPES:

	Note
	The example default scopes provided with the API Gateway are URL-based. However, you can specify any text string for an OAuth scope (for example, customer_details or readonly).

When an authorization code or access token request is received from a client application, the API Gateway OAuth access token filters check that the scopes in the message match the scopes configured for the client application. If no scopes are provided in the message, the filter creates an access token for the scopes that are configured as default. The scope for which the access token was created is checked against the list of available scopes in the Client Application Registry web interface. This list is generated from the scopes defined in Validate Access Token filter in the server configuration. For more details on this filter, see Validate access token.

Important

You can also specify OAuth scopes using selectors (for example, use ${http.request.verb} to map HTTP GET and PUT requests). However, the Client Application Registry web interface does not display selectorized scopes in the list of available scopes. This is because selectorized scopes in the Validate Access Token filter cannot be evaluated at registration time. The administrator must therefore find out about any selectorized scopes to be applied to resources at runtime. If a scope must be conifigured using a selector, the administrator must find out exactly which selector to specify in the scope. For more details on selectors, see the API Gateway User Guide.

By default, the Client Application Registry Key Property Store (KPS) is backed by an Apache Cassandra database. The Client Application Registry KPS can also be backed by a relational database such as Oracle, MySQL, IBM DB2, or Microsoft SQL Server. For more details, see the Key Property Store User Guide, available from Oracle support.

    +---------------+--------------+------+-----+---------+-------+
    | Field         | Type         | Null | Key | Default | Extra |
    +---------------+--------------+------+-----+---------+-------+
    | id            | varchar(255) | NO   | PRI | NULL    |       |
    | auth_request  | blob         | NO   |     | NULL    |       |
    | client_id     | varchar(255) | NO   |     | NULL    |       |
    | expiry_time   | datetime     | NO   |     | NULL    |       |
    | token         | blob         | NO   |     | NULL    |       |
    | refresh_token | varchar(255) | YES  |     | NULL    |       |
    | user_auth     | varchar(255) | NO   |     | NULL    |       |
    | user_name     | varchar(255) | NO   |     | NULL    |       |
    +---------------+--------------+------+-----+---------+-------+

    +--------------+--------------+------+-----+---------+-------+
    | Field        | Type         | Null | Key | Default | Extra |
    +--------------+--------------+------+-----+---------+-------+
    | token_id     | varchar(255) | NO   | PRI | NULL    |       |
    | auth_request | blob         | NO   |     | NULL    |       |
    | expiry_time  | datetime     | NO   |     | NUL     |       |
    | token        | blob         | NO   |     | NULL    |       |
    | user_name    | varchar(255) | NO   |     | NULL    |       |
    +--------------+--------------+------+-----+---------+-------+

    +---------------+--------------+------+-----+---------+-------+
    | Field         | Type         | Null | Key | Default | Extra |
    +---------------+--------------+------+-----+---------+-------+
    | id            | varchar(255) | NO   | PRI | NULL    |       |
    | authorization | blob         | NO   |     | NULL    |       |
    | expiry_time   | datetime     | NO   |     | NULL    |       |
    +---------------+--------------+------+-----+---------+-------+

The following example openssl command shows generating a client application certificate and private key:

$ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mykey.pem 
-out mycert.pem
Generating a 1024 bit RSA private key
...................................................................
...........++++++
.....++++++
writing new private key to 'mykey.pem'
-----
You are about to be asked to enter information that will be incorporated 
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank. 
For some fields there will be a default value.
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MA
Locality Name (eg, city) []:Newton
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Oracle
Organizational Unit Name (eg, section) []:API Gateway
Common Name (eg, YOUR name) []:SampleConfidentialApp
Email Address []:support@widgits.com