enable-oauth-for-apps.html.md.erb

---
title: Enabling OAuth for Apps
owner: RabbitMQ
---

This topic explains how to connect apps to RabbitMQ using OAuth 2.0.


## <a id='overview'></a> Overview

Apps authenticate with RabbitMQ using the OAuth client flow as follows:

1. The app queries UAA for a JWT token with relevant scopes, using the client credentials granted
through binding with the Single Sign-On instance.
1. The app then uses this JWT token, in place of a password, to authenticate with the RabbitMQ
service instance.

For an example of a Spring app that uses the OAuth client flow, see
[rabbitmq-oauth-example-app](https://github.com/vmware-samples/rabbitmq-oauth-example-app) in GitHub.

To connect apps to RabbitMQ using OAuth, you must:

1. [Create UAA Groups for a Space](#create-uaa-groups)
1. [Assign an Identity to the App](#assign-identity)
1. [Grant Authorities to the App](#grant-authorities)


## <a id='prerequisites'></a> Prerequisites

Before you enable OAuth for apps, you must:

* Install the Single Sign-On tile.
For more information,
[Installing Single Sign-On for VMware Tanzu](https://docs.pivotal.io/p-identity/installation.html).

* Enable the UAA/System plan for any orgs that will contain apps needing to access RabbitMQ service
instances. You can do this using the Single Sign-On tile dashboard or by running the following
cf CLI command:

    ```
    cf enable-service-access p-identity -p uaa -o ORG-NAME
    ```
    Where `ORG-NAME` is the name of the Cloud Foundry org you want to enable access to.

* Install the UAA CLI.
For more information, see
[Install UAAC](https://docs.pivotal.io/p-identity/configure-internal-us.html#install-uaac).


## <a id='create-uaa-groups'></a> Create UAA Groups for a Space

You must create UAA groups for each space in <%= vars.app_runtime_abbr %> that contains,
or is expected to contain, on-demand <%= vars.product_short %> service instances.
These groups correspond to RabbitMQ resources and can be granted as authorities to clients which
interact with RabbitMQ.

To create a UAA group for a space:

1. Display the space GUID by running:

    ```
    cf space SPACE-NAME --guid
    ```
    Where `SPACE-NAME` is the name of the space.

1. Record the space GUID.

1. Retrieve the UAA admin client credentials from <%= vars.ops_manager %> by running:

    ```
    om credentials --product-name cf \
      --credential-reference .uaa.admin_client_credentials
    ```

1. Authenticate with UAA by running:

    ```
    uaac target https://uaa.SYSTEM-DOMAIN
    uaac token client get CLIENT -s SECRET
    ```
    Where:

    * `SYSTEM-DOMAIN` is the system domain for your <%= vars.app_runtime_abbr %> foundation.
    * `CLIENT` and `SECRET` are the credentials for the UAA admin client.

1. Create UAA groups using the space GUID and RabbitMQ resources by running:

    ```
    uaac group add p-rabbitmq_SPACE-GUID.SCOPE:VHOST/NAME[/ROUTING-KEY]
    ```
    Where:

    * `SPACE-GUID` was recorded above.
    * `SCOPE` is an access permission, such as `configure`, `read`, or `write`.
    * `VHOST` is a wildcard pattern for the vhosts that you want to grant the client access to.
    * `NAME` is a wildcard pattern for the queues and exchanges that you want to grant the client
    access to.
    * (Optional) `ROUTING-KEY` is a pattern for routing keys in topics.<br>

    Wildcard patterns match as follows:
    <ul>
      <li><code>\*</code> matches any string</li>
      <li><code>foo\*</code> matches any string starting with foo</li>
      <li><code>\*foo</code> matches any string ending with foo</li>
      <li><code>foo\*bar</code> matches any string starting with foo and ending with bar</li>
    </ul>
    You can include multiple wildcards in a pattern. For example:<br>
    `p-rabbitmq_SPACE-GUID.read:*/*`<br>
    `p-rabbitmq_SPACE-GUID.write:*/*`<br>
    `p-rabbitmq_SPACE-GUID.configure:*/*`


## <a id='assign-identity'></a> Assign an Identity to the App

<p class='note'>
  <strong>Note:</strong> In most cases, app developers follow this procedure.
</p>

Before an app can interact with a RabbitMQ instance, you must associate the app with a UAA client.
You must grant this client authorities that correspond to the RabbitMQ resources it will interact
with.

To assign an identity to an application using the Single Sign-On tile:

1. In each space containing an app that needs to be bound to a RabbitMQ instance, create a
Single Sign-On service instance by running the following cf CLI command:

    ```
    cf create-service p-identity uaa INSTANCE-NAME
    ```
    Where `INSTANCE-NAME` is a name of your choice.

1. Create a JSON file named `binding.json` that contains the binding parameters.
SSO uses this file to configure the OAuth client when binding the app to the SSO service instance.
Include the RabbitMQ scopes that must be granted to the app, corresponding to the UAA groups created
above.
<br><br>
For example, an app requiring read, write, and configure access to a RabbitMQ instance has the
following binding JSON:

    ```json
    {
      "grant_types": ["client_credentials"],
      "authorities": [
        "p-rabbitmq_SPACE-GUID.read:*/*",
        "p-rabbitmq_SPACE-GUID.write:*/*",
        "p-rabbitmq_SPACE-GUID.configure:*/*",
        "openid",
        "roles",
        "user_attributes",
        "uaa.resource",
      ]
    }
    ```
    Where `SPACE-GUID` is the GUID for the space.

1. Bind the app to the Single Sign-On service instance with the binding parameters by running:

    ```
    cf bind-service APP-NAME INSTANCE-NAME -c binding.json
    ```
    Where:

    * `APP-NAME` is the name of the app.
    * `INSTANCE-NAME` is the name of the Single Sign-On instance you created earlier.


## <a id='grant-authorities'></a> Grant Authorities to the App

To grant the relevant authorities to the app and grant it access to a RabbitMQ instance:

1. Find the name of the UAA client associated with the app. To do this, look up the app in the
SSO instance dashboard or run the following UAA CLI command:

    ```
    uaac clients | grep -B 10 “name: APP-NAME”
    ```
    Where `APP-NAME` is the name of the app.

1. From the output of the above command, record the `CLIENT-NAME`.
1. Verify that this is the correct UAA client by examining the output of the command:

    ```
    uaac client get CLIENT-NAME
    ```

1. Grant the UAA client relevant authorities by running:

    ```
    uaac client update CLIENT-NAME \
      --authorities LIST-OF-AUTHORITIES
    ```
    Where:

    * `CLIENT-NAME` is the name of the UAA client associated with the application recorded above.
    * `LIST-OF-AUTHORITIES` is a single string containing a space-separated list of scopes the client
    must be granted, corresponding to one or more of the UAA groups created above.
    The authorities use the format `p-rabbitmq_SPACE-GUID.SCOPE:VHOST/QUEUE[/ROUTING-KEY]`.<br>
    You might also need to grant additional authorities such as `openid`, `roles`, `user_attributes`,
    and `uaa.resource`.
    Any authorities the app requests through the Single Sign-On binding that are not in this list
    will not be granted.