It is the responsibility of a Resource Server to extract information about the user and client application from the access token and make an access decision based on that information.
This guide will help authors of resource Servers and maintainers of client and user account data to understand the range of information available and the kinds of decisions that can be taken.
The UAA itself is a Resource Server, so the access decisions taken by the UAA are used as an example.
User accounts are either of type "user" or type "admin" (using the
SCIM type field from the core schema). These translate into granted
authorities, [uaa.user] or [uaa.admin,uaa.user] respectively, for
the purposes of access decisions within the UAA (i.e. admin users also
have the user role). Granted authorities are not directly visible to
Resource Servers, but they show up as scopes in the access tokens.
Resource Servers may choose to use this information as part of an access decision, and this may be good enough for simple use cases (e.g. users belong to a small number of relatively static roles), but in general they will need to maintain their own acess decision data since roles on UAA don't necessarily correspond to the same thing on a Resource Server.
Support for SCIM groups is currently provided only through the authorities attribute of the user object. Resource Servers that are also SCIM clients can modify this attribute themselves, but it might be better (and safer) if the data don't change much to have an admin user or client do the role assignments. In any case it is recommended that Resource Servers have sensible defaults for new users that have not yet been assigned a role.
There are 2 distinct scenarios:
Demo or test with vanilla code and no special environment. A UAA service started with no active Spring profile will initialize a single user account (marissa/koala).
A vcap environment: integration testing or in production. If the
service starts with any active Spring profile, by default it will not
touch the user database. The SCIM endpoints can be used to provision
user accounts, once a client with the correct privileges has been
registered.
In either case, additional user accounts and client registrations can
be bootstrapped at start up by providing some data in uaa.yml.
Example users:
scim:
users:
- paul|wombat|[email protected]|Paul|Smith|uaa.admin
- stefan|wallaby|[email protected]|Stefan|Schmidt
The format for the user is
username|password|email|first_name|last_name(|comma-separated-authorities).
Remember that authorities are represented as groups in SCIM.
In its default configuration, the UAA does not lock accounts permanently when a user repeatedly fails authentication. Instead it temporarily locks a user out for a short period (5 minutes by default) after 5 failed logins within the previous hour. The failure count is reset when a user successfully authenticates.
Client application meta data can be used by Resource Servers to make an access decision, and by the Authorization Server (the UAA itself) to decide whether to grant an access token.
Scope values are arbitrary strings, but are a contract between a
Client Application and a Resource Server, so in cases where UAA acts as a Resource
Server there are some "standard" values (scim.read, scim.write,
passsword.write, openid, etc.) whose usage and meaning is
described below.
Scopes are used by the Authorization Server to deny a token requested for a scope not on the list, and should be used by a Resource Server to deny access to a resource if the token has insufficient scope.
UAA client applications have the following meta data (some are optional, but to prevent mistakes it is usually better to use a default value):
client_credentials,
password, implicit, refresh_token, authorization_code. Used
by the Authorization Server to deny a token grant if it is not on
the list. If in doubt use authorization_code and refresh_token.client_credentials grants).
Also used as the default scopes for a token where the client does
not explicitly specify scopes in the authorization request.uaa.admin or any valid scope value). The authorities are
used to define the default scopes that are assigned to a token in a
client_credentials grant, and to limit the legal values if
explicit scopes are requested in that case.none for all clients), but instead creates
a list of resource ids dynamically from the scope values when a
token is granted. The resource id is extracted from a scope using a
period separator (the last occurrence in the string) except for some
standard values (e.g. openid) that are not controlled by the UAA
or its own resources. So a scope of cloud_controller.read is
assigned a resource id of cloud_controller, for instance.Client registration can be initialized by adding client details data
to uua.yml. The UAA always starts with a registered admin client.
There are 2 typical scenarios for additional client registration
bootstraps:
Demo or test with vanilla code and no custom uaa.yml. A UAA
service started with no active Spring profile will start with some
client registrations (used in samples to make the out-of-the box
experience for new users as convenient as possible). More clients and
user accounts will be created by the integration tests.
A vcap environment: integration testing or in production. By
default no clients are created if any Spring profile is active, but
client registrations can be configured in uaa.yml and in some
well-known situations clients this will happen. In particular, the
dev_setup environment and the CF.com deployment job both start up
with additional client registrations that are needed by the basic
Cloud Foundry use cases (vmc and cloud_controller). If the
vcap Spring profile is active in the integration tests, no additional
accounts will be created.
Clients are bootstrapped from config if they are not present in the backend when the system starts up (i.e. once the system has started up once, config changes will not affect the client registrations for existing clients). Certain fields (e.g. secret) can be reset if the bootstrap component is configured to do so (it is not by default).
The admin client has the following properties (in the default
uaa.yml always present on the classpath but overriddable by
specifying all the values again in a custom config file):
id: admin
secret: adminsecret
authorized-grant-types: client_credentials
scope: none
authorities: uaa.admin,clients.read,clients.write,clients.secret
The admin client can be used to bootstrap the system by adding
additional clients. In particular, user accounts cannot be
provisioned until a client with access to the scim resource is
added.
The default Spring profile initializes 3 clients in addition to the
admin client, e.g. if the server is started from the command line
after a fresh clone from github for demo purposes:
vmc:
id: vmc
authorized-grant-types: implicit
scope: cloud_controller.read,cloud_controller.write,openid,password.write
authorities: uaa.none
resource-ids: none
app:
id: app
secret: appclientsecret
authorized-grant-types: password,authorization_code,refresh_token
scope: cloud_controller.read,cloud_controller.write,openid,password.write,tokens.read,tokens.write
authorities: uaa.none
resource-ids: none
In dev_setup these client accounts (in addition to the admin client)
are initialized:
cloud_controller:
authorized-grant-types: client_credentials
scope: none
authorities: scim.read,scim.write,password.write,tokens.read,tokens.write
id: cloud_controller
secret: ...
resource-ids: none
vmc:
id: vmc
authorized-grant-types: implicit
scope: cloud_controller.read,cloud_controller.write,openid,password.write
authorities: uaa.none
resource-ids: none
redirect-uri: http://uaa.cloudfoundry.com/redirect/vmc
The cloud controller secret is generated during the setup. The same
clients are initialized in CF.com, but the secret is different.
Additional clients can be added during start up using uaa.yml, e.g.
oauth:
clients:
vmc:
authorized-grant-types: implicit
scope: cloud_controller.read,cloud_controller.write,password.write,openid
authorities: uaa.none
id: vmc
resource-ids: none
redirect-uri: http://uaa.cloudfoundry.com/redirect/vmc
When a client application asks for a new access token it can
optionally provide a set of requested scopes (space separated,
e.g. scope=openid cloud_controller.read). The UAA will use that set
if provided and that will be the scope of the token if
granted. Otherwise, if no explicit value is requested, defaults will
be supplied according to what the client and user are allowed to do.
The rules governing the defaults and what is allowed are described
next.
A token granted on behalf of a user (grant type anything except
client_credentials) takes its default scopes from the scope field
of the client registration. Whether or not the default values are
used, the requested scopes are then validated:
[openid, cloud_controller.read, cloud_controller.write]Note that the filtering of scopes by user authorities might mean that
a client gets a narrower-scoped token than it originally asked for,
e.g. if it asks for no scope=dash.admin dash.user openid, the token
might come back with only dash.user openid. Tokens are opaque to
client applications, so they have to be prepared for resource servers
to deny access to some resources based on the scope of the token when
it is presented.
A token issued on a client_credentials grant has default and allowed
scopes equal to the client authorities. Requesting a disallowed scope
will result in a 400 reponse and an error message that indicates the
allowed scopes. A client would normally take the default scopes when
acting on its own behalf - since no approval is necessary there is no
point narrowing the scope.
All OAuth2 protected resource have an id (as listed individually).
Any request whose token does not have a matching resource id (aud
field in decoded token) will be rejected. Resources that are not
OAuth2 protected resources do not have a resource id (e.g. those with
simple HTTP Basic authentication).
Resource ID = tokens. Rules:
uaa.admin, ortokens.writeuaa.admin ortokens.readuaa.admin ortokens.writeuaa.admin ortokens.readResource ID = clients. Rules:
clients.writeclients.readResource ID null (so all clients can change their password). Rule:
clients.secretuaa.admin or client can only change its own secretuaa.admin or client provides the old secretuaa.admin client must provide the old value to change its own secretResource ID = password. Rules:
password.writeuaa.adminuaa.admin or user provides the old passwordResource ID = scim. Rules:
List or search users
scim.read provides read/query access to ALL users in the UAADelete, add user account
scim.writeUpdate existing user account
scim.write lets you update ANY user's information in the UAAIn addition, a User Token obtained by a client with authorities scim.me (eg. token from authorization_code
or password grant flow) provides read/query/update access to that particular user's account.
Resource ID = scim. Rules:
/ids/Usersfilter parameter must be supplieduserName and id are returned (and can be queried on)Used for Single Sign On ( OpenID Connect lite ). Resource ID = openid. Rules:
openidResource ID = scim. Rules:
List or Search groups
scim.readDelete or Add groups
scim.writeUpdate group name or add/remove members
scim.write OR groups.updateThe UAA is the identity management service for Cloud Foundry. It's primary role is as an OAuth2 provider, issuing tokens for client applications to use when they act on behalf of Cloud Foundry users.
It can also authenticate users with their Cloud Foundry credentials, and can act as an SSO service using those credentials (or others). It has endpoints for managing user accounts and for registering OAuth2 clients, as well as various other management functions.
If this works you are in business:
$ git clone git://github.com/cloudfoundry/uaa.git
$ cd uaa
$ mvn install
Each module has a mvn tomcat:run target to run individually, or you
could import them as projects into STS (use 2.8.0 or better if you
can). The apps all work together the apps running on the same port
(8080) as /uaa, /app and /api.
You will need Maven 3.0.4 or newer.
You can also build the app and push it to Cloud Foundry, e.g.
$ mvn package install
$ vmc push myuaa --path uaa/target
(If you do that, choose a unique application id, not 'myuaa'.)
First run the UAA server as described above:
$ cd uaa
$ mvn tomcat:run
Then start another terminal and from the project base directory, ask the login endpoint to tell you about the system:
$ curl -H "Accept: application/json" localhost:8080/uaa/login
{
"timestamp":"2012-03-28T18:25:49+0100",
"commit_id":"111274e",
"prompts":{"username":["text","Username"],
"password":["password","Password"]
}
}
Then you can try logging in with the UAA ruby gem. Make sure you have ruby 1.9, then
$ gem install cf-uaac
$ uaac target http://localhost:8080/uaa
$ uaac token get marissa koala
(or leave out the username / password to be prompted).
This authenticates and obtains an access token from the server using
the OAuth2 implicit grant, similar to the approach intended for a
client like VMC. The token is stored in ~/.uaac.yml, so dig into
that file and pull out the access token for your vmc target (or use
--verbose on the login command line above to see it logged to your
console).
Then you can login as a resource server and retrieve the token details:
$ uaac target http://localhost:8080/uaa
$ uaac token decode [token-value-from-above]
You should see your username and the client id of the original token grant on stdout, e.g.
exp: 1355348409
user_name: marissa
scope: cloud_controller.read openid password.write scim.userids tokens.read tokens.write
email: [email protected]
aud: scim tokens openid cloud_controller password
jti: ea2fac72-3f51-4c8f-a7a6-5ffc117af542
user_id: ba14fea0-9d87-4f0c-b59e-32aaa8eb1434
client_id: vmc
The same command line example should work against a UAA running on cloudfoundry.com (except for the token decoding bit because you won't have the client secret). In this case, there is no need to run a local uaa server, so simply ask the external login endpoint to tell you about the system:
$ curl -H "Accept: application/json" uaa.cloudfoundry.com/login
{
"prompts":{"username":["text","Username"],
"password":["password","Password"]
}
}
You can then try logging in with the UAA ruby gem. Make sure you have ruby 1.9, then
$ gem install cf-uaac
$ uaac target uaa.cloudfoundry.com
$ uaac token get [yourusername] [yourpassword]
(or leave out the username / password to be prompted).
This authenticates and obtains an access token from the server using the OAuth2 implicit grant, the same as used by a client like VMC.
With all apps deployed into a running server on port 8080 the tests
will include integration tests (a check is done before each test that
the app is running). You can deploy them in your IDE or using the
command line with mvn tomcat:run and then run the tests as normal.
For individual modules, or for the whole project, you can also run integration tests and the server from the command line in one go with
$ mvn test -P integration
(This might require an initial mvn install from the parent directory
to get the wars in your local repo first.)
To make the tests work in various environments you can modify the configuration of the server and the tests (e.g. the admin client) using a variety of mechanisms. The simplest is to provide additional Maven profiles on the command line, e.g.
$ (cd uaa; mvn test -P vcap)
will run the integration tests against a uaa server running in a local
vcap, so for example the service URL is set to uaa.vcap.me (by
default). There are several Maven profiles to play with, and they can
be used to run the server, or the tests or both:
local: runs the server on the ROOT context http://localhost:8080/
vcap: also runs the server on the ROOT context and points the
tests at uaa.vcap.me.
devuaa: points the tests at http://devuaa.cloudfoundry.com (an
instance of UAA deployed on cloudfoundry).
All these profiles set the CLOUD_FOUNDRY_CONFIG_PATH to pick up a
uaa.yml and (if appropriate) set the context root for running the
server (see below for more detail on that).
There is a really simple cucumber feature spec (--tag @uaa) to
verify that the UAA server is there. There is also a rake task to
launch the integration tests from the uaa submodule in vcap.
Typical usage for a local (uaa.vcap.me) instance:
$ cd vcap/tests
$ rake bvt:run_uaa
You can change the most common important settings with environment
variables (see below), or with a custom uaa.yml. N.B. MAVEN_OPTS
cannot be used to set JVM system properties for the tests, but it can
be used to set memory limits for the process etc.
To modify the runtime parameters you can provide a uaa.yml, e.g.
$ cat > /tmp/uaa.yml
uaa:
host: uaa.appcloud21.dev.mozycloud
test:
username: [email protected] # defaults to [email protected]
password: changeme
email: [email protected]
then from vcap-tests
$ CLOUD_FOUNDRY_CONFIG_PATH=/tmp rake bvt:run_uaa
or from uaa/uaa
$ CLOUD_FOUNDRY_CONFIG_PATH=/tmp mvn test
The integration tests look for a Yaml file in the following locations (later entries override earlier ones), and the webapp does the same when it starts up so you can use the same config file for both:
classpath:uaa.yml
file:${CLOUD_FOUNDRY_CONFIG_PATH}/uaa.yml
file:${UAA_CONFIG_FILE}
${UAA_CONFIG_URL}
To test against a vcap instance use the Maven profile vcap (it
switches off some of the tests that create random client and user
accounts):
$ (cd uaa; mvn test -P vcap)
To change the target server it should suffice to set
VCAP_BVT_TARGET (the tests prefix it with uaa. to form the
server url), e.g.
$ VCAP_BVT_TARGET=appcloud21.dev.mozycloud mvn test -P vcap
You can also override some of the other most important default
settings using environment variables. The defaults as usual come from
uaa.yml but tests will search first in an environment variable:
UAA_ADMIN_CLIENT_ID the client id for bootstrapping client
registrations needed for the rest of the tests.
UAA_ADMIN_CLIENT_SECRET the client secret for bootstrapping client
registrations
All other settings from uaa.yml can be overridden individually as
system properties. Running in an IDE this is easy just using whatever
features allow you to modify the JVM in test runs, but using Maven you
have to use the argLine property to get settings passed onto the
test JVM, e.g.
$ mvn -DargLine=-Duaa.test.username=foo test
will create an account with userName=foo for testing (instead using
the default setting from uaa.yml).
If you prefer environment variables to system properties you can use a
custom uaa.yml with placeholders for your environment variables,
e.g.
uaa:
test:
username: ${UAA_TEST_USERNAME:marissa}
will look for an environment variable (or system property)
UAA_TEST_USERNAME before defaulting to marissa. This is the trick
used to expose UAA_ADMIN_CLIENT_SECRET etc. in the standard
configuration.
The default uaa unit tests (mvn test) use hsqldb.
To run the unit tests using postgresql:
$ SET SPRING_PROFILES_ACTIVE=test,postgresql
& SET CLOUD_FOUNDRY_CONFIG_PATH=src/test/resources/test/profiles/postgresql
& mvn test
To run the unit tests using mysql:
$ SET SPRING_PROFILES_ACTIVE=test,mysql
$ SET CLOUD_FOUNDRY_CONFIG_PATH=src/test/resources/test/profiles/mysql
& mvn test
The database configuration for the common and scim modules is located at:
common/src/test/resources/(mysql|postgresql).properties
scim/src/test/resources/(mysql|postgresql).properties
There are actually several projects here, the main uaa server application and some samples:
common is a module containing a JAR with all the business logic. It is used in
the webapps below.
uaa is the actual UAA server
gem is a ruby gem (cf-uaa-client) for interacting with the UAA server
api (sample) is an OAuth2 resource service which returns a mock list of deployed apps
app (sample) is a user application that uses both of the above
login (sample) is an application that performs authentication for the UAA acting as a back end service
In CloudFoundry terms
uaa provides an authentication service plus authorized delegation for
back-end services and apps (by issuing OAuth2 access tokens).
api is a service that provides resources that other applications may
wish to access on behalf of the resource owner (the end user).
app is a webapp that needs single sign on and access to the api
service on behalf of users.
login is where Cloud Foundry administrators set up their
authentication sources, e.g. LDAP/AD, SAML, OpenID (Google etc.) or
social. The cloudfoundry.com platform uses a different
implementation of the
login server.
The authentication service is uaa. It's a plain Spring MVC webapp.
Deploy as normal in Tomcat or your container of choice, or execute
mvn tomcat:run to run it directly from uaa directory in the source
tree (make sure the common jar is installed first using mvn install
from the common subdirectory or from the top level directory). When
running with maven it listens on port 8080.
The UAA Server supports the APIs defined in the UAA-APIs document. To summarise:
The OAuth2 /authorize and /token endpoints
A /login_info endpoint to allow querying for required login prompts
A /check_token endpoint, to allow resource servers to obtain information about an access token submitted by an OAuth2 client.
SCIM user provisioning endpoint
OpenID connect endpoints to support authentication /userinfo and /check_id (todo). Implemented roughly enough to get it working (so /app authenticates here), but not to meet the spec.
Authentication can be performed by command line clients by submitting
credentials directly to the /authorize endpoint (as described in
UAA-API doc). There is an ImplicitAccessTokenProvider in Spring
Security OAuth that can do the heavy lifting if your client is Java.
By default uaa will launch with a context root /uaa. There is a
Maven profile local to launch with context root /, and another
called vcap to launch at / with a postgresql backend.
There is a uaa.yml in the application which provides defaults to the
placeholders in the Spring XML. Wherever you see
${placeholder.name} in the XML there is an opportunity to override
it either by providing a System property (-D to JVM) with the same
name, or a custom uaa.yml (as described above).
All passwords and client secrets in the config files are plain text, but they will be inserted into the UAA database encrypted with BCrypt.
The default is to use an in-memory RDBMS user store that is
pre-populated with a single test users: marissa has password
koala.
To use Postgresql for user data, activate one of the Spring profiles
hsqldb or postgresql.
The active profiles can be configured in uaa.yml using
spring_profiles: postgresql
or by passing the spring.profiles.active parameter to the JVM. For,
example to run with an embedded HSQL database:
mvn -Dspring.profiles.active=hsqldb tomcat:run
Or to use PostgreSQL instead of HSQL:
mvn -Dspring.profiles.active=postgresql tomcat:run
To bootstrap a microcloud type environment you need an admin client.
For this there is a database initializer component that inserts an
admin client. If the default profile is active (i.e. not
postgresql) there is also a vmc client so that the gem login works
out of the box. You can override the default settings and add
additional clients in uaa.yml:
oauth:
clients:
admin:
authorized-grant-types: client_credentials
scope: read,write,password
authorities: ROLE_CLIENT,ROLE_ADIN
id: admin
secret: adminclientsecret
resource-ids: clients
The admin client can be used to create additional clients (but not to
do anything much else). A client with read/write access to the scim
resource will be needed to create user accounts. The integration
tests take care of this automatically, inserting client and user
accounts as necessary to make the tests work.
An example resource server. It hosts a service which returns
a list of mock applications under /apps.
Run it using mvn tomcat:run from the api directory (once all other
tomcat processes have been shutdown). This will deploy the app to a
Tomcat manager on port 8080.
This is a user interface app (primarily aimed at browsers) that uses
OpenId Connect for authentication (i.e. SSO) and OAuth2 for access
grants. It authenticates with the Auth service, and then accesses
resources in the API service. Run it with mvn tomcat:run from the
app directory (once all other tomcat processes have been shutdown).
The application can operate in multiple different profiles according
to the location (and presence) of the UAA server and the Login
application. By default it will look for a UAA on
localhost:8080/uaa, but you can change this by setting an
environment variable (or System property) called UAA_PROFILE. In
the application source code (src/main/resources) you will find
multiple properties files pre-configured with different likely
locations for those servers. They are all in the form
application-<UAA_PROFILE>.properties and the naming convention
adopted is that the UAA_PROFILE is local for the localhost
deployment, vcap for a vcap.me deployment, staging for a staging
deployment (inside VMware VPN), etc. The profile names are double
barrelled (e.g. local-vcap when the login server is in a different
location than the UAA server).
See all apps
GET /app/apps
browser is redirected through a series of authentication and access grant steps (which could be slimmed down to implicit steps not requiring user at some point), and then the photos are shown.
See the currently logged in user details, a bag of attributes grabbed from the open id provider
GET /app
A user interface for authentication. The UAA can also authenticate user accounts, but only if it manages them itself, and it only provides a basic UI. The Login app can be branded and customized for non-native authentication and for more complicate UI flows, like user registration and password reset.
The login application is actually itself an OAuth2 endpoint provider,
but delegates those features to the UAA server. Configuration for the
login application therefore consists of locating the UAA through its
OAuth2 endpoint URLs, and registering the login application itself as
a client of the UAA. There is a login.yml for the UAA locations,
e.g. for a local vcap instance:
uaa:
url: http://uaa.vcap.me
token:
url: http://uaa.vcap.me/oauth/token
login:
url: http://uaa.vcap.me/login.do
and there is an environment variable (or Java System property),
LOGIN_SECRET for the client secret that the app uses when it
authenticates itself with the UAA. The Login app is registered by
default in the UAA only if there are no active Spring profiles (so not
at all in vcap). In the UAA you can find the registration in the
oauth-clients.xml config file. Here's a summary:
id: login
secret: loginsecret
authorized-grant-types: client_credentials
authorities: ROLE_LOGIN
resource-ids: oauth
Authenticate
GET /login
The sample app presents a form login interface for the backend UAA, and also an OpenID widget so the user can authenticate using Google etc. credentials.
Approve OAuth2 token grant
GET /oauth/authorize?client_id=app&response_type=code...
Standard OAuth2 Authorization Endpoint. Client credentials and
all other features are handled by the UAA in the back end, and the
login application is used to render the UI (see
access_confirmation.jsp).
Obtain access token
POST /oauth/token
Standard OAuth2 Authorization Endpoint passed through to the UAA.
Handles authentication on cloudfoundry.com and delegates all other
identity management tasks to the UAA. Also provides OAuth2 endpoints
issuing tokens to client apps for cloudfoundry.com (the tokens come
from the UAA and no data are stored locally).
The Login Server is a standard JEE servlet application, and you can
build a war file and deploy it to any container you like (mvn package and look in the target directory). For convenience there
is also a Maven profile that will run the Login Server, the UAA and
some sample apps all in the same container from the command line
(assuming you have the UAA and Login Server cloned in separate
directories with a common parent):
$ (cd uaa; mvn clean install)
$ cd login-server
$ mvn clean install
$ mvn tomcat:run -P integration
(Note that the tomcat7 plugin at the moment does not support running
multiple apps in the same container - it's a bug that is fixed but not
released as of September 2012.)
You can run the Login Server integration tests using the command line as well (as long as the UAA project is built and installed first as above):
$ mvn test -P integration
The Login Server:
Request: GET /login?error={error}
Response Body: form with all the relevant prompts
Response Codes: 200 - Success
Browser POSTs to /login.do with user credentials (same as UAA).
Login Server returns a cookie that can be used to authenticate future
requests (until the session expires or the user logs out).
The Login Server is a Single Sign On server for the Cloud Foundry platform (and possibly user apps as well), so if a user logs out he logs out of all the apps. Users need to be reminded of the consequences of their actions, so the recommendation for application authors is to
Request: GET /logout.do?redirect=http://myclient/loggedout
Request Headers: Cookie: JSESSIONID=8765FDUAYSFT7897
Response Codes:
200 - OK (if no redirect supplied)
302 - FOUND (if redirect supplied)
The standard authorize and token endpoints are available on the Login Server. They are passed through the request to the UAA, getting JSON responses from the UAA and re-rendering them if the user requested HTML.
Client applications usually send a redirect to User's browser with the request URI appropriate to the Client. Exactly the same as the UAA, but the response is rendered differently.
Request: example
GET /oauth/authorize?response_type=code&
redirect_uri=https://myclient/callback&
client_id=myclient&
state=RANDOM
The request must be authenticated as a user, so usually a session
cookie (JSESSIONID) is required, having been obtained previously
through the Login page.
Exactly the same as the UAA. When user approves the browser sends
user_oauth_approval=true (or false) and the Login Server sends back
an authorization code (if one was previously requested).
Obtain an access token, typically either with an authorization code or client credentials. Exactly the same as the UAA.
Reports basic information about the build (version and git commit id) and also passes through the information about prompts from the UAA. Unauthenticated.
Returns "ok" in the response body if the server is up and running
Reports basic management information about the Login Server and the
JVM it runs in (memory usage etc.). Secured with HTTP Basic
authentication using credentials that are advertised on NATS in Cloud
Foundry (for a standalone instance the default is
varz:varzclientsecret).
Request: GET /varz
Response Body:
{
"type": "Login",
"links": {
"JMImplementation": "http://localhost:8080/uaa/varz/JMImplementation",
"spring.application": "http://localhost:8080/uaa/varz/spring.application",
"com.sun.management": "http://localhost:8080/uaa/varz/com.sun.management",
"Catalina": "http://localhost:8080/uaa/varz/Catalina",
"env": "http://localhost:8080/uaa/varz/env",
"java.lang": "http://localhost:8080/uaa/varz/java.lang",
"java.util.logging": "http://localhost:8080/uaa/varz/java.util.logging"
},
"mem": 19173496,
"memory": {
"verbose": false,
"non_heap_memory_usage": {
"max": 184549376,
"committed": 30834688,
"init": 19136512,
"used": 30577744
},
"object_pending_finalization_count": 0,
"heap_memory_usage": {
"max": 902299648,
"committed": 84475904,
"init": 63338496,
"used": 19173496
}
},
"spring.profiles.active": []
}
For user-facing account management UIs (e.g. portal) that need to set or reset users' passwords it is convenient to be able to log them in immediately, rather than waiting for them to come back to the Login Server and enter the new password explicitly.
Client POSTs user credentials to /autologin
Login Server responds with autologin code (short-lived, one-time)
Client builds redirect URI to Login Server /authorize endpoint
(normal OAuth2 auth code flow) appending the code
Client sends redirect to User
User's browser initiates auth code flow
Login Server redeems autologin code and exchanges it for an authenticated user (as if the user had authenticated with the Login Server manually)
User's browser now has SSO cookie for Login Server, and remains logged in for the duration of that session.
Gets a short-lived code that can be exchanged for an authentication at
the Login Server /oauth/authorize UI. The client authenticates
itself with its secret using an HTTP Basic header.
Request: POST /autologin
Request Body: Form encoded user credentials
username=<username>&password=<password>
Request Headers:
Authorization: Basic <...>
Response Body:
{ "code"="aiuynklj", "path"="/oauth/authorize" }
By default the password is required and is checked using the
login.do endpoint at the UAA, but could be made optional or changed
to other authentication credentials with a configuration change in the
Login Server (by adding a different AuthenticationManager to the
AutologinController).
Contents
UAA is the User Account and Authentication service. It is used to coordinate identity operations.
A “client” in the context of identity is an application doing something on behalf of the end user (or on behalf of itself).
It’s important to know how data flows between client applications and the UAA. The sequences of data movement satisfy different identity requirements.
The login flow: (view diagram source)
The client keeps track of the browser through a cookie to track its http(s) session. The refresh and access tokens are kept private and not shared directly with the browser.
An authenticated operation flow: (view diagram source)
This flow takes place after the authentication flow above. The browser can now make a request to the portal. The portal looks up the appropriate token from the session and uses it to make the request.
The login server component is separate from UAA so it can present an appropriate visual rendering of the login page and authentication interfaces.
The login server also has additional logic to support the autologin flow. This is to allow a client to sign in on behalf of the user using the client’s own credentials. This is needed when a user needs to be signed in after resetting his password.
The autologin flow: (view diagram source)
These apply if you are developing identity integration in your own application, outside a bosh deployment scenario.
Requirements:
maven 3.0.4 java >= 1.6
Older versions of maven will likely appear to work at first but eventually fail with an unhelpful error. Be sure mvn -v reports 3.0.4. It’s best if you only have one version installed.
Clone, build UAA server:
git clone [email protected]:cloudfoundry/uaa.git cd uaa mvn clean install
Note the version number that you just built (e.g. look in the pom or in uaa/target for the version label on the WAR file).
Clone, build login-server:
git clone [email protected]:cloudfoundry/login-server.git cd login-server mvn clean install
Run Servers (using the UAA version <X> from above):
cd login-server && mvn tomcat:run -P integration
You can add -Didentity.version=<X> if you need to match a specific UAA build.
or to just run the UAA:
cd uaa && mvn tomcat7:run)
uaa.yml drives uaa behavior. There is a default file in the WAR that you should not touch. Overrides and additions can come from an external location, the most convenient way to specify that is through an environment variable (or system property in the JVM): $CLOUDFOUNDRY_CONFIG_PATH/uaa.yml.
UAA will use an in-memory database that is torn down between runs unless you choose a spring profile or a specific database configuration as a toplevel setting in uaa.yml. An example connecting to a postgres database:
database:
driverClassName: org.postgresql.Driver
url: jdbc:postgresql://localhost:5432/uaadb
username: postgres
password: passwordUAA can use either symmetric key encryption (shared secrets) or public key encryption.
jwt:
token:
signing-key: …
verification-key: …If you want to use symmetric key encryption, signing and verification values should be the same.
Generating new asymmetric key pairs
mkdir temp_uaa_certs cd temp_uaa_certs openssl genrsa -out privkey.pem 2048 openssl rsa -pubout -in privkey.pem -out pubkey.pem
Aysmmetric key pairs can be set directly in the yaml file using block literals. Make sure the entire key is indented.
jwt:
token:
signing-key: |
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAyV3Ws3gLOvi169ZPx8v3t9UZpxcG0fqtQzC4X+Ff7dlx4w6P
...
pYPYK4M+4Gwi7O49a63G+lzX7BqUWYBXR84iZG+vWz2F3ICjiOIz
-----END RSA PRIVATE KEY-----
verification-key: |
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyV3Ws3gLOvi169ZPx8v3
...
XwIDAQAB
-----END PUBLIC KEY-----Specify autoapprove in the client section when the user should not be asked to approve a token grant expicitly. This avoids redundant and annoying requests to grant permission when there is not a reasonable need to ever deny them.
oauth:
client:
autoapprove:
- vmc
- support-signonIndividual client settings in uaa.yml go in sections under “clients” using the client name:
oauth:
clients:
portal:
override: true
scope: openid,cloud_controller.read,cloud_controller.write
authorities: openid,cloud_controller.read,cloud_controller.writeOverride defaults to false; when true, the client settings in this section can override client settings saved if you have a persistent database. It’s recommended to have this property present and set to true; declare it as false only if you need the db to take precedence.
A scope specifies a privilege users can ask this client to assert on their behalf.
An authority specifies a privilege the client can assert on its own.
uaa.yml entries can used to set up users for development. This is not suitable for staging or production but useful in testing. If you specified a persistent db above and the user account exists, it may not be updated with a new password. Group membership will be updated automatically in a future release.
scim is a toplevel attribute in uaa.yml. Login, password, and groups can be defined on the new user.
scim:
users:
- [email protected]|apassword|scim.write,scim.read,openidA scope cannot be added to a token granted by the UAA unless the user is in the corresponding group with the same name (some default groups are always available and do not need to be explicitly populated: openid, password.write, cloud_controller.read, cloud_controller.write, tokens.read, tokens.write).
Bosh deployments can be tricky to debug.
You should examine the steps of the flow you are expecting and find the point at which it misbehaves. If any one point in the flow is broken, for example an endpoint misconfigured or an identity test failing, you will see the flow break down at that point.
vms to look at are uaa, login, and the vm with your client application.
Go the uaa machine to monitor logs with:
bosh ssh uaa 0 tail -f /var/vcap/sys/log/uaa/uaa.log
You can watch headers to confirm the kind of flow you want with tcpdump, for example if you ssh into the login server:
bosh ssh login 0 sudo tcpdump 'tcp port 80 and host uaa.cf116.dev.las01.vcsops.com' -i any -A
uaac and vmc can take a --trace option which shows each online interaction.
"uaa target" your uaa if you haven't already.
"uaac token decode" functions can be used to examine tokens. Make sure attributes like scopes match what you expect. This function can take a verification key to make sure the token is signed as you expect.
"uaac signing key" can be used to get the signing key the uaa server is using. Pass -c and -s for a client to retrieve a symmetric key.
vmc and uaac each need a target. vmc points to a cloud controller and uaac to a uaa instance.
vmc target api.cf116.dev.las01.vcsops.com uaac target uaa.cf116.dev.las01.vcsops.com # dev deployment uaac target uaa.cfpartners.cloudfoundry.com # production uaac target localhost:8080/uaa # local dev
uaac context will contain clients or an end user id. These are added to your context after authenticating.
uaac token client get admin # default pass adminsecret uaac token client get vmc uaac token client get dashboard # get dashboard context
Learn about your context
uaac contexts # show your target and all contexts with it
You see scopes granted through this token. jti is a token identifier, used for operations like deleting a token.
User, group, and client changes below will be persisted if you have UAA backed by a persistent db.
If your admin client is denied access to modify scim, you will need to add scim.write to its authorities list, delete and get the token again.
uaac client update admin --authorities "clients.write clients.read uaa.admin scim.read scim.write" uaac token delete uaac token client get admin
The vmc client can be used for user registrations:
vmc add-user --email [email protected] # prompts for new password uaac users # examine all users uaac user ids # look up user ids -- only works outside production
Register a new user
uaac user add
Groups limit what scopes an entity has and what can be delegated by this client or user.
Make a user a member of the dashboard group to open the dashboard:
uaac member add dashboard.user [email protected] uaac -t user add --given_name Bill --emails [email protected] --password test [email protected]
Clients registrations can also be changed in a live system.
uaac token client get admin # admin has client scopes uaac clients # list the clients uaa knows about
Create new clients:
uaac client add media_server --scope openid,scim.read,scim.write \
--authorized_grant_types client_credentials \
--authorities oauth.login
Put in .bash_profile or another script you source:
export VCAP_BVT_TARGET=api.cf116.dev.las01.vcsops.com export [email protected] export VCAP_BVT_USER_PASSWD=an_admin_pw
Make [email protected] an admin if you want to do parallel yeti tests
uaac user update [email protected] --authorities "cloud_controller.admin"
Manually deploy an app
vmc login vmc create-org org1 vmc login vmc create-space space1 vmc login # select space1 vmc push # in an app dir
Execute the yeti suite with retries in case of timeouts
vmc target api.cf116.dev.las01.vcsops.com vmc login # [email protected] vmc add-user --email [email protected] git clone https://github.com/cloudfoundry/vcap-yeti.git cd vcap-yeti git checkout ./update bundle exec rake full rerun_failure # [email protected] test
Tokens are signed by the UAA. Signatures are checked for validity. Get the configuration of the UAA signing key if you are dealing with invalid token errors.
This will print the public key without requiring a password if using public key verification:
uaac signing key
if access is denied, use client credentials that allow access to the symmetric key:
vmc signing key -c admin -s adminsecret
UAA documentation in docs/
Login-server documentation in docs/
It is the responsibility of a Resource Server to extract information about the user and client application from the access token and make an access decision based on that information. This guide will help authors of resource Servers and maintainers of client and user account data to understand the range of information available and the kinds of decisions that can be taken. The UAA itself is a Resource Server, so the access decisions taken by the UAA are used as an example.
User accounts are either of type "user" or type "admin" (using the
SCIM type field from the core schema). These translate into granted
authorities, [uaa.user] or [uaa.admin,uaa.user] respectively, for
the purposes of access decisions within the UAA (i.e. admin users also
have the user role). Granted authorities are not directly visible to
Resource Servers, but they show up as scopes in the access tokens.
Resource Servers may choose to use this information as part of an access decision, and this may be good enough for simple use cases (e.g. users belong to a small number of relatively static roles), but in general they will need to maintain their own acess decision data since roles on UAA don't necessarily correspond to the same thing on a Resource Server.
Support for SCIM groups is currently provided only through the authorities attribute of the user object. Resource Servers that are also SCIM clients can modify this attribute themselves, but it might be better (and safer) if the data don't change much to have an admin user or client do the role assignments. In any case it is recommended that Resource Servers have sensible defaults for new users that have not yet been assigned a role.
There are 2 distinct scenarios:
Demo or test with vanilla code and no special environment. A UAA service started with no active Spring profile will initialize a single user account (marissa/koala).
A vcap environment: integration testing or in production. If the
service starts with any active Spring profile by default it will not
touch the user database. The SCIM endpoints can be used to provision
user accounts, once a client with the correct privileges has been
registered.
In either case additional user accounts and client registrations can
be bootstrapped at start up by providing some data in uaa.yml.
Example users:
scim:
users:
- paul|wombat|[email protected]|Paul|Smith|uaa.admin
- stefan|wallaby|[email protected]|Stefan|Schmidt
The format for the user is
username|password|email|first_name|last_name(|comma-separated-authorities).
Remember that authorities are represented as groups in SCIM.
In its default configuration, the UAA does not lock accounts permanently when a user repeatedly fails authentication. Instead it temporarily locks a user out for a short period (5 minutes by default) after 5 failed logins within the previous hour. The failure count is reset when a user successfully authenticates.
Client application meta data can be used by Resource Servers to make an access decision, and by the Authorization Server (the UAA itself) to decide whether to grant an access token.
Scope values are arbitrary strings, but are a contract between a
client and a Resource Server, so in cases where UAA acts as a Resource
Server there are some "standard" values (scim.read, scim.write,
passsword.write, openid, etc.) whose usage and meaning is
described below. Scopes are used by the Authorization Server to deny
a token requested for a scope not on the list, and should be used by a
Resource Server to deny access to a resource if the token has
insufficient scope.
UAA client applications have the following meta data (some are optional, but to prevent mistakes it is usually better to use a default value):
client_credentials,
password, implicit, refresh_token, authorization_code. Used
by the Authorization Server to deny a token grant if it is not on
the list. If in doubt use authorization_code and refresh_token.client_credentials grants).
Also used as the default scopes for a token where the client does
not explicitly specify scopes in the authorization request.uaa.admin or any valid scope value). The authorities are
used to define the default scopes that are assigned to a token in a
client_credentials grant, and to limit the legal values if
explicit scopes are requested in that case.none for all clients), but instead creates
a list of resource ids dynamically from the scope values when a
token is granted. The resource id is extracted from a scope using a
period separator (the last occurrence in the string) except for some
standard values (e.g. openid) that are not controlled by the UAA
or its own resources. So a scope of cloud_controller.read is
assigned a resource id of cloud_controller, for instance.Client registration can be initialized by adding client details data
to uua.yml. The UAA always starts with a registered admin client.
There are 2 typical scenarios for additional client registration
bootstraps:
Demo or test with vanilla code and no custom uaa.yml. A UAA
service started with no active Spring profile will start with some
client registrations (used in samples to make the out-of-the box
experience for new users as convenient as possible). More clients and
user accounts will be created by the integration tests.
A vcap environment: integration testing or in production. By
default no clients are created if any Spring profile is active, but
client registrations can be configured in uaa.yml and in some
well-known situations clients this will happen. In particular, the
dev_setup environment and the CF.com deployment job both start up
with additional client registrations that are needed by the basic
Cloud Foundry use cases (vmc and cloud_controller). If the vcap
Spring profile is active in the integration tests, no additional
accounts will be created.
Clients are bootstrapped from config if they are not present in the backend when the system starts up (i.e. once the system has started up once config changes will not affect the client registrations for existing clients). Certain fields (e.g. secret) can be reset if the bootstrap component is configured to do so (it is not by default).
The admin client has the following properties (in the default
uaa.yml always present on the classpath but overriddable by
specifying all the values again in a custom config file):
id: admin
secret: adminsecret
authorized-grant-types: client_credentials
scope: none
authorities: uaa.admin,clients.read,clients.write,clients.secret
The admin client can be used to bootstrap the system by adding
additional clients. In particular, user accounts cannot be
provisioned until a client with access to the scim resource is
added.
The default Spring profile initializes 3 clients in addition to the
admin client, e.g. if the server is started from the command line
after a fresh clone from github for demo purposes:
vmc:
id: vmc
authorized-grant-types: implicit
scope: cloud_controller.read,cloud_controller.write,openid,password.write
authorities: uaa.none
resource-ids: none
app:
id: app
secret: appclientsecret
authorized-grant-types: password,authorization_code,refresh_token
scope: cloud_controller.read,cloud_controller.write,openid,password.write,tokens.read,tokens.write
authorities: uaa.none
resource-ids: none
In dev_setup these client accounts (in addition to the admin
client) are initialized:
cloud_controller:
authorized-grant-types: client_credentials
scope: none
authorities: scim.read,scim.write,password.write,tokens.read,tokens.write
id: cloud_controller
secret: ...
resource-ids: none
vmc:
id: vmc
authorized-grant-types: implicit
scope: cloud_controller.read,cloud_controller.write,openid,password.write
authorities: uaa.none
resource-ids: none
redirect-uri: http://uaa.cloudfoundry.com/redirect/vmc
The cloud controller secret is generated during the setup. The same
clients are initialized in CF.com, but the secret is different.
Additional clients can be added during start up using uaa.yml, e.g.
oauth:
clients:
vmc:
authorized-grant-types: implicit
scope: cloud_controller.read,cloud_controller.write,password.write,openid
authorities: uaa.none
id: vmc
resource-ids: none
redirect-uri: http://uaa.cloudfoundry.com/redirect/vmc
When a client application asks for a new access token it can
optionally provide a set of requested scopes (space separated,
e.g. scope=openid cloud_controller.read). The UAA will use that set
if provided and that will be the scope of the token if
granted. Otherwise, if no explicit value is requested, defaults will
be supplied according to what the client and user are allowed to do.
The rules governing the defaults and what is allowed are described
next.
A token granted on behalf of a user (grant type anything except
client_credentials) takes its default scopes from the scope field
of the client registration. Whether or not the default values are
used, the requested scopes are then validated:
[openid, cloud_controller.read, cloud_controller.write]Note that the filtering of scopes by user authorities might mean that
a client gets a narrower-scoped token than it originally asked for,
e.g. if it asks for no scope=dash.admin dash.user openid, the token
might come back with only dash.user openid. Tokens are opaque to
client applications, so they have to be prepared for resource servers
to deny access to some resources based on the scope of the token when
it is presented.
A token issued on a client_credentials grant has default and allowed
scopes equal to the client authorities. Requesting a disallowed scope
will result in a 400 reponse and an error message that indicates the
allowed scopes. A client would normally take the default scopes when
acting on its own behalf - since no approval is necessary there is no
point narrowing the scope.
All OAuth2 protected resource have an id (as listed individually).
Any request whose token does not have a matching resource id (aud
field in decoded token) will be rejected. Resources that are not
OAuth2 protected resources do not have a resource id (e.g. those with
simple HTTP Basic authentication).
Resource ID = tokens. Rules:
uaa.admin, ortokens.writeuaa.admin ortokens.readuaa.admin ortokens.writeuaa.admin ortokens.readResource ID = clients. Rules:
clients.writeclients.readResource ID null (so all clients can change their password). Rule:
clients.secretuaa.admin or client can only change its own secretuaa.admin or client provides the old secretuaa.admin client must provide the old value to change its own secretResource ID = password. Rules:
password.writeuaa.adminuaa.admin or user provides the old passwordResource ID = scim. Rules:
List or search users
scim.read provides read/query access to ALL users in the UAADelete, add user account
scim.writeUpdate existing user account
scim.write lets you update ANY user's information in the UAAIn addition, a User Token obtained by a client with authorities scim.me (eg. token from authorization_code
or password grant flow) provides read/query/update access to that particular user's account.
Resource ID = scim. Rules:
/ids/Usersfilter parameter must be supplieduserName and id are returned (and can be queried on)Used for Single Sign On (OpenID Connect lite). Resource ID = openid. Rules:
openidResource ID = scim. Rules:
List or Search groups
scim.readDelete or Add groups
scim.writeUpdate group name or add/remove members
scim.write OR groups.updateIn addition, a User Token obtained by a client with authorities scim.me (eg. token from authorization_code
or password grant flow) provides the following access:
List or Search groups
reader.Update group name or add/remove members
writer in the group being updated.The UAA uses HTTP Basic authentication for these resources, so they
are no OAuth2 protected resources, but to simplify the security data
client registrations are used, so only registered clients can access
them. The caller must have a secret (so vmc and other implicit
grant clients need not apply).
Obtain access token at /oauth/token
authorization_code client must have the codeInspect access token at /check_token
uaa.resourceObtain token key (for decoding JWT tokens locally) at /token_key
uaa.resourceThe /varz endpoint is protected by HTTP Basic authentication with
credentials that are externalized via uaa.yml. They have defaults
(varz:varzclientsecret) and can also be overridden via System
properties.
The login endpoint is unsecured. Any client can ask it and it will respond with some information about the system and the login prompts required to authenticate.
Table of Contents
POST /oauth/authorizeGET /oauth/authorizePOST /check_tokenPOST /oauth/token
POST /check_idGET /userinfoGET /loginThe User Account and Authentication Service (UAA):
www.cloudfoundry.com)Rather than trigger arguments about how RESTful these APIs are we'll just refer to them as JSON APIs. Most of them are defined by the specs for the OAuth2, OpenID Connect, and SCIM standards.
Several modes of operation and other optional features can be set in configuration files. Settings for a handful of standard scenarios can be externalized and switched using environment variables or system properties.
Internal username/password authentication source
The UAA manages a user account database. These accounts can be used for password based authentication similar to existing Cloud Foundry user accounts. The UAA accounts can be configured with password policy such as length, accepted/required character types, expiration times, reset policy, etc.
Other Authentication sources
Other standard external authentication sources can also be used. The most common and therefore the expected starting point are LDAP server, or an external OpenID provider (e.g. Google). Another expected authentication source would be Horizon Application Manager either through OAuth2 (preferred), or SAML protocols. General SAML2 support is not currently planned but could be added and would provide capabilities similar to OpenID and OAuth.
This section deals with machine interactions, not with browsers, although some of them may have browsable content for authenticated users. All machine requests have accept headers indicating JSON (or a derived media type perhaps).
The /userinfo, /check_id, and /token endpoints are specified in the OpenID Connect and OAuth2 standards and should be used by web applications on a cloud foundry instance such as micro, www, support, but will not be used by flows from vmc.
The OAuth2 spec includes a scope parameter as part of the token granting request which contains a set of scope values. The spec leaves the business content of the scope up to the participants in the protocol - i.e. the scope values are completely arbitrary and can in principle be chosen by any Resource Server using the tokens. Clients of the Resource Server have to ask for a valid scope to get a token, but the Authorization Server itself attaches no meaning to the scope - it just passes the value through to the Resource Server. The UAA implementation of the Authorization Server has a couple of extra scope-related features (by virtue of being implemented in Spring Security where the features originate).
/check_token endpoint (in the aud claim), so that a Resource Server can check that its own ID is on the allowed list for the token before serving a resource.Resource IDs have some of the character of a scope, except that the clients themselves don't need to know about them - it is information exchanged between the Authorization and Resource Servers. The examples in this document use a scope parameter that indicates a resource server, e.g. a Cloud Controller instance. This is a suggested usage, but whether it is adopted by the real Cloud Controller is not crucial to the system. Similarly any Resource Server that wants to can check the allowed resource IDs if there are any, but it is not mandatory to do so.
This is a completely vanilla as per the OAuth2 spec, but we give a brief outline here for information purposes.
HTML Responses
Request: GET /oauth/authorize
Request Body: some parameters specified by the spec, appended to the query component using the application/x-www-form-urlencoded format,
response_type=codeclient_id=wwwscope=read write passwordredirect_uri is optional because it can be pre-registeredRequest Header:
Cookie: JSESSIONID=ADHGFKHDSJGFGF; Path / - the authentication cookie for the client with UAA. If there is no cookie user's browser is redirected to /login, and will eventually come back to /oauth/authorize.Response Header: location as defined in the spec includes access_token if successful:
HTTP/1.1 302 Found Location: https://www.cloudfoundry.example.com?code=F45jH
Response Codes:
302 - Found
JSON Responses
If the client asks for a JSON response (with an Accept header), and
the user has not approved the grant yet, the UAA sends a JSON object
with some useful information that can be rendered for a user to read
and explicitly approve the grant:
{
"message":"To confirm or deny access POST to the following locations with the parameters requested.",
"scopes":[
{"text":"Access your data with scope 'openid'","code":"scope.openid"},
{"text":"Access your 'cloud_controller' resources with scope 'read'","code":"scope.cloud_controller.read"},
...],
...,
"client_id":"idtestapp",
"redirect_uri":"http://nowhere.com",
"options":{
"deny":{"location":"https://uaa.cloudfoundry.com/oauth/authorize","value":"false","path":"/oauth/authorize","key":"user_oauth_approval"},
"confirm":{"location":"https://uaa.cloudfoundry.com/oauth/authorize","value":"true","path":"/oauth/authorize","key":"user_oauth_approval"}
}
}
The most useful information for constructing a user approval page is the list of requested scopes, the client id and the requested redirect URI.
See oauth2 token endpoint below for a more detailed description.
| Request | POST /oauth/token |
| Request Body | the authorization code (form encoded), e.g.: code=F45jH |
| Response Codes | 200 OK |
| Response Body | {
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"bearer",
"expires_in":3600,
}
|
An OAuth2 defined endpoint to provide various tokens and authorization codes.
For the vmc flows, we use the OAuth2 Implicit grant type (to avoid a second round trip to /token and so vmc does not need to securely store a client secret or user refresh tokens). The authentication method for the user is undefined by OAuth2 but a POST to this endpoint is acceptable, although a GET must also be supported (see OAuth2 section 3.1).
Effectively this means that the endpoint is used to authenticate and obtain an access token in the same request. Note the correspondence with the UI endpoints (this is similar to the /login endpoint with a different representation).
Note
A GET mothod is used in the relevant section of the spec that talks about the implicit grant, but a POST is explicitly allowed in the section on the /oauth/authorize endpoint (see OAuth2 section 3.1).
All requests to this endpoint MUST be over SSL.
Request: POST /oauth/authorize
Request query component: some parameters specified by the spec, appended to the query component using the "application/x-www-form-urlencoded" format,
response_type=tokenclient_id=vmcscope=read writeredirect_uri - optional because it can be pre-registered, but a dummy is still needed where vmc is concerned (it doesn't redirect) and must be pre-registered, see Client Registration Administration APIs.Request body: contains the required information in JSON as returned from the login information API, e.g. username/password for internal authentication, or for LDAP, and others as needed for other authentication types. For example:
credentials={"username":"dale","password":"secret"}
Response Header: location as defined in the spec includes access_token if successful:
HTTP/1.1 302 Found Location: oauth:redirecturi#access_token=2YotnFZFEjr1zCsicMWpAA&token_type=bearer
Response Codes:
302 - Found
This works similarly to the previous section, but does not require the credentials to be POSTed as is needed for browser flows.
/oauth/authorize endpoint with parameters in the query component as per the previous section.redirect_uri provided (and pre-registered) by the client.In addition to the normal authentication of the /oauth/authorize endpoint described above (cookie-based for browser app and special case for vmc) the UAA offers a special channel whereby a trusted client app can authenticate itself and then use the /oauth/authorize endpoint by providing minimal information about the user account (but not the password). This channel is provided so that authentication can be abstracted into a separate "Login" server. The default client id for the trusted app is login, and this client is registered in the default profile (but not in any other):
id: login, secret: loginsecret, scope: uaa.none, authorized_grant_types: client_credentials, authorities: oauth.login
To authenticate the /oauth/authorize endpoint using this channel the Login Server has to provide a standard OAuth2 bearer token header _and_ some additional parameters to identify the user: source=login is mandatory, as is username, plus optionally [email, given_name, family_name]. The UAA will lookup the user in its internal database and if it is found the request is authenticated. The UAA can be configured to automatically register authenicated users that are missing from its database, but this will only work if all the fields are provided. The response from the UAA (if the Login Server asks for JSON content) has enough information to get approval from the user and pass the response back to the UAA.
Using this trusted channel a Login Server can obtain authorization (or tokens directly in the implicit grant) from the UAA, and also have complete control over authentication of the user, and the UI for logging in and approving token grants.
An authorization code grant has two steps (as normal), but instead of a UI response the UAA sends JSON:
Request: POST /oauth/authorize
Request query component: some parameters specified by the spec, appended to the query component using the "application/x-www-form-urlencoded" format,
response_type=codeclient_id - a registered client idredirect_uri - a redirect URI registered with the clientstate - recommended (a random string that the client app can correlate with the current user session)source=login - mandatoryusername - the user whom the client is acting on behalf of (the authenticated user in the Login Server)email - the email of the user, optionalgiven_name - the given (first) name of the user, optionalfamily_name - the family (last) name of the user, optionalRequest header:
Accept: application/json Authorization: Bearer <login-client-bearer-token-obtained-from-uaa>
Request body: empty (or form encoded parameters as above)
Response header will include a cookie. This needs to be sent back in the second step (if required) so that the UAA can retrive the state from this request.
Response body if successful, and user approval is required (example):
HTTP/1.1 200 OK
{
"message":"To confirm or deny access POST to the following locations with the parames rqstd.",
"scopes":[
{"text":"Access your data with scope 'openid'","code":"scope.openid"},
{"text":"Access your 'password' resources with scope 'write'","code":"scope.password.write"},
...
],
"auth_request":{...}, // The authorization request
"client": {
"scope":[...],
"client_id":"app",
"authorized_grant_types":["authorization_code"],
"authorities":[...]
},
"redirect_uri": "http://app.cloudfoundry.com",
"options":{
"deny":{"value":"false","key":"user_oauth_approval",...},
"confirm":{"value":"true","key":"user_oauth_approval",...}
}
}
the response body contains useful information for rendering to a user for approval, e.g. each scope that was requested (prepended with "scope." to facilitate i18n lookups) including a default message text in English describing it.
Response Codes:
200 - OK 403 - FORBIDDEN (if the user has denied approval) 302 - FOUND (if the grant is already approved)
Just a normal POST with approval parameters to /oauth/authorize, including the cookie requested in Step 1 (just like a browser would do). For example:
POST /oauth/authorize Cookie: JSESSIONID=fkserygfkseyrgfv user_oauth_approval=true
Response:
302 FOUND Location: https://app.cloudfoundry.com?code=jhkgh&state=kjhdafg
An endpoint that allows a resource server such as the cloud controller to validate an access token. Interactions between the resource server and the authorization provider are not specified in OAuth2, so we are adding this endpoint. The request should be over SSL and use basic auth with the shared secret between the UAA and the resource server (which is stored as a client app registration). The POST body should be the access token and the response includes the userID, user_name and scope of the token in json format. The client (not the user) is authenticated via basic auth for this call.
OAuth2 access tokens are opaque to clients, but can be decoded by resource servers to obtain all needed information such as userID, scope(s), lifetime, user attributes. If the token is encrypted witha shared sceret between the UAA are resource server it can be decoded without contacting the UAA. However, it may be useful -- at least during development -- for the UAA to specify a short, opaque token and then provide a way for the resource server to return it to the UAA to validate and open. That is what this endpoint does. It does not return general user account information like the /userinfo endpoint, it is specifically to validate and return the information represented by access token that the user presented to the resource server.
This endpoint mirrors the OpenID Connect /check_id endpoint, so not very RESTful, but we want to make it look and feel like the others. The endpoint is not part of any spec, but it is a useful tool to have for anyone implementing an OAuth2 Resource Server.
Request: uses basic authorization with base64(resource_server:shared_secret) assuming the caller (a resource server) is actually also a registered client:
POST /check_token HTTP/1.1 Host: server.example.com Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Content-Type: application/x-www-form-encoded token=eyJ0eXAiOiJKV1QiL
Successful Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"jti":"4657c1a8-b2d0-4304-b1fe-7bdc203d944f",
"aud":["openid","cloud_controller"],
"scope":["read"],
"email":"[email protected]",
"exp":138943173,
"user_id":"41750ae1-b2d0-4304-b1fe-7bdc24256387",
"user_name":"marissa",
"client_id":"vmc"
}
Notes:
The user_name is the same as you get from the OpenID Connect /userinfo endpoint. The user_id field is the same as you would use to get the full user profile from /Users.
Many of the fields in the response are a courtesy, allowing the caller to avoid further round trip queries to pick up the same information (e.g. via the /Users endpoint).
The aud claim is the resource ids that are the audience for the token. A Resource Server should check that it is on this list or else reject the token.
The client_id data represent the client that the token was granted for, not the caller. The value can be used by the caller, for example, to verify that the client has been granted permission to access a resource.
Error Responses: see OAuth2 Error responses and this addition:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{ "error":"invalid_token" }
An OAuth2 defined endpoint which accepts authorization code or refresh tokens and provides access_tokens. The access_tokens can then be used to gain access to resources within a resource server.
POST /oauth/token| Request | POST /oauth/token |
| Request Body | the authorization code (form encoded), e.g.: code=F45jH |
| Response Codes | 200 OK |
| Response Body | {
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"bearer",
"expires_in":3600,
}
|
Additional user defined claims can be added to the token by sending them in the token request. The format of the request is as follows:
authorities={"additionalAuthorizationAttributes":{"external_group":"domain\\group1",
"external_id":"abcd1234"}}
A sample password grant request is as follows:
POST /uaa/oauth/token HTTP/1.1 Host: localhost:8080 Accept: application/json Authorization: Basic YXBwOmFwcGNsaWVudHNlY3JldA== "grant_type=password&username=marissa&password=koala&authorities=% 7B%22additionalAuthorizationAttributes%22%3A%7B%22external_group%22%3A%22domain% 5C%5Cgroup1%22%2C%20%22external_id%22%3A%22abcd1234%22%7D%7D%0A"
The access token will contain an az_attr claim like:
"az_attr":{"external_group":"domain\\group1","external_id":"abcd1234"}}
These attributes can be requested in an authorization code flow as well.
An OpenID Connect defined endpoint. It accepts an id_token, which contains claims about the authentication event. It validates the token and returns information contained in the token in JSON format. Basically makes it so that clients do not need to have full token handling implementations.
| Request | POST /check_id |
| Request Body | id_token=LKFJHDSG567TDFHG |
An OAuth2 protected resource and an OpenID Connect endpoint. Given an appropriate access_token, returns information about a user. Defined fields include various standard user profile fields. The response may include other user information such as group membership.
| Request | GET /userinfo |
| Response | {"user_id":"olds","email":"[email protected]"} |
An endpoint which returns login information, e.g prompts for authorization codes or one-time passwords. This allows vmc to determine what login information it should collect from the user.
This call will be unauthenticated.
| Request | GET /login_info or GET /login |
| Request body | empty |
| Response body | example HTTP/1.1 200 OK
Content-Type: application/json
"prompt": {
"email":["text", "validated email address"],
"password": ["password", "your UAA password" ]
"otp":["password", "security code"],
}
|
UAA supports the SCIM standard for these APIs and endpoints. These endpoints are themselves secured by OAuth2, and access decision is done based on the 'scope' and 'aud' fields of the JWT OAuth2 token.
Request: POST /Users
Request Headers: Authorization header containing an OAuth2 bearer token with:
scope = scim.write aud = scim
Request Body:
{
"schemas":["urn:scim:schemas:core:1.0"],
"userName":"bjensen",
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
}
}
The userName is unique in the UAA, but is allowed to change. Each user also has a fixed primary key which is a UUID (stored in the id field of the core schema).
Response Body:
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://example.com/v1/User/uid=123456
ETag: "0"
{
"schemas":["urn:scim:schemas:core:1.0"],
"id":"123456",
"externalId":"bjensen",
"meta":{
"version":0,
"created":"2011-08-01T21:32:44.882Z",
"lastModified":"2011-08-01T21:32:44.882Z"
},
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"userName":"bjensen"
}
Response Codes:
201 - Created successfully 400 - Bad Request (unparseable, syntactically incorrect etc) 401 - Unauthorized
Request: PUT /Users/{id}
Request Headers: Authorization header containing an OAuth2 bearer token with:
scope = scim.write aud = scim
Request Body:
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
If-Match: "2"
{
"schemas":["urn:scim:schemas:core:1.0"],
"id":"123456",
"userName":"bjensen",
"externalId":"bjensen",
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara",
"middleName":"Jane"
},
"emails":[
{
"value":"[email protected]"
},
{
"value":"[email protected]"
}
],
"meta":{
"version":2,
"created":"2011-11-30T21:11:30.000Z",
"lastModified":"2011-12-30T21:11:30.000Z"
}
}
As for create operation, returns the entire, updated record, with the Location header pointing to the resource.
Response Codes:
200 - Updated successfully 400 - Bad Request 401 - Unauthorized 404 - Not found
Note: SCIM also optionally supports partial update using PATCH.
Request: PUT /Users/{id}/password
Request Headers: Authorization header containing an OAuth2 bearer token with:
scope = password.write aud = password
OR
user_id = {id} i.e id of the user whose password is being updated
Request Body:
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
{
"schemas":["urn:scim:schemas:core:1.0"],
"password": "newpassword",
"oldPassword": "oldpassword"
}
Response Body: the updated details
Response Codes:
200 - Updated successfully 400 - Bad Request 401 - Unauthorized 404 - Not found
Note
SCIM specifies that a password change is a PATCH, but since this isn't supported by many clients, we have used PUT. SCIM offers the option to use POST with a header override - if clients want to send X-HTTP-Method-Override they can ask us to add support for that.
See SCIM - List/Query Resources
Get information about a user. This is needed by to convert names and email addresses to immutable ids, and immutable ids to display names. The implementation provides the core schema from the specification, but not all attributes are handled in the back end at present (e.g. only one email address per account).
Filters: note that, per the specification, attribute values are comma separated and the filter expressions can be combined with boolean keywords ("or" and "and").
Request: GET /Users?attributes={requestedAttributes}&filter={filter}
Request Headers: Authorization header containing an OAuth2 bearer token with:
scope = scim.read aud = scim
Response Body (for GET /Users?attributes=id&filter=emails.value eq [email protected]):
HTTP/1.1 200 OK
Content-Type: application/json
{
"totalResults":1,
"schemas":["urn:scim:schemas:core:1.0"],
"resources":[
{
"id":"123456"
}
]
}
Response Codes:
200 - Success 400 - Bad Request 401 - Unauthorized
See SCIM - Deleting Resources.
Request: DELETE /Users/{id}
Request Headers:
Authorization header containing an OAuth2 bearer token with:
scope = scim.write aud = scim
If-Match the ETag (version id) for the value to delete
Request Body: Empty
Response Body: Empty
Response Codes:
200 - Success 401 - Unauthorized 404 - Not found
Deleting accounts is handled in the back end logically using the active flag, so to see a list of deleted users you can filter on that attribute (filters by default have it set to true), e.g.
GET /Users?attributes=id,userName&filter=userName co 'bjensen' and active eq falseThere is a SCIM-like endpoint for converting usernames to names, with the same filter and attribute syntax as /Users. It must be supplied with a filter parameter. It is a special purpose endpoint for use as a user id/name translation api, and is should be disabled in production sites by setting scim.userids_enabled=false in the UAA configuration. It will be used by vmc so it has to be quite restricted in function (i.e. it's not a general purpose groups or users endpoint). Otherwise the API is the same as /Users.
GET /ids/UsersThe password strength API is not part of SCIM but is provided as a service to allow user management applications to use the same password quality checking mechanism as the UAA itself. Rather than specifying a set of rules based on the included character types (upper and lower case, digits, symbols etc), the UAA exposes this API which accepts a candidate password and returns a JSON message containing a simple numeric score (between 0 and 10) and a required score (one which is acceptable to the UAA). The score is based on a calculation using the ideas from the zxcvbn project.
The use of this API does not guarantee that a password is strong (it is currently limited to English dictionary searches, for example), but it will protect against some of
the worst choices that people make and will not unnecessarily penalise strong passwords. In addition to the password parameter itself, the client can pass a
comma-separated list of user-specific data in the userData parameter. This can be used to pass things like the username, email or other biographical
information known to the client which should result in a low score if it is used as part of the password.
Request: POST /password/score
POST /password/score HTTP/1.1 Host: uaa.example.com Content-Type: application/x-www-form-encoded
password=password1&userData=jane,janesdogsname,janescity
HTTP/1.1 200 OK Content-Type: application/json
{"score": 0, "requiredScore": 5}
In addition to SCIM users, UAA also supports/implements SCIM_groups for managing group-membership of users. These endpoints too are secured by OAuth2 bearer tokens.
Request: POST /Group
Request Headers: Authorization header containing an OAuth2 bearer token with:
scope = scim.write aud = scim
Request Body:
{
"schemas":["urn:scim:schemas:core:1.0"],
"displayName":"uaa.admin",
"members":[
{ "type":"USER","authorities":["READ"],"value":"3ebe4bda-74a2-40c4-8b70-f771d9bc8b9f" }
]
}
The displayName is unique in the UAA, but is allowed to change. Each group also has a fixed primary key which is a UUID (stored in the id field of the core schema).
Response Body:
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://example.com/v1/Group/uid=123456
ETag: "0"
{
"schemas":["urn:scim:schemas:core:1.0"],
"id":"123456",
"meta":{
"version":0,
"created":"2011-08-01T21:32:44.882Z",
"lastModified":"2011-08-01T21:32:44.882Z"
},
"displayName":"uaa.admin",
"members":[
{ "type":"USER","authorities":["READ"],"value":"3ebe4bda-74a2-40c4-8b70-f771d9bc8b9f" }
]
}
Response Codes:
201 - Created successfully 400 - Bad Request (unparseable, syntactically incorrect etc) 401 - Unauthorized
The members.value sub-attributes MUST refer to a valid SCIM resource id in the UAA, i.e the UUID of an existing SCIM user or group.
Request: PUT /Group/{id}
Request Headers:
Authorization header containing an OAuth2 bearer token with:
scope = scim.write OR groups.update aud = scim
OR
user_id = <id of a user who is an admin member of the group being updated>
(optional) If-Match the ETag (version id) for the value to update
Request Body:
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
If-Match: "2"
{
"schemas":["urn:scim:schemas:core:1.0"],
"id":"123456",
"displayName":"uaa.admin",
"meta":{
"version":2,
"created":"2011-11-30T21:11:30.000Z",
"lastModified":"2011-12-30T21:11:30.000Z"
},
"members":[
{"type":"USER","authorities":["READ"],"value":"3ebe4bda-74a2-40c4-8b70-f771d9bc8b9f"},
{"type":"USER","authorities":["READ", "WRITE"],"value":"40c44bda-8b70-f771-74a2-3ebe4bda40c4"}
]
}
As for create operation, returns the entire, updated record, with the Location header pointing to the resource.
Response Codes:
200 - Updated successfully 400 - Bad Request 401 - Unauthorized 404 - Not found
As with the create operation, members.value sub-attributes MUST refer to a valid SCIM resource id in the UAA, i.e the UUID of a an existing SCIM user or group.
Note: SCIM also optionally supports partial update using PATCH, but UAA does not currently implement it.
See SCIM - List/Query Resources
Get information about a group, including its members and what roles they hold within the group itself, i.e which members are group admins vs. which members are just members, and so on.
Filters: note that, per the specification, attribute values are comma separated and the filter expressions can be combined with boolean keywords ("or" and "and").
Request: GET /Groups?attributes={requestedAttributes}&filter={filter}
Request Headers: Authorization header containing an OAuth2 bearer token with:
scope = scim.read aud = scim
Response Body (for GET /Groups?attributes=id&filter=displayName eq uaa.admin):
HTTP/1.1 200 OK
Content-Type: application/json
{
"totalResults":1,
"schemas":["urn:scim:schemas:core:1.0"],
"resources":[
{
"id":"123456"
}
]
}
Response Codes:
200 - Success 400 - Bad Request 401 - Unauthorized
See SCIM - Deleting Resources.
Request: DELETE /Group/{id}
Request Headers:
Authorization header containing an OAuth2 bearer token with:
scope = scim.write aud = scim
If-Match the ETag (version id) for the value to delete
Request Body: Empty
Response Body: Empty
Response Codes:
200 - Success 401 - Unauthorized 404 - Not found
Deleting a group also removes the group from the 'groups' sub-attribute on users who were members of the group.
OAuth2 protected resources which deal with listing and revoking access tokens. To revoke a token with DELETE clients need to provide a jti (token identifier, not the token value) which can be obtained from the token list via the corresponding GET. This is to prevent token values from being logged in the server (DELETE does not have a body).
Request: GET /oauth/users/{username}/tokens
Request body: empty
Response body: a list of access tokens, example
HTTP/1.1 200 OK
Content-Type: text/plain
[
{
"access_token": "FYSDKJHfgdUydsFJSHDFKAJHDSF",
"jti": "fkjhsdfgksafhdjg",
"expires_in": 1234,
"client_id": "vmc"
}
]
DELETE /oauth/users/{username}/tokens/{jti}200 OKRequest: GET /oauth/clients/{client_id}/tokens
Request body: empty
Response body: a list of access tokens, example
HTTP/1.1 200 OK
Content-Type: text/plain
[
{
"access_token": "KJHDGFKDHSJFUYTGUYGHBKAJHDSF",
"jti": "fkjhsdfgksafhdjg",
"expires_in": 1234,
"client_id": "www"
}
]
Request: DELETE /oauth/clients/{client_id}/tokens/{jti}
Request body: empty
Reponse code: 200 OK
Response body: a status message (hash)
HTTP/1.1 200 OK
{ "status": "ok" }
An endpoint which returns the JWT token key, used by the UAA to sign JWT access tokens, and to be used by authorized clients to verify that a token came from the UAA.
This call is authenticated with client credentials using the HTTP Basic method.
| Request | GET /token_key |
| Request body | empty |
| Response body | example HTTP/1.1 200 OK
Content-Type: text/plain
{alg:HMACSHA256, value:FYSDKJHfgdUydsFJSHDFKAJHDSF}
|
The algorithm ("alg") tells the caller how to use the value (it is the result of algorithm method in the Signer implementation used in the token endpoint). In this case it is an HMAC (symmetric) key, but you might also see an asymmetric RSA public key with algorithm "SHA256withRSA").
| Request | GET /oauth/clients |
| Request body | client details |
| Response code | 200 OK if successful with client details in JSON response |
| Response body | example HTTP/1.1 200 OK
{foo: {
client_id : foo,
scope : [uaa.none]
resource_ids : [none],
authorities : [cloud_controller.read,cloud_controller.write,scim.read],
authorized_grant_types : [client_credentials]
},
bar: {
client_id : bar,
scope : [cloud_controller.read,cloud_controller.write,openid],
resource_ids : [none],
authorities : [uaa.none],
authorized_grant_types : [authorization_code]
}}
|
| Request | GET /oauth/clients/{client_id} |
| Request body | client details |
| Response code | 200 OK if successful with client details in JSON response |
| Response body | example: HTTP/1.1 200 OK
{
client_id : foo,
scope : [uaa.none],
resource_ids : [none],
authorities : [cloud_controller.read,cloud_controller.write,scim.read],
authorized_grant_types : [client_credentials]
}
|
| Request | POST /oauth/clients/{client_id} |
| Request body | client details |
| Response code | 201 CREATED if successful |
| Response body | the client details |
Example request:
POST /oauth/clients/foo
{
client_id : foo,
client_secret : fooclientsecret, // optional for untrusted clients
scope : [uaa.none],
resource_ids : [none],
authorities : [cloud_controller.read,cloud_controller.write,openid],
authorized_grant_types : [client_credentials],
access_token_validity: 43200
}
(Also available for grant types that support it: refresh_token_validity.)
| Request | PUT /oauth/clients/{client_id} |
| Request body | client details |
| Response code | 200 OK if successful |
| Response body | the updated details |
Example:
PUT /oauth/clients/foo
{
client_id : foo,
scope : [uaa.none],
resource_ids : [none],
authorities : [cloud_controller.read,cloud_controller.write,openid],
authorized_grant_types : [client_credentials]
}
N.B. the secret will not be changed, even if it is included in the request body (use the secret change endpoint instead).
| Request | DELETE /oauth/clients/{client_id} |
| Request body | empty |
| Response code | 200 OK |
| Response body | the old client |
| Request | PUT /oauth/clients/{client_id}/secret |
| Request body | secret change request |
| Reponse code | 200 OK if successful |
| Response body | a status message (hash) |
Example:
PUT /oauth/clients/foo/secret
{
oldSecret: fooclientsecret,
secret: newclientsceret
}
Web app clients need UI endpoints for the OAuth2 and OpenID redirects. Clients that do not ask for a JSON content type will get HTML. Note that these UIs are whitelabeled and the branded versions used in Cloud Foundry are deployed in a separate component (the Login Server).
GET /login?error={error}200 - SuccessRequest: POST /login.do
Request Body, example -- depends on configuration (e.g. do we need OTP / PIN / password etc.):
username={username}&password={password}...
Response Header, includes location if redirect, and cookie for subsequent interaction (e.g. authorization):
Location: http://myapp.cloudfoundry.com/mycoolpage Set-Cookie: JSESSIONID=ldfjhsdhafgkasd
Response Codes:
302 - Found 200 - Success
The UAA can act as a Single Sign On server for the Cloud Foundry platform (and possibly user apps as well), so if a user logs out he logs out of all the apps.
Request: GET /oauth/authorize/confirm_access
Request Body: HTML form posts back to /oauth/authorize:
Do you approve the application "foo" to access your CloudFoundry resources with scope "read_cloudfoundry"? Approve/Deny.
Response Codes:
200 - Success
The precise form of this request is not given by the spec (which just says "obtain authorization"), but the response is.
Request: POST /oauth/authorize?user_oauth_approval=true
Request Header (needed to ensure the currently authenticated client is the one that is authorizing):
Cookie: JSESSIONID=ldfjhsdhafgkasd
Response Header: location as defined in the spec (e.g. includes auth code for that grant type, and error information)
Response Codes:
302 - Found
| Request | GET /login |
| Response Code | 302 - Found |
| Response Headers | Location: http://www.google.com/etc/blah Set-Cookie: JSESSIONID=ldfjhsdhafgkasd |
Authentication is via HTTP basic using credentials that are configured
via varz.username and varz.password. The /varz endpoint pulls
data out of the JMX MBeanServer, exposing selected nuggets directly
for ease of use, and providing links to more detailed metrics.
Request: GET /varz
Response Body:
{
"type": "UAA",
"links": {
"Users": "http://localhost:8080/uaa/varz/Users",
"JMImplementation": "http://localhost:8080/uaa/varz/JMImplementation",
"spring.application": "http://localhost:8080/uaa/varz/spring.application",
"com.sun.management": "http://localhost:8080/uaa/varz/com.sun.management",
"Catalina": "http://localhost:8080/uaa/varz/Catalina",
"env": "http://localhost:8080/uaa/varz/env",
"java.lang": "http://localhost:8080/uaa/varz/java.lang",
"java.util.logging": "http://localhost:8080/uaa/varz/java.util.logging"
},
"mem": 19173496,
"memory": {
"verbose": false,
"non_heap_memory_usage": {
"max": 184549376,
"committed": 30834688,
"init": 19136512,
"used": 30577744
},
"object_pending_finalization_count": 0,
"heap_memory_usage": {
"max": 902299648,
"committed": 84475904,
"init": 63338496,
"used": 19173496
}
},
"token_store": {
"refresh_token_count": 0,
"access_token_count": 0,
"flush_interval": 1000
},
"audit_service": {
"user_authentication_count": 0,
"user_not_found_count": 0,
"principal_authentication_failure_count": 1,
"principal_not_found_count": 0,
"user_authentication_failure_count": 0
},
"spring.profiles.active": []
}
More detailed metrics can be obtained from the links in /varz. All
except the env link (the OS env vars) are just the top-level domains
in the JMX MBeanServer. In the case of Catalina there are some
known cycles in the object graph which we avoid by restricting the
result to the most interesting areas to do with request processing.
Request: GET /varz/{domain}
Response Body (for domain=Catalina):
{
"global_request_processor": {
"http-8080": {
"processing_time": 0,
"max_time": 0,
"request_count": 0,
"bytes_sent": 0,
"bytes_received": 0,
"error_count": 0,
"modeler_type": "org.apache.coyote.RequestGroupInfo"
}
}
}
Beans from the Spring application context are exposed at
/varz/spring.application.
| # find src/main/webapp/WEB-INF -name \*.xml -exec grep '\${.*}' {} /dev/null \; | sed -e 's/.*\${\(.*\)}.*/\1/g' | sed -e 's/:/: /' | sed -e 's/\./:\n /' | |
| # find src/main/webapp/WEB-INF -name \*.xml -exec grep '\#{.*}' {} /dev/null \; | |
| uaa: | |
| url: http://localhost:8080/uaa | |
| clientinfo: | |
| url: http://localhost:8080/uaa/clientinfo | |
| approvals: | |
| url: http://localhost:8080/uaa/approvals | |
| login: | |
| url: http://localhost:8080/uaa/authenticate | |
| token: | |
| url: http://localhost:8080/uaa/oauth/token | |
| login: | |
| authorize: | |
| url: http://localhost:8080/login/oauth/authorize | |
| autologin: | |
| expire_when_used: true | |
| links: | |
| home: https://www.cloudfoundry.com | |
| passwd: https://www.cloudfoundry.com/passwd | |
| signup: https://www.cloudfoundry.com/signup | |
| LOGIN_SECRET: loginsecret | |
| require_https: false | |
| dump_requests: false |
| # find uaa/src/main/webapp/WEB-INF/spring* -name \*.xml -exec grep '\${.*}' {} /dev/null \; | sed -e 's/.*\${\(.*\)}.*/\1/g' | sed -e 's/:/: /' | sed -e 's/\./:\n /' | |
| # find uaa/src/main/webapp/WEB-INF/spring* -name \*.xml -exec grep '\#{.*}' {} /dev/null \; | |
| spring_profiles: postgresql # default is empty | |
| login.addnew: false # true in default profile | |
| database: | |
| driverClassName: org.postgresql.Driver # only if spring_profiles=postgresql | |
| url: jdbc:postgresql:uaa # only if spring_profiles=postgresql | |
| username: root # only if spring_profiles=postgresql | |
| password: changeme # only if spring_profiles=postgresql | |
| password-policy.required-score: 0 | |
| jwt: | |
| token: | |
| signing-key: tokenkey | |
| verification-key: tokenkey | |
| issuer.uri: http://localhost:8080/uaa | |
| scim: | |
| delete: | |
| deactivate: false | |
| userids_enabled: false # true in default profile | |
| user: | |
| override: false | |
| users: # example only, default is empty | |
| - marissa|koala|[email protected]|Marissa|Bloggs|uaa.user | |
| userids_enabled: true | |
| users: | |
| group_membership: # example only, default is empty | |
| - acme|acme.dev,acme.qa | |
| - acme.dev|marissa | |
| oauth: | |
| authorize: | |
| ssl: | |
| client: | |
| override: true | |
| autoapprove: | |
| - vmc | |
| clients: | |
| # example only (default is empty except in default profile) | |
| login: | |
| id: login | |
| secret: loginsecret | |
| scope: openid | |
| authorized-grant-types: client_credentials,authorization_code | |
| authorities: oauth.login | |
| require_https: false | |
| dump_requests: false |
25 Feb 2013
“things are the way they are because they got that way” – Gerald Weinberg
Let's walk through this file:
https://github.com/vmware-ac/portal2/blob/master/config/backend/uaa.yml
https://github.com/vmware-ac/deployments/blob/master/staging/staging.yml#L818
avoiding the phantom sre user problem
bootstrap clients and secrets
bootstrap users and group membership
override issues
dev-template => manifest.yml => uaa.yml.erb => uaa.yml => spring *.xml => uaa
mvn clean install; cd uaa/uaa; mvn tomcat7:run
or mvnDebug tomcat7:run
running a login server and uaa locally
targets and contexts
info -- commit id, links
varz
be the client
decode tokens
be a user whoami, context
typical tomcat, spring logs
some exceptions for unnecessary database migrations are logged and can be ignored
making sense of it all
default is in memory
can specify postgres, soon mysql
unit tests:
integration tests:
uaac integration tests
yeti
uaa/gatling: see http://gatling.cloudfoundry.com/reports.html
another java app
primarily provides the oauth2 /authorize endpoint services, but sometimes proxies other endpoints to the uaa
contains any ui related to authentication and approvals
uaa has small, generic login server built In, but the login_server job provides CF artwork and UI
no db, just talks to the uaa
debug and deploy much like the uaa