Enable OAuth for Apps

Note: Pivotal Platform is now part of VMware Tanzu. In v1.20 and later, VMware Tanzu RabbitMQ [VMs] is named VMware Tanzu RabbitMQ for VMs.

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

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.
  2. 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 in GitHub.

To connect apps to RabbitMQ using OAuth, you must:

  1. Create UAA Groups for a Space
  2. Assign an Identity to the App
  3. Grant Authorities to the App

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.

  • 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.

Create UAA Groups for a Space

You must create UAA groups for each space in TAS for VMs that contains, or is expected to contain, on-demand VMware Tanzu RabbitMQ 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.

  2. Record the space GUID.

  3. Retrieve the UAA admin client credentials from Ops Manager by running:

    om credentials --product-name cf \
      --credential-reference .uaa.admin_client_credentials
    
  4. 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 TAS for VMs foundation.
    • CLIENT and SECRET are the credentials for the UAA admin client.
  5. 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.

    Wildcard patterns match as follows:

    • * matches any string
    • foo* matches any string starting with foo
    • *foo matches any string ending with foo
    • foo*bar matches any string starting with foo and ending with bar
    You can include multiple wildcards in a pattern. For example:
    p-rabbitmq_SPACE-GUID.read:*/*
    p-rabbitmq_SPACE-GUID.write:*/*
    p-rabbitmq_SPACE-GUID.configure:*/*

Assign an Identity to the App

Note: In most cases, app developers follow this procedure.

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.

  2. 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.

    For example, an app requiring read, write, and configure access to a RabbitMQ instance has the following binding 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.

  3. 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.

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.

  2. From the output of the above command, record the CLIENT-NAME.

  3. Verify that this is the correct UAA client by examining the output of the command:

    uaac client get CLIENT-NAME
    
  4. 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].
      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.