UAA Concepts

This topic explains core concepts of User Accounts and Authentication (UAA).

Identity Zones

UAA is built to support a multi-tenant architecture. Each tenant is referred to as an identity zone.

Identity zones are configured with JSON payloads using a REST API. See examples in the UAA API documentation.

An identity zone is a logical boundary around the entities UAA manages. The entities in a zone include, but are not limited to:

  • client registrations
  • users
  • groups
  • group mappings
  • user approvals
  • identity providers and access
  • ID and refresh tokens

Having two identity zones is equivalent to standing up two separate UAA deployments, but using fewer resources. This type of resource management can reduce operational and maintenance overhead.


An identity zone is uniquely identified by a subdomain identifier in UAA. If a UAA deployment is hosted on the URL, identity zones are hosted as subdomains of that same deployment.

For example:

Default Zones

A UAA deployment always has one zone referred to as the default zone. The default zone is configured and bootstrapped using a YAML configuration file.


A user is the central domain object of the UAA server. Because UAA acts as both an account store and an authorization server, many different types of information are linked to users and can be accessed through user-centric API calls.

In its capacity as a user account store, UAA can provide unique attributes that describe an individual user, such as email, name, phone number, and group memberships. In addition to these attributes, UAA also tracks some dynamic user metadata, such as the last successful logon time and last updated time.

You can make additional attributes available if UAA is configured to use custom attribute mappings from an external identity provider, such as an existing LDAP or SAML provider. For more information about identity provider options, see Identity Providers in UAA.

External identity providers are read-only, as are attributes from those providers. Any change to the external user account should be performed on the external identity provider directly. These read-only attributes are refreshed each time the user authenticates with the external identity provider.

UAA can be used as an authorization server, which allows client applications to interact with resources on a user’s behalf using the four standard OAuth2 authorization grant flows for obtaining access tokens:

  • Authorization Code
  • Implicit
  • Resource Owner Password Credentials
  • Client Credentials

A UAA user fulfills the resource owner role of the OAuth2 protocol. Access tokens issued to the user contain scopes at the intersection of the requesting client’s allowed scopes and a user’s group memberships.

A string used to identify a user in APIs. This universally unique identifier is randomly generated at the time of user creation and does not change. It is guaranteed to be unique across all identity zones in the UAA deployment. The is a 128-bit number formatted as a UUID. This is also expressed as a “sub” claim in the tokens generated by UAA.


A user in UAA always belongs to a user store with an alias referred to as an origin. For example, users that are authenticated by the UAA itself with a username/password combination have their origin set to the value uaa.

The fixed origin values are:

  • uaa for users that are authenticated by the UAA deployment
  • ldap for users that are authenticated by the LDAP provider
  • {OIDC provider alias} for users authenticated via an OIDC provider
  • {SAML provider alias} for users authenticated via a SAML identity provider

Users that are authenticated with an external identity provider are often referred to as shadow users in UAA.


A user-readable string that refers to the user, typically an email address. The user enters their username when authenticating against UAA.

If the user authenticates against an external provider, the username is transferred from that provider to the shadow user in UAA. An individual user can be uniquely identified by the combination of the username and the origin values.

The username alone is not a unique value. Because usernames can change, UAA provides user IDs as unchanging references to a single user.

Users that create accounts through the UAA user interface use their email address as their username. The administrative API can create user accounts that specify arbitrary usernames.

For external providers, the username is mapped from the assertion received by UAA.

  • SAML: Retrieved from the nameID claim. For example:
    <saml2:NameID> Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
  • LDAP: Username derived from user input.
  • OIDC1.0 / OAuth2: UAA derives usernames from OpenID Connect and OAuth2 providers from the id_token, userinfo endpoint, or the access token. The usernames are returned in JSON Web Token (JWT) format. The name of the claim holding the username value can be configured and defaults to preferred_username.

User Groups

A user can belong to one or more groups. A group is a way to express a common group-based or role-based access control model. A group has a display name. This name, an arbitrary string, corresponds directly to a scope in a JWT access token and is used for access control by OAuth2 resource servers.

The common group attributes are as follows:

  • type: This can be one of two membership types, “DIRECT” and “INDIRECT.” “DIRECT means that the user is directly associated with the group. "INDIRECT” means that the membership has been inherited from the nested membership of groups.
  • display: The displayName of the group the user or the group belongs to. The displayName is an identifier that is unique to a given identity zone and is a representation of the access given to the user.

Note: To create a group, see the UAA API documentation. Add a user or group to a group through group-membership.

Default User Groups

UAA can be configured to have one or more default groups. These are groups that every user in the system is a member of, even if there is no direct relationship between user and group in the database.

Shadow Users

Users that have authenticated through an external identity provider still get assigned a record in the users table in the UAA database. These users are frequently referred to as shadow users. UAA internal users have an origin of uaa. Shadow users are differentiated from internal users with a different origin corresponding to the external identity provider. Each time an external user is authenticated and the assertion is passed to UAA, UAA refreshes the user information. This means that the information about a shadow user in UAA is accurate up to the last time UAA received an assertion with user information.

Shadow users have a different type of group membership. A shadow user can be associated with a group through its origin. This membership may also change each time a new assertion is received.

A shadow user can also have a group memberships defined using group_membership.origin='uaa'. These are memberships that remain persistent and do not change when assertions report a change in external group memberships. It also allows UAA operators to assign privileges to users that are not known by external providers or cannot be mapped to external groups.


UAA is an OAuth2 authorization server. Before applications can obtain access tokens, developers must perform a one-time registration process to create a client in the UAA.

A client usually represents an application with its own set of permissions and configurations. Clients are protected by simple credentials, such as client ID and secret, that applications use to authenticate themselves to the UAA in order to obtain tokens.

There are two types of clients: clients that access resources and request tokens from UAA with which to do so, and clients that represent resources and accept and validate access tokens.

Clients are created in UAA through client registration. Clients can be defined in UAA using the UAA configuration files or created using the UAA API.

Choosing Authorization Grant Types

To create a client, the application developer must specify which grant types should be permitted using their client. The grant type determines how your client can interact with UAA. Each grant types corresponds to one of the four different authorization flows defined in the OAuth2 spec. The available grant types on UAA include:

  • authorization_code
  • password
  • implicit
  • client_credentials

For increased security, use only the grant types your application requires. If necessary, however, you can assign multiple grant types to one client.

Selecting the Client Grant Type

The table below is intended to help you choose a grant type for your use case.

Grant type User Details
authorization_code Developers building web applications In the authorization code grant flow, the user is directed to a page on the UAA where they grant approvals to the client. After the user approves the requested scopes, they are redirected back to the client application with an authorization code in the URL parameters. The client application may then exchange the authorization code with UAA to obtain an access token.
password Developers building native desktop or mobile applications The name “password” refers to the Resource Owner Password Grant type. The user, who trusts the security of the application, provides their username and password to the client app which may then use them to obtain an access_token.
implicit Developers building a single page web application with no server backend The user is taken to a page on UAA where they are asked to grant approvals to the client, and after doing so they are redirected to the redirect_uri with the access token in the URI fragment.
client_credentials Developers use client_credentials when the client application needs to perform actions in UAA on its own behalf Actions where a client_credentials grant type might be appropriate include creating or destroying user groups, managing user group membership, or creating or destroying other clients. The client_credentials grant can be likened to service accounts in legacy application ecosystems.


A client is identified with a value up to 255 characters. Unlike the, the client_id is often a human readable identifier. For example, an application’s name could be it’s client_id. This identifier is unique within the identity zone.


Client authentication occurs via a password mechanism referred to as a client_secret. UAA allows client credentials to be asserted in two different ways:

  • With an HTTP authorization header using Basic authentication, or
  • By passing the client_id and client_secret as request parameters as part of an HTTP POST body using content type application/x-www-form-urlencoded.


The authorization_code and implicit grant types rely on a user-agent. A user agent like a web browser is responsible for performing HTTP redirects to UAA and receiving a response from UAA. That response can be in the form of an access token or a code that is exchanged for an access token later.

A client that supports either of these two flows must have at least one URL in the client configuration. Alternatively, you can use multiple URLs and wildcards (*) for ant path matching.

URLs are registered using a comma delimited string.


UAA validates access tokens up to the time those tokens expire. Clients do the same, if they can validate tokens offline. The access token validity is the value in seconds from the time the token was created to when it expires.


UAA validates access tokens up to the time those tokens expire. Clients do the same, if they can validate tokens offline. The access token validity is the value in seconds from the time the token was created to when it expires.

Choosing Scopes and Authorities

Client scopes are used to populate the scope claim when constructing an access token where the client acts on behalf of the user.

When an access token is created, UAA takes the user groups and intersects them with the client scopes. The intersection of these two fields are scopes that are eligible to be populated in the access token. There are two more validations that can further limit the scopes that get populated in the access token after the intersection has been decided:

  1. Did the user approve these scopes?
  2. Did the client request these scopes in the authorization request?

The token can never contain more scopes than the intersection between client scopes and user groups.


Scopes in an access token have to be approved by the granting entity.

During a client_credentials grant, the client itself is the granting entity and the client authorities are automatically assumed to be approved.

During a password grant, the user shares their password with the client application. This sharing is considered the implicit approval of the scopes that the client wish to be populated in the access token.

Two grant types, authorization_code and implicit, require specific user approval for the scopes to populate in the access token. UAA provides a UI that lets the user approve or deny scopes from being populated in the access token.

During client registration, the operator can configure the client to bypass this approval process by setting the auto-approve values to a single string with the value of true. This results in any requested scope being approved automatically.

The value can also be a comma delimited list of selected scopes that would not require user approval.


Clients can store custom attributes in a field called additional_information. This is a simple key value store.

Key Value
allowed providers You can limit what applications can be used by what users. For example, in a Cloud Foundry deployment, you may have set up multiple identity providers. For example, you could be using Facebook and your organization’s LDAP system.

You can limit UAA to only issue an application tokens if the users are from a certain provider. You would configure the application’s client to have allowed providers="ldap". The value is a comma delimited string of Identity Provider.origin values.
created with UAA stores the scope zones.write in this field if the client was created using the /identity-zones endpoint. This field is used by the UAA to allow clients to be deleted by the same endpoint. It is not a configurable field, instead used by the UAA.
name Various tooling in the Cloud Foundry ecosystem creates clients with generated Client.client_id values. These tools often store a human readable name in this field.
approvals_deleted Contains a boolean value if performing an operation on the client resulted in all the client’s user approvals were deleted. For example, changing the Client.client_secret value causes UAA to delete all the approvals. UAA then stores a value of true in this field.
token_salt Tokens, even stateless JWT, can be revoked. By revoked, we mean they do not pass a UAA token validation when the token is passed to the /check_token endpoint. UAA revokes a token if the client’s secret has changed. There may be instances to revoke all tokens for a certain client without having to change the client secret. This can be achieved by changing the token_salt. token_salt is an arbitrary string value that is used to generate a hash.
Create a pull request or raise an issue on the source for this page in GitHub