Gluu UMA Auth and UMA PEP#

Overview#

The UMA Auth and UMA PEP are used for client authentication and to enforce the presence of UMA scopes for access to resources protected by the Gateway. UMA scopes and policies are defined in an external UMA Authorization Server (AS) -- in most cases the Gluu Server. The Gateway and AS leverage the oxd UMA middleware service for communication.

There are two plugins for OAuth security.

gluu-uma-auth: Authenticate client by UMA RPT Token. The plugin priority is 998.
gluu-uma-pep: Authorization by UMA Scope security. The plugin priority is 995.

The plugin supports two tokens:

Default Access Token: The plugin will authenticate the token using introspection.
Access Token as JWT: The plugin will authenticate the token using JWT verify. Currently, three algorithms are supported: RS256, RS384 and RS512.

Configuration#

Plugins can be configured at the Service, Route or Global level. There are several possibilities for plugin configuration with services and routes. For information on plugin precedence, read the Kong docs.

Important

During plugin configuration, the GG UI creates a new OP Client if the oxd ID is left blank. However, if configuring with the Kong Admin API, existing client credentials must be used.

Important

konga.log also shows the curl commands for all API requests to Kong and oxd made by the Konga GUI. This curl command can be used to automate configuration instead of using the web interface.

Service Level#

Add Service

Follow these step to add Service using GG UI:
- Click SERVICES on the left panel
- Click on + ADD NEW SERVICE button
- Fill the form by your upstream service details
Add Route

Route is recommended to reach at kong proxy. Follow these steps to add route:
- Click on service name or edit button of above added service
- Click ROUTES
- Click the + ADD ROUTE button
- Fill the form by routing details. Check kong docs for more routing capabilities here.
Add Plugins

Follow these steps to add plugins:
- Click SERVICES on the left panel
- Click on name or edit button
- Click on Plugins
- Click on + ADD PLUGIN button
- You will see Gluu UMA Auth & PEP title and + icon in pop-up
- Click here for next step

Route Level#

Add Service

Follow these step to add Service using GG UI
- Click SERVICES on the left panel
- Click on + ADD NEW SERVICE button
- Fill the form by your upstream service details
Add Route

Follow these steps to add route:
- Click on service name or edit button of above added service
- Click ROUTES
- Click the + ADD ROUTE button
- Fill the form by routing details. Check kong docs for more routing capabilities here.
Add Plugins

Follow these steps to add plugins:
- Click ROUTES on the left panel
- Click on route id/name or edit button
- Click on Plugins
- Click on + ADD PLUGIN button
- You will see Gluu UMA Auth & PEP title and + icon in pop-up
- Click here for next step

Global Plugin#

A global plugin will apply to all services and routes.

Follow these steps to add plugins:

Click Plugins on the left panel
You will see Gluu UMA Auth & PEP title and + icon in pop-up
Click here for next step

Add Plugin#

You will see Gluu UMA Auth & PEP title and + icon in pop-up.

uma-auth-pep-plugin-add

Clicking on the + icon will bring up the below form. Check here for all the parameter descriptions.

uma-auth-pep-form

Add Plugin using Kong API#

Note

Use OXD API for client registration.

Configuration for gluu-uma-auth. Check here for parameter descriptions.

$ curl -X POST \
  http://<kong_hostname>:8001/plugins \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "gluu-uma-auth",
  "config": { <parameters> },
  "route": { "id": "<kong_route_object_id>" }
}'

Configuration for gluu-uma-pep. Check here for parameter descriptions.

$ curl -X POST \
  http://<kong_hostname>:8001/plugins \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "gluu-uma-pep",
  "config": { <parameters> },
  "route": { "id": "<kong_route_object_id>" }
}'

The above example is passing route property which will add the plugin for route level.

Request	For
`"route": { "id": "<kong_route_object_id>" }`	Plugin will add for kong route object
`"service": { "id": "<kong_service_object_id>" }`	Plugin will add for kong service object
	If you not pass any `service` or `route`, it will add globally. Plugin will execute for any routes and services

Parameters#

Here is a list of all the parameters which can be used in this plugin's configuration.

Gluu-UMA-Auth#

field	Default	Description
op_url		The URL of your OP server. Example: https://op.server.com
oxd_url		The URL of your oxd server. Example: https://oxd.server.com
oxd_id		The ID for an existing client used to introspect the token. If left blank, a new client will be registered dynamically
client_id		An existing client ID used to get a protection access token to access the introspection API. Required if an existing oxd ID is provided.
client_secret		An existing client secret, used to get a protection access token to access the introspection API. Required if an existing oxd ID is provided.
anonymous		An required string (consumer Id) value to use as an “anonymous” consumer if authentication fails. You need to set the Anonymous consumer because it is used to bypass gluu-uma-auth authentication and help to get the ticket from gluu-uma-pep.
pass_credentials	pass	It allows 3 values. `pass`, `hide` and `phantom_token`. Used to operate the authorization header from the upstream service as per configuration. In `phantom_token` case, plugin will replace bearer token with new generated JWT(with introspection result) token, so for outside there is bearer token and JWT for internal use.
custom_headers		Used to set the custom headers, which is passed to upstream service by kong after authentication. Check here for more details
consumer_mapping		`consumer_mapping = true`, GG introspect the token and try to find Kong consumer with `custom_id == client_id`. If consumer with such custom_id doesn’t exists - authentication fail. For `rate-limite` plugin configuration, you need to configure it as `limit_by=consumer`. With `consumer_mapping = false`, you don’t need to create a Kong consumer for every OAuth2 client. GG will introspect the token and perform authentication. For `rate-limite` plugin configuration, you need to configure it as `limit_by=credential`.

Gluu-UMA-PEP#

field	Default	Description
op_url		The URL of your OP server. Example: https://op.server.com
oxd_url		The URL of your oxd server. Example: https://oxd.server.com
oxd_id		The ID for an existing client used to introspect the token. If left blank, a new client will be registered dynamically
client_id		An existing client ID used to get a protection access token to access the introspection API. Required if an existing oxd ID is provided.
client_secret		An existing client secret, used to get a protection access token to access the introspection API. Required if an existing oxd ID is provided.
uma_scope_expression		Check here for description
deny_by_default	true	For paths not protected by UMA scope expressions. If true, denies unprotected paths.
require_id_token	false	It use when you configure `gluu-openid-connect` plugin. This is for the Push Claim token. if it is true then it will use id_token for push claim token for getting RPT
obtain_rpt	false	It is used to get RPT when you configure `gluu-openid-connect` plugin with `gluu-uma-pep`
claims_redirect_path		It use when you configure `gluu-openid-connect` plugin. Claims redirect URL in claim gathering flow for your OP Client. You just need to set path here like `/claim-callback` but you need to register OP Client with full URL like `https://kong.proxy.com/claim-callback`. GG UI creates OP client for you and also configure the `gluu-openid-connect` and `gluu-uma-pep` plugin.
redirect_claim_gathering_url	false	It use when you configure `gluu-openid-connect` plugin. It used to tell the plugin that if `need_info` response comes in claim gathering situation then redirect it for claim gathering.
method_path_tree		It is for plugin internal use. We use it for tree-level matching for dynamic paths which registered in `uma_scope_expression`
pushed_claims_lua_exp		It use when you are dealing with `gluu-openid-connect` plugin. Used to make the Push claim token. Check here for more details.

Note

GG UI can create a dynamic client. However, if the Kong Admin API is used for plugin configuration, it requires an existing client using the oxd API, then passing the client's credentials to the Gluu-UMA-PEP plugin.

Phantom Token#

In some cases, there is a requirement that bearer token for outside of the network and JWT token for the internal network. Check here for more details.

UMA Scope Expression#

It is stringify json. It used to register the resources in a resource server. See more details in the Gluu Server docs.

Important

GG UI registers the resources for you during plugin configuration. If you are using APIs, you need to register client and resources using OXD APIs. You don't need to pass stringify json during resource registration using OXD API. It is required only in the plugin configuration.

path: it is your url which you want to protect. There is a regular expression facility for path configuration. Check here for more dynamic path registration details.
- condition: it is the array of conditions for the path where you can define acr values to the path. You can add multiple conditions with different Http Method.
  - httpMethods: it is HTTP Method. During authentication, the plugin uses it as a filter for the request. ? in the HTTP method allow all the http methods. It should be in a capital case. e.g. GET, POST, PUT.
  - scope_expression: It is the rules to check the values.
  - data: It is the data for the scope_expression.

Example of JSON expression

[
  {
    "path": "/users",
    "conditions": [
      {
        "httpMethods": [
          "GET"
        ],
        "scope_expression": {
          "rule": {
            "and": [
              {
                "var": 0
              },
              {
                "or": [
                  {
                    "var": 1
                  },
                  {
                    "var": 2
                  }
                ]
              }
            ]
          },
          "data": [
            "admin",
            "employee",
            "customer"
          ]
        }
      }
    ]
  }
]

JSON expression in string format(stringify json)

"[{\"path\":\"/users\",\"conditions\":[{\"httpMethods\":[\"GET\"],\"scope_expression\":{\"rule\":{\"and\":[{\"var\":0},{\"or\":[{\"var\":1},{\"var\":2}]}]},\"data\":[\"admin\",\"employee\",\"customer\"]}}]}]"

Dynamic Resource Protection#

There are 3 elements to make more dynamic path registration and protection. Check here for more details.

DB-Less Configuration#

For DB-Less configuration you need 2 OP client. You need to use OXD APIs to create OP Client.

Plugin Client#

This client will be used to configure the plugin. During runtime, It use by plugin to introspect the token.

Below is the curl to create client:

curl -k -X POST https://<oxd_host>:8443/register-site \
-d '{
  "op_host":"https://<op_host>",
  "redirect_uris":["https://client.example.com/cb"],
  "client_name":"gluu-oauth-client",
  "scope":["openid","oxd", "uma_protection"],
  "grant_types":["client_credentials"]
}'

Register the UMA resource#

You also need to register UMA resources with Plugin OP Client which is for gluu-uma-pep plugin.

You need to first get AT using /get-client-token endpoint.

curl -k -X POST https://<your_oxd_host>:8443/get-client-token \
-d '{
  "op_host":"<your_op_server_url>",
  "client_id":"<plugin_client_id>",
  "client_secret":"<plugin_client_secret>",
  "scope":["openid","oxd"]
  }'

It will return AT token, you need to use this token in /uma-rs-protect request. Below is the curl for resource registration. We are registering scope_expression. Below is just a example. Please check here for more information about scope_expression.

curl -k -X POST https://ce-dev6.gluu.org:8443/uma-rs-protect \
-H 'Authorization: Bearer <AT_Token>' \
-d '{
  "oxd_id":"<plugin_client_oxd_id>",
  "resources":[{"path":"/settings/??","conditions":[{"httpMethods":["GET"],"scope_expression":{"rule":{"and":[{"var":0}]},"data":["with-claims"]}}]}]
  }'

Consumer Client#

This client will be used to configure the Consumer.

Below is the curl to create client:

curl -k -X POST https://<oxd_host>:8443/register-site \
-d '{
  "op_host":"https://<op_host>",
  "redirect_uris":["https://client.example.com/cb"],"client_name":"uma-consumer",
  "scope":["openid","oxd", "uma_protection"],
  "grant_types":["client_credentials"]
  }'

Plugin configuration#

Below is the example of kong.yml with plugin configurations. For more details about plugin parameters chech here.

{
  "_format_version": "1.1",
  "routes": [
    {
      "hosts": [
        "<your_host>"
      ],
      "name": "demo-route",
      "service": "demo-service"
    }
  ],
  "services": [
    {
      "name": "demo-service",
      "url": "<your_upstream_app_url>"
    }
  ],
  "plugins": [
    {
      "name": "gluu-uma-auth",
      "tags": null,
      "config": {
        "oxd_id": "<plugin_client_oxd_id>",
        "client_id": "<plugin_client_id>",
        "client_secret": "<plugin_client_secret>",
        "op_url": "<your_op_server_url>",
        "oxd_url": "<your_oxd_server_url>",
        "anonymous": "anonymous",
        "pass_credentials": "pass",
        "custom_headers": [
          {
            "header_name": "x-consumer-id",
            "value_lua_exp": "consumer.id",
            "format": "string",
            "sep": " ",
            "iterate": false
          },
          {
            "header_name": "x-oauth-client-id",
            "value_lua_exp": "introspect_data.client_id",
            "format": "string",
            "sep": " ",
            "iterate": false
          },
          {
            "header_name": "x-consumer-custom-id",
            "value_lua_exp": "introspect_data.client_id",
            "format": "string",
            "iterate": false,
            "sep": " "
          },
          {
            "header_name": "x-oauth-expiration",
            "value_lua_exp": "introspect_data.exp",
            "format": "string",
            "iterate": false,
            "sep": " "
          },
          {
            "header_name": "x-authenticated-scope",
            "value_lua_exp": "introspect_data.scope",
            "format": "list",
            "iterate": false,
            "sep": ","
          }
        ],
        "consumer_mapping": true
      },
      "route": "demo_route"
    },
    {
      "name": "gluu-uma-pep",
      "config": {
        "oxd_id": "<plugin_client_oxd_id>",
        "client_id": "<plugin_client_id>",
        "client_secret": "<plugin_client_secret>",
        "op_url": "<your_op_server_url>",
        "oxd_url": "<your_oxd_server_url>",
        "uma_scope_expression": "[{\"path\":\"/settings/??\",\"conditions\":[{\"httpMethods\":[\"GET\"],\"scope_expression\":{\"rule\":{\"and\":[{\"var\":0}]},\"data\":[\"with-claims\"]}}]}]",
        "deny_by_default": true
      },
      "route": "demo-route"
    }
  ],
  "consumers": [
    {
      "custom_id": "<consumer_clients_client_id>",
      "username": "<give_any_unique_name>"
    },
    {
      "custom_id": "anonymous",
      "username": "anonymous"
    }
  ]
}

Usage#

Create Client#

Create a client using create client consumer section or use the oxd register-site API to create a client.

Create Consumer#

A client credential needs to be associated with an existing Consumer object. To create a Consumer, use the Consumer section.

Create a consumer using the Kong Admin API.

$ curl -X POST \
    http://<kong_hostname>:8001/consumers \
    -H 'Content-Type: application/json' \
    -d '{
   "username": "<kong_consumer_name>",
   "custom_id": "<gluu_client_id>"
  }'

Security & Access Proxy#

To access a proxy upstream API, pass an UMA RPT token in the authorization header. Generate the UMA RPT token using OP Client credentials by sending a request to the oxd APIs.

For example, to access a Kong proxy using an UMA token:

curl -X GET \
  http://<kong_hostname>:8000/{path matching a configured Route} \
  -H 'Authorization: Bearer <uma_rpt_token>' \

Note

Kong normally provides the 8443 port for https by default, but during the setup script installation, it is changed to 443.

Upstream Headers#

When a client has been authenticated, the plugin will append some headers to the request before proxying it to the upstream service to identify the consumer and the end-user in the code:

Check here to setup custom headers.

This information can be used to implement additional logic. For example, use the X-Consumer-ID value to query the Kong Admin API and retrieve more information about the Consumer.

Gluu UMA Auth and UMA PEP#

Overview#

Configuration#

Service Level#

Route Level#

Global Plugin#

Add Plugin#

Add Plugin using Kong API#

Parameters#

Gluu-UMA-Auth#

Gluu-UMA-PEP#

Phantom Token#

UMA Scope Expression#

Dynamic Resource Protection#

DB-Less Configuration#

Plugin Client#

Register the UMA resource#

Consumer Client#

Plugin configuration#

Usage#

Create Client#

Create Consumer#

Security & Access Proxy#

Upstream Headers#

Demos and Tutorials#