geode-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "ASF GitHub Bot (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (GEODE-2854) GEODE REST API Docs Missing Authentication
Date Thu, 15 Jun 2017 21:50:00 GMT

    [ https://issues.apache.org/jira/browse/GEODE-2854?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16051115#comment-16051115
] 

ASF GitHub Bot commented on GEODE-2854:
---------------------------------------

Github user joeymcallister commented on a diff in the pull request:

    https://github.com/apache/geode/pull/583#discussion_r122320206
  
    --- Diff: geode-docs/rest_apps/setup_config.html.md.erb ---
    @@ -29,162 +31,233 @@ All Geode REST interface classes and required JAR files are distributed
as a WAR
     
     where _install-dir_ is the server installation directory and _n.n.n_ is a version number.
     
    -To enable the developer REST API service in Apache Geode, set the `start-dev-rest-api`
Geode property to `true` when starting a data node using either `gfsh` or the ServerLauncher
API. Setting this property to true on a data node will start up an embedded Jetty server and
deploy the REST developer API WAR file.
    +- [Enabling the REST API](#setup_config_enabling_rest)
    +- [Starting the REST API Service](#setup_config_starting_rest)
    +- [Implementing Authentication for the REST API](#setup_config_implementing_auth)
    +- [Programmatic Startup](#setup_config_implementing_auth)
    +
    +# <a id="setup_config_enabling_rest" class="no-quick-link"></a>Enabling the
REST API
    +
    +The REST API service for application development runs only on data nodes; you cannot
run the service on a locator.
    +
    +To enable the Developer REST API service on a given server, set the `start-dev-rest-api`
property
    +to `true` when starting the data node to start an embedded Jetty server and deploy the
Developer REST
    +API WAR file on that node. Use either the `gfsh start server` command or the ServerLauncher
API to enable this property.
     
    -**Note:**
    -The REST API service for application development runs only on servers; you cannot use
locators to host the developer Geode REST API services.
    +## Enabling the REST API on Multiple Nodes
     
    -You can have multiple REST enabled data nodes in a single distributed system. Each data
node should
    +You can configure multiple REST enabled data nodes in a single distributed system. Each
data node should
     have a separate host name and unique end point. To ensure that the data node is reachable
on a
    -machine with multiple NIC addresses, you can use `http-service-bind-address` to bind
an address to
    -the REST API service (as well as the other embedded web services such as Pulse).
    +machine with multiple NIC addresses, use `http-service-bind-address` to bind an address
to
    +the REST API service (as well as the other embedded web services, such as Pulse).
     
    -You can also configure the Developer REST API service to run over
    -HTTPS by enabling ssl for the `http` component in `gemfire.properties`
    -or `gfsecurity.properties` or on server startup:
    -See [SSL](../managing/security/ssl_overview.html) for details on configuring SSL parameters.
    -These SSL parameters apply to all HTTP services hosted on the configured server, which
can include the following:
    +You can configure the Developer REST API service to run over HTTPS by enabling SSL for
the `http`
    +component in `gemfire.properties` or `gfsecurity.properties`, or on server startup. 
See
    +[SSL](../managing/security/ssl_overview.html) for details on configuring SSL parameters.
 These SSL
    +parameters apply to all HTTP services hosted on the configured server, which can include
the
    +following:
     
     -   Developer REST API service
     -   Management REST API service (for remote cluster management)
     -   Pulse monitoring tool
     
    -The following procedure starts up a REST API service-enabled Geode deployment:
    +# <a id="setup_config_starting_rest" class="no-quick-link"></a> Starting
the REST API Service
     
    -1.  Configure PDX for your cluster. You must configure PDX if either or both of the following
conditions apply: 
    -    -   Application peer member caches will access REST-accessible Regions (resources)
with the `Region.get(key)`.
    -    -   Your deployment has persistent regions that must be available as resources to
the REST API.  To configure PDX in your cluster, perform the following steps:
    -        1.  Start up a locator running the [cluster configuration service](../configuring/cluster_config/gfsh_persist.html)
(enabled by default). For example: 
    +To start a REST API service-enabled Geode deployment, configure PDX serialization for
your
    +cluster, then start the service on one or more server nodes.
     
    -            ``` pre
    -            gfsh>start locator --name=locator1
    -            ```
    -        2.  If your deployment has application peer member caches (for example, Java
clients) that must also access REST-accessible Regions (resources), use the following gfsh
command:
    +## Configure PDX for your cluster
     
    -            ``` pre
    -            gfsh>configure pdx --read-serialized=true
    -            ```
    -        **Note:**
    -        You do not need to configure `--read-serialized=true` if no application peer
member caches are accessing the REST-accessible regions (resources) in your deployment.
    -        3.  If your deployment contains **persistent regions** that must be REST-accessible,
use the following gfsh command:
    +You must configure PDX if either or both of the following conditions apply: 
     
    -            ``` pre
    -            gfsh>configure pdx --disk-store
    -            ```
    -        This command sets `pdx` `persistent` equal to true and sets the disk-store-name
to DEFAULT. If desired, specify an existing disk store name as the value for `--disk-store`.
    -        4.  If both of the above cases apply to your deployment, then configure PDX with
the following single command:
    +-   Application peer member caches will access REST-accessible regions (resources) with
`Region.get(key)`.
    +-   Your deployment has persistent regions that must be available as resources to the
REST API.  
     
    -            ``` pre
    -            gfsh>configure pdx --read-serialized=true --disk-store
    -            ```
    +To configure PDX in your cluster, perform the following steps:
     
    -    After you have configured PDX for your caches, then proceed with starting up your
REST-enabled servers and other data nodes.
    +1.  Start up a locator running the [cluster configuration service](../configuring/cluster_config/gfsh_persist.html)
(enabled by default). For example: 
     
    -2.  Start a server node with the Geode property `start-dev-rest-api` set to `true`. 
    -    Optionally, you can also configure a `http-service-bind-address` and `http-service-port`
to
    -    identify the cache server and specific port that will host REST services. If you
do not specify
    -    the `http-service-port`, the default port is 7070. If you do not specify
    -    `http-service-bind-address`, the HTTP service will bind to all local addresses by
default.
    -    **Note:** If your application will be running in a VM (as when running in the cloud,
for example), it's good practice to specify `http-service-bind-address` and `http-service-port`
    -    so they will be publicly visible. The default values may not be visible outside the
VM in which the application is running.
    +    ``` pre
    +    gfsh>start locator --name=locator1
    +    ```
     
    -    For example:
    +2.  If your deployment has application peer member caches (for example, Java clients)
that must also access REST-accessible Regions (resources), use the following gfsh command:
     
         ``` pre
    -    gfsh>start server --name=server1 --start-rest-api=true \
    -    --http-service-port=8080 --http-service-bind-address=localhost
    +    gfsh>configure pdx --read-serialized=true
         ```
     
    -    Any server that hosts data, even a server acting as a JMX manager, can start the
developer REST API service. For example, to start the service on a server that is also a JMX
manager, you would run:
    +    **Note:**
    +    You do not need to configure `--read-serialized=true` if no application peer member
caches are accessing the REST-accessible regions (resources) in your deployment.
    +
    +3.  If your deployment contains **persistent regions** that must be REST-accessible,
use the following gfsh command:
    +
    +    ``` pre
    +    gfsh>configure pdx --disk-store
    +    ```
    +    This command sets `pdx` `persistent` equal to true and sets the disk-store-name to
DEFAULT. If desired, specify an existing disk store name as the value for `--disk-store`.
    +
    +4.  If both of the above cases apply to your deployment, then configure PDX with the
following single command:
     
         ``` pre
    -    gfsh>start server --name=server1  --start-rest-api=true \
    -    --http-service-port=8080 --http-service-bind-address=localhost \
    -    --J=-Dgemfire.jmx-manager=true --J=-Dgemfire.jmx-manager-start=true
    +    gfsh>configure pdx --read-serialized=true --disk-store
         ```
     
    -    Note that when started as a JMX Manager, the server will also host the Pulse web
application in the same HTTP service.
    +    After you have configured PDX for your caches, then proceed with starting up your
REST-enabled servers and other data nodes.
    +
    +## Start the REST API Service on One or More Servers
    +
    +To start the REST API service on a server, start a server node with the Geode property
`start-dev-rest-api` set to `true`. 
    +Optionally, you can also configure a `http-service-bind-address` and `http-service-port`
to
    +identify the cache server and specific port that will host REST services. If you do not
specify
    +the `http-service-port`, the default port is 7070. If you do not specify
    +`http-service-bind-address`, the HTTP service will bind to all local addresses by default.
    +
    +**Note:** If your application will be running in a VM (as when running in the cloud,
for example),
    +it is good practice to specify `http-service-bind-address` and `http-service-port` so
they will be
    +publicly visible. The default values may not be visible outside the VM in which the application
is
    +running.
    +
    +For example:
    +
    +```
    +gfsh>start server --name=server1 --start-rest-api=true \
    +--http-service-port=8080 --http-service-bind-address=localhost
    +```
    +
    +Any server that hosts data, even a server acting as a JMX manager, can start the Developer
REST API service. For example, to start the service on a server that is also a JMX manager,
you would run:
    +
    +```
    +gfsh>start server --name=server1  --start-rest-api=true \
    +--http-service-port=8080 --http-service-bind-address=localhost \
    +--J=-Dgemfire.jmx-manager=true --J=-Dgemfire.jmx-manager-start=true
    +```
    +
    +Note that when started as a JMX Manager, the server will also host the Pulse web application
in the same HTTP service.
    +
    +You may also need to specify a CLASSPATH to load any functions that need to be made available
to your REST services. For example:
     
    -3.  You may also need to specify a CLASSPATH to load any functions that need to be made
available to your REST services. For example:
    +```
    +gfsh>start server --name=server1 --start-rest-api=true \
    +--http-service-port=8080 --http-service-bind-address=localhost \
    +--classpath=/myapps/testfunctions.jar
    +```
    +
    +You can also specify these properties either upon server startup or in the server’s
gemfire.properties configuration file.
    +
    +```
    +gfsh>start server --name=serverX --server-port=40405 --cache-xml-file=cache-config.xml
\
    +--properties-file=gemfire.properties --classpath=/myapps/testfunctions.jar
    +```
    +
    +where gemfire.properties contains:
    +
    +```
    +http-service-port=8080
    +http-service-bind-address=localhost
    +start-dev-rest-api=true
    +```
    +
    +## Verify That The Service is Running
    +
    +Verify that the Geode REST API service is up and running. To validate this, you can perform
the following checks:
    +
    +1.  Test the list resources endpoint (this step assumes that you have regions defined
on your cluster):
     
         ``` pre
    -    gfsh>start server --name=server1 --start-rest-api=true \
    -    --http-service-port=8080 --http-service-bind-address=localhost \
    -    --classpath=/myapps/testfunctions.jar
    +    curl -i http://localhost:8080/geode/v1
         ```
     
    -4.  You can also specify these properties either upon server startup or in the server’s
gemfire.properties configuration file.
    +2.  Examine the server logs for the following messages:
     
         ``` pre
    -    gfsh>start server --name=serverX --server-port=40405 --cache-xml-file=cache-config.xml
\
    -    --properties-file=gemfire.properties --classpath=/myapps/testfunctions.jar
    +    [info 2017/06/13 13:48:14.090 PDT gfsec-server1 <main> tid=0x1] Initializing
Spring FrameworkServlet 'geode-mgmt'
    +    [info 2017/06/13 13:48:14.091 PDT gfsec-server1 <main> tid=0x1] FrameworkServlet
'geode-mgmt': initialization started
         ```
     
    -    where gemfire.properties contains:
    +3.  Open a browser and enter the following URL to browse the Swagger-enabled REST APIs:
     
         ``` pre
    -    http-service-port=8080
    -    http-service-bind-address=localhost
    -    start-dev-rest-api=true
    +    http://<http-service-bind-address>:<http-service-port>/geode/docs/index.html
         ```
     
    -5.  Verify that the Geode REST API service is up and running. To validate this, you can
perform the following checks:
    -    1.  Test the list resources endpoint (this step assumes that you have regions defined
on your cluster):
    +    where *http-service-bind-address* is the address and *http-service-port* is the port
number that you specified when starting the Development REST API service on the server. For
example, based on the server started in an earlier example, you would enter:
     
    -        ``` pre
    -        curl -i http://localhost:8080/gemfire-api/v1
    -        ```
    +    ``` pre
    +    http://localhost:8080/geode/docs/index.html
    +    ```
    +
    +If you did not specify these properties upon server startup or in `gemfire.properties`,
then use the
    +default of localhost and port 7070. See [Using the Swagger UI to Browse REST
    +APIs](using_swagger.html#concept_rlr_y3c_54) for more information.
    +
    +# <a id="setup_config_implementing_auth" class="no-quick-link"></a>Implementing
Authentication for the REST API
     
    -    2.  Examine the server logs for the following messages:
    +To turn on integrated security, start your servers and locators with the security-manager
property
    +set in your gemfire.properties file or on the gfsh command-line.
    +The following example uses the sample implementation that is included in the Geode source,
    +`org.apache.geode.examples.security.ExampleSecurityManager`.
     
    -        ``` pre
    -        [info 2014/06/12 14:56:52.431 PDT rest-test <localhost-startStop-1> tid=0x4d]

    -        (tid=11 msgId=8) Initializing Spring FrameworkServlet 'gemfire-api'[info 2014/06/12

    -        14:56:52.432 PDT rest-test <localhost-startStop-1> tid=0x4d] (tid=11 msgId=9)

    -        FrameworkServlet 'gemfire-api': initialization started
    -        ```
    +This implementation requires a JSON security configuration file which defines the allowed
users and their corresponding
    +permissions. (See the javadocs for `ExampleSecurityManager` for details on how to compose
the JSON file.)
    +Place a copy of the JSON security configuration file in the execution directory of each
security-enabled member, then
    +specify `--classpath=.` in the start command for each of those members.
     
    -    3.  Open a browser and enter the following URL to browse the Swagger-enabled REST
APIs:
    +To start a server using a username and password that are defined in that server's security
configuration, include the
    +`--user=username` and `--password=password` options in the server's start command:
     
    -        ``` pre
    -        http://<http-service-bind-address>:<http-service-port>/gemfire-api/docs/index.html
    -        ```
    +For example, suppose the JSON config file defines user "super-user" with password "1234567":
    +
    +```
    +gfsh>start server --name=server1 --start-rest-api=true \
    +--http-service-port=8080 --http-service-bind-address=localhost \
    +--J=-Dgemfire.security-manager=org.apache.geode.examples.security.ExampleSecurityManager
\
    +--classpath=. --user=super-user --password=1234567
    +```
     
    -        where *http-service-bind-address* is the address and *http-service-port* is the
port number that you specified when starting the Development REST API service on the server.
For example, based on the server started in step 2, you would enter:
    +To contact the server through the REST interface, you must provide the username and password.
Various REST GUI interfaces
    +provide different ways of accomplishing this. The `curl` command offers the `--user`
(or `-u`) option for this purpose,
    +where username and password are specified as a colon-separated pair:
     
    -        ``` pre
    -        http://localhost:8080/gemfire-api/docs/index.html
    -        ```
    +```
    +curl -i --user super-user:1234567 http://localhost:8080/geode/v1
    +```
    +
    +In a simple URL, such as in a browser address bar, the credentials can be given as a
prefix to the host name
    +in the form `username:password@`:
    +
    +```
    +http://super-user:1234567@localhost:8080/geode/v1
    +```
     
    -        If you did not specify these properties upon server startup or in `gemfire.properties`,
then use the default of localhost and port 7070. See [Using the Swagger UI to Browse REST
APIs](using_swagger.html#concept_rlr_y3c_54) for more information.
     
    -## Programmatic Startup
    +# <a id="setup_config_implementing_auth" class="no-quick-link"></a>Programmatic
Startup
     
     You can also start up and configure Geode REST services programmatically. For example:
    --- End diff --
    
    Change "start up and" to "start and"


> GEODE REST API Docs Missing Authentication
> ------------------------------------------
>
>                 Key: GEODE-2854
>                 URL: https://issues.apache.org/jira/browse/GEODE-2854
>             Project: Geode
>          Issue Type: Task
>          Components: docs
>            Reporter: Michael Martell
>            Assignee: Dave Barnes
>
> The REST API docs don't document how to do authentication. Looks like HEAD params "security-username"
and "security-password" are supported but undocumented in the REST API.
> There is a comment about REST auth in this link: https://geode.apache.org/docs/guide/11/managing/security/implementing_authentication.html
> Also, the docs seem to imply that you pass usr/passwd in the http headers such as 'security-username'
and 'security-password'. However, it only works using HTTP Basic Authentication, which Spring
must be translating on the server side into the 'security-username' and 'security-password'
params.



--
This message was sent by Atlassian JIRA
(v6.4.14#64029)

Mime
View raw message