ORDS OAuth2 Authentication: Securing Your REST APIs Step by Step

Why OAuth2 for ORDS

Deploying ORDS REST APIs without authentication means anyone who discovers the URL can read and modify your data. OAuth2 Client Credentials flow is the standard way to secure machine-to-machine API access in ORDS. It provides token-based authentication with automatic expiration, scoped access through privileges, and no need to send passwords with every request.

Setting Up OAuth2 in ORDS

The process involves creating a role, a privilege, an OAuth client, and associating them together:

-- Step 1: Create a role
BEGIN
    ORDS.CREATE_ROLE('api_consumer_role');
    COMMIT;
END;

-- Step 2: Create a privilege and protect your module
BEGIN
    ORDS.CREATE_PRIVILEGE(
        p_name        => 'api_read_privilege',
        p_role_name   => 'api_consumer_role',
        p_label       => 'API Read Access',
        p_description => 'Allows reading data through REST APIs'
    );

    ORDS.CREATE_PRIVILEGE_MAPPING(
        p_privilege_name => 'api_read_privilege',
        p_pattern        => '/api/v1/*'
    );
    COMMIT;
END;

-- Step 3: Create an OAuth client
BEGIN
    OAUTH.CREATE_CLIENT(
        p_name            => 'external_app',
        p_grant_type      => 'client_credentials',
        p_owner           => 'API Admin',
        p_description     => 'External application access',
        p_support_email   => 'admin@example.com',
        p_privilege_names => 'api_read_privilege'
    );

    -- Grant the role to the client
    OAUTH.GRANT_CLIENT_ROLE(
        p_client_name => 'external_app',
        p_role_name   => 'api_consumer_role'
    );
    COMMIT;
END;

Getting the Client Credentials

SELECT id, name, client_id, client_secret
  FROM user_ords_clients
 WHERE name = 'external_app';

Using the Token

# Step 1: Get a token
curl -X POST https://myserver/ords/hr/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -u "client_id:client_secret"

# Response: {"access_token":"abc123...","token_type":"bearer","expires_in":3600}

# Step 2: Use the token
curl -H "Authorization: Bearer abc123..." \
     https://myserver/ords/hr/api/v1/products/

Token Management

Tokens expire after a configurable period (default 3600 seconds). Client applications should cache the token and request a new one only when the current token expires or returns a 401. Never hard-code tokens in application code. Store client_id and client_secret in secure credential stores or environment variables.