Using the Proxy in a secure data store
Starting up the Proxy
The Oracle NoSQL Database Proxy can be started on a secure data store using the following steps.
- A secure proxy connection should be bootstrapped. Before you start up the proxy,
you need to create a bootstrap user in the secure data store for the proxy to
bootstrap its security connection. In SQL shell, the following command will
create a bootstrap user for the proxy. See Developers Guide for
getting started with SQL
commands.
sql-> CREATE USER <proxy_user> IDENTIFIED BY "<proxy_password>";
where,proxy_user
is the user name.proxy_password
is the password for theproxy_user
.
Note:
The default privilege is sufficient for a bootstrap user. It is not recommended to grant admin privilege or any other additional privileges to the bootstrap user.
Note:
Any user-supplied name can be given for the bootstrap user.
- Create a directory
./proxy
where the proxy related files can be stored. - Create a login file
./proxy/proxy.login
for the bootstrap user with the following information in it.
where,oracle.kv.auth.username=<proxy_user> oracle.kv.auth.pwdfile.file=proxy.passwd oracle.kv.transport=ssl oracle.kv.ssl.trustStore=client.trust
proxy.passwd
is the file to store the password value of theproxy_user
user.client.trust
is the certificate trust file obtained from the kvstore deployment.
See Create users and configure security with remote access to know how to generate the
proxy.passwd
andclient.trust
files in kvstore client machine. In this case, the proxy runs as a kvstore client. These files must exist in order for theproxy.login
to work properly. - Create a
certificate.pem
file andkey-pkcs8.pem
file for the proxy and driver to configure and establish a secure communication. If the Java driver is used, thedriver.trust
file should also be generated. See Generating Certificate and Private Key for the Oracle NoSQL Database Proxy in the Security Guide. - Use the following command to start up the proxy for a secure data
store:
where,java -jar lib/httpproxy.jar \ -storeName <kvstore_name> \ -helperHosts <kvstore_helper_host> \ [-hostname <proxy_host>] \ [-httpsPort <proxy_https_port>] \ -storeSecurityFile proxy/proxy.login \ -sslCertificate certificate.pem \ -sslPrivateKey key-pkcs8.pem \ -sslPrivateKeyPass <privatekey_password> \ [-verbose true]
kvstore_name
is the data store name obtained from the data store deployment. See ping.kvstore_helper_host
is the data store's helper host:port list obtained from the data store deployment. See Obtaining a KVStore Handle in the Java Direct Driver Developer's Guide.proxy_host
is the hostname of the machine to host the proxy service. If the proxy is to be accessed from machines other than the one on which it is started this should be the hostname of the machine running the proxy. This parameter is optional and defaults tolocalhost
which means that the proxy will only be available from the machine running the proxy.proxy_https_port
is the port on which the proxy is watching for requests on its host machine. This is an optional parameter and defaults to 443.Note:
Use of port 80 may require additional privileges, depending on your machine.proxy.login
is the security login file generated in the earlier step for accessing the secure kvstore.certificate.pem
is the certificate file generated in the previous step.key-pkcs8.pem
is the private key file generated in the previous step.privatekey_password
is the password for the encryptedkey-pkcs8.pem
file.
Note:
The proxy start-up only accepts private key file in PKCS#8 format. If your private key is already in PKCS#8 (start with -----BEGIN ENCRYPTED PRIVATE KEY----- or -----BEGIN PRIVATE KEY-----), you don't need any additional conversion. Otherwise, you can use OpenSSL to do the conversion.
The Oracle NoSQL Database Java Driver contains the jar files that enables an application to communicate with the Oracle NoSQL Database Proxy. You can connect to the proxy using the following steps.
- Create a user for the driver which is used by the application
to access the data store through the
proxy.
where, thesql-> CREATE USER <driver_user> IDENTIFIED BY "<driver_password>" sql-> GRANT READWRITE TO USER <driver_user>
driver_user
is the username anddriver_password
is the password for thedriver_user
user. In this example, the userdriver_user
is grantedreadwrite
role, which allows the application to perform only read and write operation. See Configuring Authorization in the Security Guide.Note:
If the user needs to create, drop, or alter tables or indexes, thedriver_user
should be granteddbadmin
role, which allows the application to perform DDL operations.sql-> GRANT DBADMIN TO USER <driver_user>
- Install the Oracle NoSQL Database Java Driver in the application's
classpath and use the following code to connect to the
proxy.
where,String endpoint = "https://<proxy_host>:<proxy_https_port>"; StoreAccessTokenProvider atProvider = new StoreAccessTokenProvider("<driver_user>","<driver_password>".toCharArray()); NoSQLHandleConfig config = new NoSQLHandleConfig(endpoint); config.setAuthorizationProvider(atProvider); NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);
proxy_host
is the hostname of the machine to host the proxy service. This should match the proxy host you configured earlier.proxy_https_port
is the port on which the proxy is watching for requests on its host machine. This should match the proxy https port configured earlier.driver_user
is the driver username. This should match the user created in the previous step.driver_password
is the password of the driver user.
- Start-up the application program and set the
driver.trust
file's path to the Java trust store by using the following command. This is required as the proxy is already set up using the certificate.pem
andkey-pkcs8.pem
files.java -Djavax.net.ssl.trustStore=driver.trust \ -Djavax.net.ssl.trustStorePassword=<password of driver.trust> \ -cp .:lib/nosqldriver.jar application_program
The
driver.trust
contains thecertificate.pem
orrootCA.crt
certificate. If the certificatecertificate.pem
is in a chain signed by a trusted CA that is listed inJAVA_HOME/jre/lib/security/cacerts
, then you don't need to append Java environment parameter-Djavax.net.ssl.trustStore
in the Java command.
The on-Premises configuration requires a running instance of the Oracle NoSQL database. In addition a running proxy service is required.
REQUESTS_CA_BUNDLE
environment
variable:
$ export REQUESTS_CA_BUNDLE=
<path-to-certificate>/certificate.pem:$REQUESTS_CA_BUNDLE
or borneo.NoSQLHandleConfig.set_ssl_ca_certs()
.
borneo.kv.StoreAccessTokenProvider
.from borneo import NoSQLHandle, NoSQLHandleConfig
from borneo.kv import StoreAccessTokenProvider
#
# Assume the proxy is secure and running on localhost:443
#
endpoint = 'https://localhost:443'
#
# Create the AuthorizationProvider for a secure store:
#
ap = StoreAccessTokenProvider(user_name, password)
#
# create a configuration object
#
config = NoSQLHandleConfig(endpoint).set_authorization_provider(ap)
#
# set the certificate path if running a secure store
#
config.set_ssl_ca_certs(<ca_certs>)
#
# create a handle from the configuration object
#
handle = NoSQLHandle(config)
The on-Premises configuration requires a running instance of the
Oracle NoSQL database. In addition a running proxy service is required. In this
case, the Endpoint
config parameter should point to the NoSQL
proxy host and port location.
InsecureSkipVerify
to instruct the client to
skip verifying server's certificate, or specify the CertPath
and ServerName
that used to verify server's certificate and
hostname.import (
"fmt"
"github.com/oracle/nosql-go-sdk/nosqldb"
"github.com/oracle/nosql-go-sdk/nosqldb/httputil"
)
...cfg:= nosqldb.Config{
Endpoint: "https://nosql.mycompany.com:8080",
Mode: "onprem",
Username: "testUser",
Password: []byte("F;0s2M0;-Tdr"),
// Specify InsecureSkipVerify
HTTPConfig: httputil.HTTPConfig{
InsecureSkipVerify: true,
},
// Alternatively, specify the CertPath and ServerName
// HTTPConfig: httputil.HTTPConfig{
// CertPath: "/path/to/certificate-used-by-server",
// ServerName: "nosql.mycompany.com",
// set to the "CN" subject value from the certificate
// },
}
client, err:=nosqldb.NewClient(cfg)
iferr!=nil {
fmt.Printf("failed to create a NoSQL client: %v\n", err)
return
}
deferclient.Close()
// Perform database operations using client APIs.
// ...
Your application will connect and use a running NoSQL database via the proxy service.
To connect to the proxy in secure mode, in addition to communication endpoint,
you need to specify user name and password of the driver user. This information
is passed in Config#auth
object under kvstore
property and can be specified in one of 3 ways as described below.
const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
const client = new NoSQLClient({
endpoint: 'https://myhost:8081',
auth: {
kvstore: {
user: 'John',
password: johnsPassword
}
}
});
This
option is less secure because the password is stored in plain text in
memory.
{
"user": "<Driver user name>",
"password": "<Driver user password>"
}
Then
you may reference this credentials file as
following:const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
const client = new NoSQLClient({
endpoint: 'https://myhost:8081',
auth: {
kvstore: {
credentials: 'path/to/credentials.json'
}
}
});
credentials.json
in the configuration
file used to create NoSQLClient
instance.{
"endpoint": "https://myhost:8081",
"auth": {
"kvstore": {
"credentials": "path/to/credentials.json"
}
}
}
const NoSQLClient = require('oracle-nosqldb').NoSQLClient;
const client = new NoSQLClient('/path/to/config.json');
Your application will connect and use a running NoSQL database via the proxy service.
To connect to the proxy in secure mode, in addition to communication endpoint,
you need to specify user name and password of the driver user. This information
is passed in the instance of KVStoreAuthorizationProvider
and
can be specified in any of the ways as described below.
var client = new NoSQLClient(
new NoSQLConfig
{
Endpoint = "https://myhost:8081",
AuthorizationProvider = new KVStoreAuthorizationProvider(
userName, // user name as string
password) // password as char[]
});
This
option is less secure because the password is stored in plain text in memory for
the lifetime of NoSQLClient
instance. Note that the password is
specified as char[] which allows you to erase it after you are finished using
NoSQLClient.
{
"UserName": "<Driver user name>",
"Password": "<Driver user password>"
}
Then
you may use this credentials file as
following:var client = new NoSQLClient(
new NoSQLConfig
{
Endpoint: 'https://myhost:8081',
AuthorizationProvider = new KVStoreAuthorizationProvider(
"path/to/credentials.json")
});
NoSQLClient
instance:{
"Endpoint": "https://myhost:8081",
"AuthorizationProvider": {
"AuthorizationType": "KVStore",
"CredentialsFile": "path/to/credentials.json"
}
}
var client = new NoSQLClient("/path/to/config.json");
Note that in config.json
the authorization provider is
represented as a JSON object with the properties for
KVStoreAuthorizationProvider
and an additional
AuthorizationType property indicating the type of the authorization provider,
which is KVStore for the secure on-premise store.
The Oracle NoSQL Database Spring Data SDK contains the files that enable a Spring Data application to communicate with the proxy.
Install the Java driver in the application's classpath. Use the following code to connect to the proxy.
NosqlDbConfig
object. You can use the
StoreAccessTokenProvider
class with the username and
password of the Oracle NoSQL Database cluster. The
StoreAccessTokenProvider
class configures the Spring Data
Framework to connect and authenticate to a secure Oracle NoSQL Database
store.
import com.oracle.nosql.spring.data.config.AbstractNosqlConfiguration;
import com.oracle.nosql.spring.data.config.NosqlDbConfig;
import com.oracle.nosql.spring.data.repository.config.EnableNosqlRepositories;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import oracle.nosql.driver.kv.StoreAccessTokenProvider;
@Configuration
@EnableNosqlRepositories
public class AppConfig extends AbstractNosqlConfiguration {
@Bean
public NosqlDbConfig nosqlDbConfig() {
AuthorizationProvider authorizationProvider;
authorizationProvider = new StoreAccessTokenProvider(user, password);
return new NosqlDbConfig("http://<proxy_host:proxy_http_port>", authorizationProvider);
}
}
proxy_host
is the hostname of the machine to host the proxy service.proxy_http_port
is the port on which the proxy is watching for requests on its host machine.