<commit_before>---
title: UAA Integration
---

<p class="note">Note: This feature is available with bosh-release v209+ (1.3088.0) colocated with uaa v1+.</p>

In this configuration the Director is configured to delegate user management to the [UAA](https://github.com/cloudfoundry/uaa) server. The UAA server can be configured to manage its own list of users or work with an LDAP server, or a SAML provider. Regardless how the UAA server is configured the BOSH CLI will ask appropriate credentials and forward them to the UAA to request a token.

---
## <a id="configure"></a> Configuring the Director

1. Change deployment manifest for the Director and add UAA release:

    ```yaml
    releases:
    - name: bosh
      url: https://bosh.io/d/github.com/cloudfoundry/bosh?v=209
      sha1: a96833b6c68abda5aaa5d05ebdd0a5d394e6c15f
    # ...
    - name: uaa # <+++
      url: https://bosh.io/d/github.com/cloudfoundry/uaa-release?v=1
      sha1: 477289da17ffe105d0b6bde1bc10f61b1cb50fb4
    ```

1. Colocate UAA next to the Director:

    ```yaml
    jobs:
    - name: bosh
      instances: 1
      templates:
      - {name: nats, release: bosh}
      - {name: redis, release: bosh}
      - {name: postgres, release: bosh}
      - {name: blobstore, release: bosh}
      - {name: director, release: bosh}
      - {name: health_monitor, release: bosh}
      - {name: uaa, release: uaa} # <+++
      resource_pool: default
      # ...
    ```

1. Add `uaa` section to the deployment manifest:

    ```yaml
    properties:
      uaa:
        url: "https://172.16.31.10:8443"

        scim:
          users:
          - admin|admin-password|scim.write,scim.read,bosh.admin

        clients:
          bosh_cli:
            override: true
            authorized-grant-types: password,refresh_token
            # scopes the client may receive
            scope: openid,bosh.admin,bosh.read,bosh.*.admin,bosh.*.read
            authorities: uaa.none
            access-token-validity: 60 # 1 min
            refresh-token-validity: 86400 # re-login required once a day
            secret: ""

        admin: {client_secret: admin-password}
        login: {client_secret: login-password}
        zones: {internal: {hostnames: []}}
    ```

    To configure UAA to use LDAP, SAML, etc. see [uaa release job properties](http://bosh.io/jobs/uaa?source=github.com/cloudfoundry/uaa-release&version=1).

1. Configure the Director Postgres server to have an additional database called `uaa`:

    ```yaml
    properties:
      postgres: &db
        host: 127.0.0.1
        port: 5432
        user: postgres
        password: <PASSWORD>
        database: bosh
        additional_databases: [uaa] # <+++
        adapter: postgres
    ```

1. Configure the UAA server to point to that database:

    ```yaml
    properties:
      uaadb:
        address: 127.0.0.1
        port: 5432
        db_scheme: postgresql
        databases:
        - {tag: uaa, name: uaa}
        roles:
        - tag: admin
          name: postgres
          password: <PASSWORD>
    ```

1. Change Director configuration to specify how to contact the UAA server and how to verify an access token. Since UAA will be on the same server we can use the same IP as the one used for the Director.

    ```yaml
    properties:
      director:
        user_management:
          provider: uaa
          uaa:
            url: "https://172.16.31.10:8443"
    ```

    <p class="note">Note: The UAA URL given to the Director will be advertised to the CLI and the CLI will use it to ask for an access token. This means that the CLI must be able to reach that IP.</p>

1. Configure Certificates and Keys

    See [Director certificates configuration doc](director-certs.html) to find out how to generate necessary certificates.

    To generate UAA signing (private key) and verification key (public key) in PEM format:

    <pre class="terminal">
    $ ssh-keygen -t rsa -b 4096 -f uaa
    $ openssl rsa -in uaa -pubout > uaa.pub
    </pre>

    Put the keys in the Director deployment manifest:
    - `uaa.jwt.signing_key`
        - Private key used to sign authorization tokens (e.g. `./uaa`)
    - `uaa.jwt.verification_key`
        - Public key used to verify tokens (e.g. `./uaa.pub`)
    - `director.user_management.uaa.public_key`
        - Public key used by the Director to verify tokens without contacting the UAA (e.g. `./uaa.pub`)

1. Allow access to 8443 port on the Director VM from your IaaS so that the CLI can access the UAA server.

1. Redeploy the Director with the updated manifest.

---
## <a id="user-login"></a> Logging into the Director as a user

Depending on how the UAA is configured different prompts may be shown.

<pre class="terminal">
$ bosh login
Email: admin
Password: **************
</pre>

### <a id="uaac"></a> Adding/removing Users and Permissions

An example of how to use [UAA CLI](https://rubygems.org/gems/cf-uaac) to add a new user that has readonly access on any Director. Enter the client secret provided for the UAA admin client in the manifest at `uaa.admin.client_secret`.

<pre class="terminal">
$ uaac target https://172.16.31.10:8443 --skip-ssl-validation
$ uaac token client get admin
Client secret:  **************
$ uaac user add some-new-user --emails <EMAIL>
</pre>

You can add permissions to users by defining a group and adding users to that group:

<pre class="terminal">
$ uaac group add bosh.read
$ uaac member add bosh.read some-new-user
</pre>

Remove permission by removing users from a group:

<pre class="terminal">
$ uaac member delete bosh.read some-new-user
</pre>

Remove users to revoke authentication completely:
<commit_msg>use --ca-cert with uaac<commit_after>---
title: UAA Integration
---

<p class="note">Note: This feature is available with bosh-release v209+ (1.3088.0) colocated with uaa v1+.</p>

In this configuration the Director is configured to delegate user management to the [UAA](https://github.com/cloudfoundry/uaa) server. The UAA server can be configured to manage its own list of users or work with an LDAP server, or a SAML provider. Regardless how the UAA server is configured the BOSH CLI will ask appropriate credentials and forward them to the UAA to request a token.

---
## <a id="configure"></a> Configuring the Director

1. Change deployment manifest for the Director and add UAA release:

    ```yaml
    releases:
    - name: bosh
      url: https://bosh.io/d/github.com/cloudfoundry/bosh?v=209
      sha1: a96833b6c68abda5aaa5d05ebdd0a5d394e6c15f
    # ...
    - name: uaa # <---
      url: https://bosh.io/d/github.com/cloudfoundry/uaa-release?v=1
      sha1: 477289da17ffe105d0b6bde1bc10f61b1cb50fb4
    ```

1. Colocate UAA next to the Director:

    ```yaml
    jobs:
    - name: bosh
      instances: 1
      templates:
      - {name: nats, release: bosh}
      - {name: redis, release: bosh}
      - {name: postgres, release: bosh}
      - {name: blobstore, release: bosh}
      - {name: director, release: bosh}
      - {name: health_monitor, release: bosh}
      - {name: uaa, release: uaa} # <---
      resource_pool: default
      # ...
    ```

1. Add `uaa` section to the deployment manifest:

    ```yaml
    properties:
      uaa:
        url: "https://172.16.31.10:8443"

        scim:
          users:
          - admin|admin-password|scim.write,scim.read,bosh.admin

        clients:
          bosh_cli:
            override: true
            authorized-grant-types: password,refresh_token
            # scopes the client may receive
            scope: openid,bosh.admin,bosh.read,bosh.*.admin,bosh.*.read
            authorities: uaa.none
            access-token-validity: 60 # 1 min
            refresh-token-validity: 86400 # re-login required once a day
            secret: ""

        admin: {client_secret: admin-password}
        login: {client_secret: login-password}
        zones: {internal: {hostnames: []}}
    ```

    To configure UAA to use LDAP, SAML, etc. see [uaa release job properties](http://bosh.io/jobs/uaa?source=github.com/cloudfoundry/uaa-release&version=1).

1. Configure the Director Postgres server to have an additional database called `uaa`:

    ```yaml
    properties:
      postgres: &db
        host: 127.0.0.1
        port: 5432
        user: postgres
        password: <PASSWORD>
        database: bosh
        additional_databases: [uaa] # <---
        adapter: postgres
    ```

1. Configure the UAA server to point to that database:

    ```yaml
    properties:
      uaadb:
        address: 127.0.0.1
        port: 5432
        db_scheme: postgresql
        databases:
        - {tag: uaa, name: uaa}
        roles:
        - tag: admin
          name: postgres
          password: <PASSWORD>
    ```

1. Change Director configuration to specify how to contact the UAA server and how to verify an access token. Since UAA will be on the same server we can use the same IP as the one used for the Director.

    ```yaml
    properties:
      director:
        user_management:
          provider: uaa
          uaa:
            url: "https://172.16.31.10:8443"
    ```

    <p class="note">Note: The UAA URL given to the Director will be advertised to the CLI and the CLI will use it to ask for an access token. This means that the CLI must be able to reach that IP.</p>

1. Configure Certificates and Keys

    See [Director certificates configuration doc](director-certs.html) to find out how to generate necessary certificates.

    To generate UAA signing (private key) and verification key (public key) in PEM format:

    <pre class="terminal">
    $ ssh-keygen -t rsa -b 4096 -f uaa
    $ openssl rsa -in uaa -pubout > uaa.pub
    </pre>

    Put the keys in the Director deployment manifest:
    - `uaa.jwt.signing_key`
        - Private key used to sign authorization tokens (e.g. `./uaa`)
    - `uaa.jwt.verification_key`
        - Public key used to verify tokens (e.g. `./uaa.pub`)
    - `director.user_management.uaa.public_key`
        - Public key used by the Director to verify tokens without contacting the UAA (e.g. `./uaa.pub`)

1. Allow access to port 8443 on the Director VM from your IaaS so that the CLI can access the UAA server.

1. Redeploy the Director with the updated manifest.

---
## <a id="user-login"></a> Logging into the Director as a user

Depending on how the UAA is configured different prompts may be shown.

<pre class="terminal">
$ bosh login
Email: admin
Password: **************
</pre>

### <a id="uaac"></a> Adding/removing Users and Permissions

An example of how to use [UAA CLI](https://rubygems.org/gems/cf-uaac) to add a new user that has readonly access on any Director. Enter the client secret provided for the UAA admin client in the manifest at `uaa.admin.client_secret`.

<pre class="terminal">
$ uaac target https://5172.16.58.3:8443 --ca-cert certs/rootCA.pem
$ uaac token client get admin
Client secret:  **************
$ uaac user add some-new-user --emails <EMAIL>
</pre>

<p class="note">Note: Use UAA CLI v3.1.4+ to specify custom CA certificate.</p>

You can add permissions to users by defining a group and adding users to that group:

<pre class="terminal">
$ uaac group add bosh.read
$ uaac member add bosh.read some-new-user
</pre>

Remove permission by removing users from a group:

<pre class="terminal">
$ uaac member delete bosh.read some-new-user
</pre>

Remove users to revoke authentication completely:

{'fraction_non_alphanumeric': 0.10620168657765285, 'fraction_numerical': 0.0255621925509487, 'mean_word_length': 2.6350574712643677, 'pattern_counts': {'":': 0, '<': 57, '<?xml version=': 0, '>': 53, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 10, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2860982', 'n_tokens_mistral': 3742, 'n_tokens_neox': 3515, 'n_words': 1275}