Note: This feature is available with bosh-release v209+ (1.3088.0) colocated with uaa v1+.

In this configuration the Director is configured to delegate user management to the 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.


Configuring the Director

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

    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=24
      sha1: d0feb5494153217f3d62b346f426ad2b2f43511a
    
  2. Colocate UAA next to the Director:

    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
      # ...
    
  3. Add uaa section to the deployment manifest:

    properties:
      uaa:
        url: "https://54.236.100.56:8443"
    
        scim:
          users:
          - name: admin
            # password: admin-password # <--- Uncomment & change
            groups:
            - 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: 120 # 2 min
            refresh-token-validity: 86400 # re-login required once a day
            secret: "" # CLI expects this secret to be empty
    
        admin:
          # client_secret: admin-password # <--- Uncomment & change
        login:
          # client_secret: login-password # <--- Uncomment & change
        zones: {internal: {hostnames: []}}
    

    Note: Make sure UAA URL corresponds to the Director and UAA certificate subjects.

    To configure UAA to use LDAP, SAML, etc. see uaa release job properties.

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

    properties:
      postgres: &db
        host: 127.0.0.1
        port: 5432
        user: postgres
        # password: postgres-password # <--- Uncomment & change
        database: bosh
        additional_databases: [uaa] # <---
        adapter: postgres
    

    Note: If you are using externally configured database, you should skip this section.

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

    properties:
      uaadb:
        address: 127.0.0.1
        port: 5432
        db_scheme: postgresql
        databases:
        - {tag: uaa, name: uaa}
        roles:
        - tag: admin
          name: postgres
          # password: postgres-password # <--- Uncomment & change
    
  6. 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.

    properties:
      director:
        user_management:
          provider: uaa
          uaa:
            url: "https://54.236.100.56:8443"
    

    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.

    Note: Make sure UAA URL corresponds to the UAA certificate subject.

  7. Configure Certificates and Keys

    See Director certificates configuration doc to find out how to generate necessary certificates. Note, however, that login.saml.serviceProviderKeyPassword may need to be set to “”, see.

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

    $ ssh-keygen -t rsa -b 4096 -f uaa
    $ openssl rsa -in uaa -pubout > uaa.pub
    

    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)
  8. Allow access to port 8443 on the Director VM from your IaaS so that the CLI can access the UAA server.

  9. Redeploy the Director with the updated manifest.


Logging into the Director as a user

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

$ bosh login
Email: admin
Password: **************

Adding/removing Users and Permissions

An example of how to use UAA CLI 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.

$ uaac target https://54.236.100.56:8443 --ca-cert certs/rootCA.pem
$ uaac token client get admin
Client secret:  **************
$ uaac user add some-new-user --emails new.user@example.com

Note: Use UAA CLI v3.1.4+ to specify custom CA certificate.

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

$ uaac group add bosh.read
$ uaac member add bosh.read some-new-user

Remove permission by removing users from a group:

$ uaac member delete bosh.read some-new-user

Remove users to revoke authentication completely:

$ uaac user delete some-new-user

Note that changing group membership will take effect when a new access token is created for that user. New access are granted when their existing access token expires or when user logs out and logs in again. Hence it’s recommended to set access token validity to a minute or so.


Logging into the Director as a UAA client

Non-interactive login, e.g. for scripts during a CI build is supported by the UAA by using a different UAA client allowing client_credentials grant type.

$ export BOSH_CLIENT=ci
$ export BOSH_CLIENT_SECRET=ci-password
$ bosh status

See the resurrector UAA client configuration for an example to set up an additional client.


Permissions

See UAA permissions to limit access to resources.


Errors

HTTP 401: Not authorized: '/deployments' requires one of the scopes: bosh.admin, bosh.UUID.admin, bosh.read, bosh.UUID.read

This error occurs if the user doesn’t have the right scopes for the requested command. It might be the case that you created a user without adding it to any groups. See Adding/removing users and scopes above.


Back to Table of Contents


Contribute changes to this page