Skip to end of metadata
Go to start of metadata

Use the Repose 101 guide to walk you through the steps to install and configure Keystone authentication, distributed rate limiting, and metrics with Repose.

Environment setup

For this tutorial we are using Docker in Virtualbox to create an enclosed, platform-independent, development environment. We are running on an OS X Host, but this should work for any operating system.

  1. Install Virtualbox and Vagrant.
  2. Run the following commands:

    $ vagrant init precise32 http://files.vagrantup.com/precise32.box
    $ vagrant up
    $ vagrant ssh
    vagrant@precise32:~$ sudo apt-get install -y wget curl
    vagrant@precise32:~$ wget -O - http://repo.openrepose.org/debian/pubkey.gpg | sudo apt-key add -
    vagrant@precise32:~$ sudo sh -c 'echo "deb http://repo.openrepose.org/debian stable main" > /etc/apt/sources.list.d/openrepose.list'
    vagrant@precise32:~$ sudo apt-get update
    vagrant@precise32:~$ sudo apt-get install -y repose-valve repose-filter-bundle repose-extensions-filter-bundle
    vagrant@precise32:~$ sudo service repose-valve start ; sleep 1 ; sudo tail -f /var/log/repose/current.log
  3. Wait for the "... Repose ready" line, then press CTRL-C.

Installation

You can deploy Repose in a few ways. However, the Proxy Server (Valve) method is the recommended method of deployment. For more detailed information about installing Repose, see Installation.

Deployment strategyDescriptionRecommended use
Proxy Server (Valve)
  • Repose sits between the requester and the origin service.
  • Repose runs on a different port or a different host than the origin service.
If you want to run Repose separate from your application, use the Proxy Server (Valve) deployment strategy.
ROOT.war
  • Repose runs in the root context of the same application server as the origin service.
  • Repose runs on the same port and host as the origin service.
If you want to run Repose in the same container with your Java application, use the ROOT.war deployment strategy.
Docker
  • Docker can fully encapsulate Repose using a JAR deployment inside of a small, high performance VM. 

If you are comfortable with Docker and enjoy experimenting with trendy, new methods, use the Docker deployment strategy.

 

Initial configuration

The following steps will guide you through the necessary configurations for a basic Repose setup. For more detailed information, see Configuration.

1. Configure the container file.

Within the deployment-directory element, change the auto-clean attribute to true to allow Repose to clean the deployment directory of artifacts.

2. Configure the system model.

Within the endpoint element, configure your endpoint destination information.

3. Add filters and services.

Place the filters and services that you plan to use in the system model. See the standard filter order to ensure that the filters in your configuration are placed so that they interact correctly with each other.

4. Configure each filter and service.

Configure each filter and service that you have placed in the system model.  Read the individual component pages for specific configuration information on each filter or service.  

Configure the system model

The following steps will guide you through a basic configuration for the system model. Our configuration specifies only one Repose node, the SLF4J HTTP Logging filter, and a destination at port 80. For more detailed information, see system model.

1. Name each Repose cluster

Name each repose-cluster with a unique identifier or id. In the following example, we use only one repose-cluster.

2. Name each node 

Name each node within the cluster with a unique id. In the following example, we use only one node.

3. Add filters

Add the filter names that you will use within this Repose cluster. In the following example, we use only one filter, the SLF4J HTTP Logging filter.

4. Add services

Add the service names that you will use within this Repose cluster. In the following example, we are not using a service.

5. Add destination endpoint

Add your destination endpoint with the following information:

    • Name the endpoint with a unique id.
    • Define the endpoint protocol. (HTTP or HTTPS are valid values.)
    • Define the hostname with an IP address or a hostname.
    • Name the port that the endpoint is listening to for requests.

 

The following example shows a basic configuration for the system model.

/etc/repose/system-model.cfg.xml
<?xml version="1.0" encoding="UTF-8"?>

<!-- To configure Repose see: http://wiki.openrepose.org/display/REPOSE/Configuration -->
<system-model xmlns="http://docs.openrepose.org/repose/system-model/v2.0">
  <repose-cluster id="example">
    <nodes>
      <node id="repose_node1" hostname="localhost" http-port="8080"/>
      <!--
        <node id="repose_node2" hostname="other_repose_host" http-port="8080" https-port="8443"/>
      -->
    </nodes>
    <filters>   
    	<filter name="slf4j-http-logging" />	
    </filters>
	<services>
	</services>
    <destinations>
      <!-- Update this endpoint if you want Repose to send requests to a different service -->
      <endpoint id="example service" protocol="http" hostname="example.com" root-path="/" port="80" default="true"/>
    </destinations>
  </repose-cluster>
</system-model>

Configure authentication

Configure the Client Authentication filter by editing the client-auth-n.cfg.xml file.


1. Set Up Repose 
Configure Repose using either a cluster or a single instance configuration.

2. Add the Client Authentication filter 
Add the Client Authentication filter to your system model configuration. Place this filter below the logging and the normalization filters. If you are not using logging or normalization filters in your system model configuration, place the Client Authentication filter at the top of the filter chain.

3. Configure the Client Authentication filter 

 a.  Within the identity-service element:

    • Configure the administrator username and password for the authentication service that you interact with.
    • Configure the uri with the authentication endpoint.

 b. Within the openstack-auth element:

    • Set request-groups to false if you need only a single rate limit group that can be set to default, or if you populate the X-PP-Groups header in a different way. The default is true.
    • If token-cache-timeout is configured, the minimum between that value and the value provided by the identity service will be used. Roles will be cached as part of the token.

    • Adjust the cache time if necessary for group-cache-timeout. The default setting is 600,000 milliseconds (10 minutes). The Keystone service does not provide a TTL in the groups response, so you will need to adjust the group-cache-timeout if you do not want to use the default value.

 

In the following example, the system model is configured to perform basic authentication with the Client Authentication filter.

 

<?xml version= "1.0" encoding= "UTF-8" ?>
<client-auth xmlns= "http://docs.openrepose.org/repose/client-auth/v1.0" >
     <openstack-auth tenanted= "false" request-groups= "true" token-cache-timeout= "600000" group-cache-timeout= "600000"  
                     xmlns= "http://docs.openrepose.org/repose/client-auth/os-ids-auth/v1.0" > 
         <identity-service username= "admin_username" password= "admin_password" uri="https://identity.example.com/v2.0/"  />
       
		 <endpoints-in-header format= "XML" cache-timeout= "600000" identity-contract-version= "2" />
 
     </openstack-auth>
     <white-list>
         <uri-pattern uri-regex= "/application\.wadl$" />
     </white-list>
 
</client-auth>

Configure distributed rate limiting

Error rendering macro 'excerpt-include' : No link could be created for '_Distributed rate limiting configuration chunk'.

Test Keystone authentication

So you've created the configuration, and Repose appears to be working well, but how can you be sure? The following steps will guide you through the process of testing your Keystone authentication configuration.

  1. Send a Request with valid token
    Send a request to Repose with a valid auth token and check that it hits your API. If the request hits your API, skip to step 3.

     2.  Check the logs

          If the request does not hit your API, check the Repose logs to see if there are errors. 

    • If you receive a 401 error, the token is not valid. 
    • If you receive a 5xx error, that indicates that there is an issue with the communication between Repose and the authentication service or that Repose is improperly configured.

     3.  Send request with bad token

          Send a valid request with a bad token to Repose and look for a 401 error.

    • If your valid request that contains the bad token returns a 401, the authentication configuration is good.

     4.  Check the logs

          If your valid request that contains the bad token does not return a 401, check the Repose logs to see if there are errors. 

    • If you receive a 5xx error, that indicates that there is an issue with the communication between Repose and the authentication service or that Repose is improperly configured.

Read metrics

You can read metrics at any time by running JConsole. Repose reports metrics to JMX, and JConsole allows you to view the metrics. Currently, Repose reports metrics by default to JMX with no input or configuration required.

Alternatively, you can configure your metrics.cfg.xml file to report to other monitoring systems such as Graphite. In this case, you need to have a Graphite server set up to accept metrics.

Related articles