An official website of the United States government US flag signifying that this is a United States federal government website

Leveraging authentication

Leveraging authentication uses Cloud Foundry’s User Account and Authentication (UAA) server to provide identity management capabilities for the platform.

App developers can also leverage’s UAA instance as a backend that brokers authentication with supported identity providers (currently GSA, EPA and FDIC). Essentially, you can (and probably should) use’s authentication brokering if the users that you need to authenticate in your application are employees of any of the supported agencies.

Using authentication

Register your application instances

You will first need to register all instances (such as dev, staging, and production) with’s UAA. To register your instance, use the identity provider service.

Integrate with your application

UAA handles authentication according to the OpenID Connect specification, which is “a simple identity layer on top of the OAuth 2.0 protocol.”

There are two important URLs you will need to use:

In the GovCloud environment (what's this?)

  •, which is where you will direct the user to login with their agency credentials
  •, which is where you will exchange auth codes for auth tokens

In the East/West environment (what's this?)

  •, which is where you will direct the user to login with their agency credentials
  •, which is where you will exchange auth codes for auth tokens

If you are already familiar with OAuth 2.0, you might know where to go from here. If not, read on for a minimal example of how to do the OAuth dance. Below is the basic gist of it.

Send your user to

First, generate a link (or redirect the user) to the authorize URL with these query parameters:

  • response_type=code
  • (optional) state=<ANYTHING>

You can optionally set a state parameter with any value you’d like. It will be returned to you in a later step. While optional, it’s highly recommended that you use it for security reasons.

Here is an example:

<a href="">
  Log in

Once the user clicks on this link, they will be sent to to login.

The user is returned to your site

Once the user successfully logs in with their credentials, your app will receive a GET request to the callback URL associated with the registered app. The GET request will include query parameters:


Now your site’s backend will need to exchange the access code for an access token. Here is where things get fun.

  1. First, exchange the code for an authorization token by sending a POST request to the token endpoint ( with the following form-encoded parameters:

    • grant_type='authorization_code'
    • response_type='token'
    • client_id=<YOUR APP'S REGISTERED NAME>
  2. If everything works and UAA is able to verify your request, the response from that POST request will be JSON encoded and will contain these important members:

    • access_token - a JSON Web Token
    • expires_in - time in seconds until the access_token expires
    • refresh_token - a refresh token that can be exchanged for another access_token when the current one expires
  3. The access_token is a JSON Web Token that can be decoded using a library such as node-jsonwebtoken. See for a list of libraries for various languages. Decode it to get the authenticated user’s email, which you can then use within your application to identify and/or authorize the user.

    If you get an expired token error at some point in the future, you can exchange the refresh_token from the previous step to get a new access_token, so you might want to securely save the refresh_token associated with the authenticated user.

For an example of this entire process in under 100 lines of node JS, see the example client.

Using the fake UAA server

During development, you may want to authenticate against a local server running cg-fake-uaa, a minimal “fake” version of the UAA server. Aside from making login easier and allowing for offline development, it also makes the OAuth handshake easier to debug.