Skip to content

Common Features#

Below are common features in the Gluu OAuth and UMA plugins.

Phantom Token#

Some deployments require the use of a bearer token outside of the internal network and a JWT token within it. This phantom token approach is similar to a reverse proxy, adding a layer of insulation between external requests and the internal network.

phantom_token

This feature is available in both the gluu-oauth-auth and the gluu-uma-auth plugins. To configure phantom token feature, you just need to set pass_credentials='phantom_token' in plugin configuration.

Important

Set access_token_as_jwt: false and rpt_as_jwt: false in client registration, otherwise client by default returns you access token as JWT.

Dynamic Resource Protection#

This feature is available for the gluu-oauth-pep and gluu-uma-pep plugins.

dynamic_path

There are 3 elements to make more dynamic path registration and protection:

  • ? match anyone path element
  • ?? match zero or more path elements
  • {regexp} - match single path element against PCRE

The priority for the elements are:

  1. Exact match
  2. Regexp match
  3. ?
  4. ??

Info

A ? in the HTTP method allows all HTTP methods.

Info

You can use this elements to register more dynamic path for required_acrs_expression in gluu-openid-connect

Warning

Multiple times ?? in path not supported.

Examples:

Assume that all paths below are registered in one plugin:

Register Path Apply security Not Apply security
/??
  • /folder/file.ext
  • /folder/file2
  • Apply security on all the paths
/folder/file.ext
  • /folder/file.ext
  • /folder/file
/folder/file
  • /folder/file
  • /folder/file/
  • /folder/file/123
  • It will be good to use /?? wild card if you want to secure sub folders
/folder/?/file
  • /folder/123/file
  • /folder/xxx/file
/path/??
  • /path
  • /path/
  • /path/xxx
  • /path/xxx/yyy/file
/path/??/image.jpg
  • /path/one/two/image.jpg
  • /path/image.jpg
/path/?/image.jpg
  • /path/xxx/image.jpg - ? has higher priority than ??
/path/{abc|xyz}/image.jpg
  • /path/abc/image.jpg
  • /path/xyz/image.jpg
/users/?/{todos|photos}
  • /users/123/todos
  • /users/xxx/photos
/users/?/{todos|photos}/?
  • /users/123/todos/
  • /users/123/todos/321
  • /users/123/photos/321

Custom Headers#

After successful authentication, kong forward request upstream service. During this step, kong sends headers to your upstream headers. You can use this header to check and identify the user or request.

There is feature in all 3 authentication plugins gluu-oauth-auth, gluu-uma-auth and gluu-openid-connect. Every plugin provide an environment which you need to use to set headers.

For Example: gluu-oauth-auth plugin has the introspect_data environment which has the token introspect response data. So If you want to set one header like x-auth-token-exp which will has the token expiration timestamp then you need to use the environment introspect_data.exp to set value.

Take a look on below table for available environment in every plugin

Plugin Environment
gluu-oauth-auth
  • consumer
  • introspect_data
gluu-uma-auth
  • consumer
  • introspect_data
gluu-openid-connect
  • id_token
  • userinfo
  • access_token

Every plugin has the custom_headers field. which is the the array and below is the structure of an object.

Field Description
header_name The title for header, may contain {} placeholder when iterate thru claims, take a look at iterate field below. Example:* http-kong-id-token
value_lua_exp It is the lua expression which will populate the environment values. Note: For custom values you need to pass value in double quotes("value")
format the format used to encode the value. Formats: string(as it is), base64, urlencoded, list, and jwt(with none alg)
sep it is use when your header format is list type. It join the list of values by separator. Example: , (comma)
iterate the header value should point to an environment values, for example id_token It use to iterate thru keys/values and create separate header for every key. The captured key is accessible in header name via special placeholder i.e. {*}.

In UI, you will get facility to add custom headers. You just need to use header section. Click on Add Button to add header.

oidc3-1

Example#

  1. gluu-uma-auth

    Header Name Value Format Separator Iterate
    x-oauth-client-id introspect_data [JWT | base64] false
    x-consumer-id consumer.id [string | base64 | urlencoded] false
    x-oauth-client-id introspect_data.client_id [string | base64 | urlencoded] false
    x-rpt-expiration introspect_data.exp [string | base64 | urlencoded] false
    x-oauth-token-{*} introspect_data [string | urlencoded | base64] true
    kong-version "version 2.0",

    Note: double quotes required for custom values.

    		 [string | urlencoded | base64] false

  2. gluu-oauth-auth

    Header Name Value Format Separator Iterate
    x-oauth-client-id introspect_data [JWT | base64] false
    x-consumer-id consumer.id [string | base64 | urlencoded] false
    x-oauth-client-id introspect_data.client_id [string | base64 | urlencoded] false
    x-rpt-expiration introspect_data.exp [string | base64 | urlencoded] false
    x-oauth-token-{*} introspect_data [string | urlencoded | base64] true
    kong-version "version 2.0",

    Note: double quotes required for custom values.

    		 [string | urlencoded | base64] false
    x-authenticated-scope introspect_data.scope list , (comma) No

  3. gluu-openid-connect

    Header Name Value Format Separator Iterate
    kong-openidc-id-token id_token [string | base64] false
    kong-openidc-userinfo userinfo [jwt | base64] false
    kong-openidc-id-token-{*} id_token [string | urlencoded | base64] true
    kong-openidc-userinfo-{*} userinfo [string | urlencoded | base64] true
    kong-openidc-userinfo-email userinfo.email [string | urlencoded | base64] false
    kong-openidc-id-token-exp id_token.exp [string | base64] false
    kong-userinfo-roles userinfo.roles [list] , (comma) false
    gg-access-token access_token [string | urlencoded | base64] No