rabbitmq-server/deps/rabbitmq_auth_backend_oauth2/README.md

RabbitMQ authorisation Backend for Cloud Foundry UAA

Allows to use access tokens provided by CF UAA to authorize in RabbitMQ.

Usage

First, enable the plugin. Then, configure access to UAA:

[{rabbitmq_auth_backend_uaa,
  [{resource_server_id, <<"your-resource-server-id"}]},
 {uaa_jwt, [
  {signing_keys, #{
    <<"key1">> => {map, #{<<"kty">> => <<"oct">>, <<"k">> => <<"dG9rZW5rZXk">>}},
    <<"key2">> => {pem, <<"/path/to/public_key.pem">>},
    <<"key3">> => {json, "{\"kid\":\"key3\",\"alg\":\"HMACSHA256\",\"value\":\"tokenkey\",\"kty\":\"MAC\",\"use\":\"sig\"}"}}}]}].

where

• your-resource-server-id is a resource server ID (e.g. 'rabbitmq')
• signing_keys is a map of keys to sign JWT tokens (see UAA_JWT library for mode info)

To learn more about UAA/OAuth 2 clients, see UAA docs.

Then you can use access_tokens acquired from UAA as username to authenticate in RabbitMQ.

Scopes

Scopes are translated into permission grants to RabbitMQ resources for the provided token.

The current scope format is <permission>:<vhost_pattern>/<name_pattern>[/<routing_key_pattern>] where

• <permission> is an access permission (configure, read, or write)
• <vhost_pattern> is a wildcard pattern for vhosts, token has acces to.
• <name_pattern> is a wildcard pattern for resource name
• <routing_key_pattern> is an optional wildcard pattern for routing key in topic authorization

Wildcard patterns are strings with optional wildcard symbols * that match any sequence of characters.

Wildcard patterns match as wollowing:

• * matches any string
• foo* matches any string starting with a foo
• *foo matches any string ending with a foo
• foo*bar matches any string starting with a foo and ending with a bar

There can be multiple wildcards in a pattern:

• start*middle*end
• *before*after*

If you want to use special characters like *, %, or / in a wildacrd pattern, the pattern must be URL-encoded.

See the [./test/wildcard_match_SUITE.erl](wildcard matching test suite) for more examples.

Authorization Workflow

Prerequisites

1. There should be application client registered on UAA server.
2. Client id and secret should be set in plugin env as username and password
3. Client authorities should include uaa.resource
4. RabbitMQ auth_backends should include rabbit_auth_backend_uaa

Authorization

1. Client authorize with UAA, requesting access_token (using any grant type)
2. Token scope should contain RabbitMQ resource scopes (e.g. configure:%2F/foo means "configure queue 'foo' in vhost '/'")
3. Client passes token for a username when connecting to a RabbitMQ node

uaa_jwt