edit

Gluu Gateway UMA Tutorial#

Overview#

This tutorial covers UMA grant security using the GLUU-UMA-PEP plugin and the Gluu Server. There are two different ways to apply UMA security, with Claim-Gathering-flow and without Claim-Gathering-flow. The demo is a Python CGI script that can be deployed on any CGI-enabled server.

Parties#

UMA Overview

Flow#

Flow chart

Plugin Configuration#

Note

Plugin configuration can be done either via REST calls or via the Gluu Gateway web interface.

Configure plugin on Service, Route and Global.

There are several possibilities for plugin configuration with services and routes. More information is available in the Kong docs, and configuration detail descriptions are available in the Gluu Gateway docs.

Applications and their ports:

Port Description
1338 Gluu Gateway Admin GUI
8001 Kong Admin API
8000 Kong Proxy Endpoint
443 Kong SSL Proxy Endpoint. Kong by default provide 8443 port for SSL proxy but during setup it change into 443.
8443 OXD Server

The following tutorial demonstrates plugin configuration for a Service. Follow the steps below.

Add Service#

Register your upstream API as a Service. For more details, see the Gluu UMA PEP service docs.

For this demo, you'll need to add two different services with different names. You can use this live test API, https://jsonplaceholder.typicode.com.

  • Service(claim-gathering)

    • name: claim-gathering
    • URL: https://jsonplaceholder.typicode.com
    • let's call it claim_service
  • Service(non-claim-gathering):

    • name: non-claim-gathering
    • URL: https://jsonplaceholder.typicode.com
    • let's call it non_claim_service

Add Route#

For a proxy, you need to add a Route to the Service. For more details, see the Gluu UMA PEP route docs.

  • Route1

    • Add the first route in claim_service with gathering.example.com as the host.
  • Route2:

    • Add the second route in non_claim_service with non-gathering.example.com as the host.

Configure Plugin on Service#

Configure Gluu-UMA-PEP with UMA scopes and resources. See more details in the Service Plugin docs.

  • Resource registration for claim_service. claim_gathering

  • Resource registration for none_claim_service. claim_gathering

UMA Client Registration#

Create an OP Client using the GG UI, or you can use the oxd server API for client registration. Take a look at UMA client registration section for more details. Let's call this OP client consumer_op_client

Once you have an OP client, use its client_id for Kong Consumer registration. .

Call UMA protected API without Claim Gathering#

To use UMA Grant access with no policy in a scope, you need to set the umaGrantAccessIfNoPolicies flag in CE oxAuth JSON configuration to true. Then, do the following:

  • Get a resource ticket
  curl -X GET http://gg.example.com:8000/<YOUR_PATH>
      --Header "Host: non-gathering.example.com"

When you make this call, you'll receive a ticket in the WWW-Authenticate header with a permission ticket.

  • Get a client access token using consumer credentials.

 curl -X POST https://gg.example.com:8443/get-client-token
    --Header "Content-Type: application/json"
    --data '{"client_id":"<CONSUMER_OP_CLIENT_ID>", "client_secret":"<CONSUMER_OP_CLIENT_SECRET>", "op_host":"<YOUR_OP_HOST>","scope":[<YOUR_SCOPES>]}'
When you make this call, you'll receive a Consumer access token.

  • Get an RPT token

  curl -X POST https://gg.example.com:8443/uma-rp-get-rpt
      --Header "Authorization: Bearer <CONSUMER_ACCESS_TOKEN>"
      --Header "Content-Type: application/json"
      --data '{"oxd_id": "<CONSUMER_OP_CLIENT_OXD_ID>","ticket":"<PERMISSION_TICKET>"}'
When you make this call, you'll receive an RPT access token.

  • Call the UMA-protected API
  curl -X GET http://gg.example.com:8000/<YOUR_PATH>
      --Header "Authorization: Bearer <YOUR_RPT>"
      --Header "Host: non-gathering.example.com"

UMA flow with Claims Gathering#

Prerequisites#

  • Enable UMA RPT Polices & UMA Claims Gathering

    There is one uma_rpt_policy included in the script. During authorization, it checks County=US and City=NY. If you want to change the value, then you can update this script or add your own new script. For more details, take a look at Gluu CE Documentation. uma_rpt_policy uma_claim_gatering_policy

  • UMA scope with Authorization Policy

    uma_scope

  • Update the consumer_op_client with claim_redirect_uris in CE. Add your CGI script URL.

    config_claim_url

Authentication#

  • Get a resource ticket
  curl -X GET http://gg.example.com:8000/<YOUR_PATH>
      --Header "Host: gathering.example.com"

When you make this call, you'll receive a ticket in the WWW-Authenticate header with a permission ticket.

  • Get a client access token using consumer credentials.
 curl -X POST https://gg.example.com:8443/get-client-token
    --Header "Content-Type: application/json"
    --data '{"client_id":"<CONSUMER_OP_CLIENT_ID>", "client_secret":"<CONSUMER_OP_CLIENT_SECRET>", "op_host":"<YOUR_OP_HOST>","scope":[<YOUR_SCOPES>]}'

When you make this call, you'll receive a Consumer access token.

  • Get a need_info ticket
  curl -X POST https://gg.example.com:8443/uma-rp-get-rpt
      --Header "Authorization: Bearer <CONSUMER_ACCESS_TOKEN>"
      --Header "Content-Type: application/json"
      --data '{"oxd_id": "<CONSUMER_OP_CLIENT_OXD_ID>","ticket":"<PERMISSION_TICKET>"}'

When you make this call, you'll get a need_info ticket and a claims gathering URL for user redirection. You have to add your claims redirect URI as a URL query parameter. You may need to add your claims redirect URL to your client configuration in CE.

The next step is to request a claim gatering URL in the browser and add country and city data. Per default uma_rpt_policy, you need to enter US in Country and NY in City. If you change location values in the script, enter corresponding values here.

If all claims are correct, the Gluu Server will redirect you to the claim redirect URI with a new permission ticket.

  • Get an RPT token with a permission ticket
  curl -X POST https://gg.example.com:8443/uma-rp-get-rpt
      --Header "Authorization: Bearer <CONSUMER_ACCESS_TOKEN>"
      --Header "Content-Type: application/json"
      --data '{"oxd_id": "<CONSUMER_OP_CLIENT_OXD_ID>","ticket":"<NEW_PERMISSION_TICKET>"}'

When you make this call, you'll receive an RPT access token.

  • Call an UMA protected API
  curl -X GET http://gg.example.com:8000/<YOUR_PATH>
      --Header "Authorization: Bearer <YOUR_RPT>"
      --Header "Host: gathering.example.com"

Demo#

The Demo is a Python CGI script. You need to put it in a CGI-enabled web server. The script is divided into 3 parts:

  • index.py - Main script
  • helper.py - REST calls and HTML template
  • config.py - Custom configuration

Download the Demo from the Gluu-Gateway repository.

By default, the UMA without claim gathering flow is executed.

If you want to execute UMA with claims gathering flow, add claim=true parameter to your URL.

Deploy#

Since we are going to write a Python CGI script for simplicity, we first need to get a working web server to act as the Relying Party (RP). Install Apache on the host rp.server.com. This tutorial is using Ubuntu 16.04 LTS. First, install the Apache web server:

# apt-get update
# apt-get install apache2
# ln -s /etc/apache2/mods-available/cgi.load /etc/apache2/mods-enabled/

You will use Python's requests module to interact with oxd's REST API:

# apt-get install python-requests

Put all 3 files in /usr/lib/cgi-bin and give them 755 permission.

# chmod 755 index.py helper.py config.py

If you set the configuration as above then you can send a request to

  1. With claim gathering flow: <your-server.com>/cgi-bin/index.py?claim=true
  2. Without claim gathering flow: <your-server.com>/cgi-bin/index.py

Configuration#

Use the config.py file to add your configuration

Properties Description
gg_admin_url Gluu Gateway kong admin URL
gg_proxy_url Gluu Gateway kong proxy URL
oxd_host OXD server URL
ce_url CE OP Server URL
api_path your API path which you register during plugin configuration
host_with_claims Kong Router object's host which you configure for claim gathering flow. As per above configuration, its value is gathering.example.com.
host_without_claims Kong Router object's host which you configure for without claim gathering flow. As per above configuration, its value is non-gathering.example.com.
client_oxd_id, client_id, client_secret Consumer OP Client credentials
claims_redirect_url Claims redirect URL. As per above configuration, it is <your-server.com>/cgi-bin/index.py.