CloudFoundry UAA Server: OAuth2 Identity Service
CloudFoundry UAA Server is the identity service Cloud Foundry itself runs in production, which says more about reliability than any star count would. Reach for it if you already run Cloud Foundry or BOSH, or want a self-hosted OAuth2 provider with SCIM user management built in. Skip it if you need full OpenID Connect out of the box — the README flags its OIDC support as partial — or don't want a Java/Tomcat/Gradle stack just for auth.
Understanding CloudFoundry UAA Server
CloudFoundry UAA Server is a multi-tenant identity management service that began life inside Cloud Foundry but also runs as a standalone OAuth2 server. It's a plain Spring MVC web application, with no proprietary runtime, that issues OAuth2 tokens, authenticates users against their Cloud Foundry credentials or other sources, and acts as an SSO service. It also exposes endpoints for managing user accounts and registering OAuth2 clients.
Core Identity and Access Features
- ✓OAuth2 provider — implements the /oauth/authorize and /oauth/token endpoints from the UAA-APIs spec, issuing tokens that client apps use on behalf of Cloud Foundry users.
- ✓Partial OpenID Connect support — exposes OpenID Connect endpoints including /userinfo, though the README explicitly calls this support partial rather than full OIDC compliance.
- ✓SCIM user provisioning endpoint for creating and managing user accounts, plus endpoints for registering OAuth2 clients.
- ✓Token introspection via /check_token, so resource servers can validate a token submitted by an OAuth2 client, and /token_key to fetch the signature verification key.
- ✓/login_info endpoint that lets a client query which login prompts are required before authenticating.
- ✓Multi-tenant identity zones — the Postgres schema in the README includes an identity_zone table alongside oauth_client_details, groups, and group_membership, reflecting the multi-tenant design.
- ✓Documented LDAP integration that lets UAA authenticate against an external LDAP directory, tested in the README's own instructions against an OpenLDAP container from Bitnami.
- ✓Built-in SSO — once authenticated, UAA can act as a single sign-on service for other apps sharing the same credentials.
Typical Authentication Flows
- •Interactive login — GET /login serves a basic HTML form for users to sign in directly.
- •Authorizing a client app — GET /oauth/authorize?client_id=...&response_type=code drives the standard OAuth2 authorization code flow so a third-party app can request access on a user's behalf.
- •Exchanging a code for a token — POST /oauth/token completes the flow and hands the client an access token.
- •Command-line authentication — CLI clients can submit credentials straight to /oauth/authorize, and Java clients can use Spring Security OAuth's ImplicitAccessTokenProvider to handle that flow.
- •Acting as the Cloud Foundry auth layer — issuing tokens that back-end services and apps use when delegating on behalf of Cloud Foundry users.
Quick Start and Deployment Options
Clone the repo and run `./gradlew run` (or `./gradlew bootRun`) from the `uaa` directory — the README's own quick-start line is 'if this works, you are in business.' Requirements: Java 25. Running through Gradle, it listens on port 8080 and is reachable at http://localhost:8080/uaa (with /app and /api on the same port). Logs go to a file called uaa.log; the README suggests finding it with `sudo lsof | grep uaa.log`, typically under scripts/boot/tomcat/logs/. Verify it's up with `curl --silent --show-error --head localhost:8080/uaa/login | head -1`, which should return HTTP/1.1 200. For anything beyond a demo, deploy the built WAR into Tomcat or another servlet container instead of running through Gradle. Three Gradle tasks cover different run modes — `./gradlew run` (kills any running UAA and restarts, recommended), `./gradlew bootRun` (the standard Spring Boot task), and `./gradlew bootWarRun` (runs the packaged .war). By default it runs against HSQLDB; switching to MySQL or PostgreSQL means starting a database yourself (the README has Docker examples) and passing `-Dspring.profiles.active=mysql` or `=postgresql`.
Strengths
- ✓It's the actual identity component Cloud Foundry runs in production, not a demo project — the SCIM, OAuth2, and identity-zone tables in its own schema reflect real multi-tenant operational use.
- ✓Covers the core OAuth2 surface (authorize, token, check_token, token_key) plus SCIM provisioning in one deployable app, so you're not wiring together separate services for auth, tokens, and user management.
- ✓Runs against your choice of HSQLDB, MySQL, or PostgreSQL, and ships Docker Compose files for spinning up Postgres 15 or MySQL 8 for testing.
- ✓LDAP integration is documented and testable locally via Docker Compose against an OpenLDAP container, not just described in prose.
- ✓Kubernetes deployment is documented separately with a published Docker image, so you're not limited to Tomcat or VM deployment.
Known Limitations and Considerations
- △OpenID Connect support is explicitly partial per the README, not a full spec implementation — don't assume every OIDC endpoint is available out of the box.
- △It's a Java/Spring stack that needs Tomcat (or another container) plus Gradle to build; the README doesn't describe a lightweight Docker Compose quick start for production, so you're deploying a WAR yourself.
- △Default local runs use HSQLDB, an embedded database not meant for production; getting to MySQL or PostgreSQL means standing up containers and setting Gradle profile flags yourself.
- △Debugging and testing are Gradle-centric (`./gradlew run -Pdebug`, `run-integration-tests.sh`, `--no-daemon` test runs) — comfortable if you already work in the JVM ecosystem, friction if you don't.
- △Generating the API docs requires a separate Ruby toolchain (Ruby 3.3.8 via rbenv, plus Bundler) alongside the Java/Gradle build, an extra moving part just to read current docs.
Exploring Identity Management Alternatives
Frequently Asked Questions
CloudFoundry UAA Server is open source, released under the Apache-2.0 license and developed publicly on GitHub, where it currently has 1,636 stars and 842 forks.
CloudFoundry UAA Server implements OAuth2 as its primary protocol, handling the /oauth/authorize and /oauth/token endpoints, and layers OpenID Connect endpoints like /userinfo on top — though the README describes that OpenID Connect support as partial rather than complete.
CloudFoundry UAA Server can run in containers: the README documents deploying it on Kubernetes using a published Docker image, and its own test setup runs UAA plus LDAP and a database inside Docker containers.
CloudFoundry UAA Server runs against HSQLDB by default for local development, and the README documents Spring profiles for switching to MySQL or PostgreSQL for production-style setups.
CloudFoundry UAA Server is written in Java, built as a plain Spring MVC web application and packaged as a WAR file.
Contributions to CloudFoundry UAA Server go through GitHub pull requests against the 'develop' branch, ideally referencing an existing issue and including tests per the project's test-driven development practice; the team also runs a #uaa Slack channel for discussion.
The problem it solves
Cloud Foundry needed a single service that could issue OAuth2 tokens, authenticate users against their Cloud Foundry credentials, and manage both user accounts and registered OAuth2 clients — without every platform component reimplementing its own login and token logic. CloudFoundry UAA Server is that piece: the identity and token-issuing layer the rest of the Cloud Foundry platform, and your own apps if you want, delegate to instead of building auth from scratch.
Who should try it — and who should skip
Try CloudFoundry UAA Server if you're already operating Cloud Foundry or a BOSH-deployed platform and need the matching identity component, or if you want a self-hosted, Spring-based OAuth2 server with SCIM user provisioning and are comfortable running a Java/Tomcat/Gradle stack. Skip it if you need full OpenID Connect compliance today — the README calls its OIDC support partial — or if maintaining a JVM service just to handle login and tokens for a small app feels like overkill; a lighter or more OIDC-complete identity provider fits better there.