UAA Overview

Page last updated:

User Account and Authentication (UAA) is an open source identity server project under the Cloud Foundry (CF) Foundation.

UAA provides enterprise-scale identity management features. For example, it is used by the following commercial services:

What Is UAA?

UAA provides identity-based security for apps and APIs. It supports open standards for authentication and authorization, including:

  • OAuth
  • OpenID Connect
  • SAML
  • LDAP
  • SCIM

The major features of UAA include:

  • User Single Sign-On (SSO) using federated identity protocols
  • API security with OAuth
  • User and group management
  • Multi-tenancy support
  • Support for JWT and opaque as a token format
  • Token revocation
  • Operational flexibility
    • Operate and run as a BOSH release, which allows multi-cloud deployment capabilities
    • Push as an app to PAS
  • Database flexibility, including support for MySQL and Postgres
  • Auditing, logging, and monitoring
  • Token exchange for SAML and JWT bearers
  • Rest APIs for authentication, authorization, and configuration management

UAA Architecture

UAA architecture diagram

Protocol Purpose Profiles
OAuth 2.0 Authorizes apps and APIs Authorization Server,
Relying Party
OpenID Connect 1.0 Federates to external identity providers for SSO
Acts as an identity provider for SSO
Identity Provider,
Relying Party
SAML 2.0 Federates to external identity providers for SSO
Acts as an identity provider for SSO
Identity Provider,
Service Provider
LDAP Authenticate users in external user store LDAP Client
SCIM 1.0 User and group management Identity Provisioning

Client-Side Tools and Libraries

Name Language
Spring Security OAuth Java
CF Java Client Java
UAA Javascript SDK (Singular) JS

The Role of UAA in Securing PAS

PAS relies on UAA for its identity and access management requirements. UAA secures user and system access to PAS installations.

Since PAS is primarily used in the enterprise context, UAA supports enterprise SSO workflows. If a user has already authenticated against the enterprise identity provider, they can access PAS without re-entering credentials.

Some of the major components of PAS that use UAA include:

  • Cloud Controller
  • Gorouter
  • Loggregator
  • Container networking

Each of these components expose APIs for user and system interaction. UAA uses OAuth to secure the APIs exposed by core PAS components.

UAA secures many different CF components, including:

  • CF CLI
  • Cloud Controller
  • Loggregator
  • Notifications
  • Gorouter
  • Container Networking
  • Diego
  • Operations Manager/BOSH Director
  • Autoscaler

Token Management

After authenticating, client apps access resources and services using tokens rather than account authentication credentials. UAA generates, manages, distributes, and validates these tokens. UAA provides new tokens only to client apps with valid authentication credentials.

Once granted, token validity is unchallenged until the token expires due to timeout.

UAA distributes two types of tokens: access tokens and refresh tokens.

Access Tokens

Client apps use UAA-provided access tokens to request access to API endpoints, resources and services. The access token presented by a client app must be valid in order to access a resource.

Access tokens are valid for a short period of time.

After a UAA-provided access token has expired, a client app can request UAA provide a replacement. To request a replacement access token from UAA a client app must present a valid refresh token.

Refresh Tokens

Client apps use UAA-provided refresh tokens to request replacements for expired access tokens. The refresh token presented by a client app must be valid in order to replace an expired access token.

Refresh tokens are valid for a long period of time.

UAA does not provide replacement refresh tokens. A client app must re-authenticate to obtain a new refresh token.

Token Timeouts

Consider the following end-results of the token interactions listed above.

Authenticated client apps are running and interacting with services using tokens, not the service account’s authentication. An admin can revoke a service account’s access and privileges, but a client app running under that service account can continue to interact with the environment, unchallenged, as long as its token is valid:

  • The access token timeout is therefore the maximum period during which an already running app can continue to access services after an admin has revoked privileges from the service account the app is running under.

  • The refresh token timeout is therefore the maximum period during which a client app can access services without re-authentication.

The default access and refresh token timeout values are Pivotal’s recommended UAA token timeout values. Before altering token timeout settings, consider:

  • Short default token time out periods create overhead within your system.

    • A short access token timeout requires a client app to frequently request a replacement access token from the UAA server.
    • A short refresh token timeout requires frequent re-authentication, which might be impossible at the designated timeout frequency.

    Setting a short token timeout period, such as “0”, can result in rendering all associated services and resources inaccessible.

  • Long timeout periods represent a security risk.

    • A long access token timeout allows an authenticated process to continue accessing services and resources for a long period after an admin has revoked privileges from the service account used by the process.
    • A long refresh token timeout allows an already authenticated app to continue running for a long period of time on stale authentication credentials without being challenged to re-authenticate.

    Setting a long timeout period, such as one lasting days, can result in a client app running unchallenged for days.