Skip to main content
U.S. flag

An official website of the United States government

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

App developers can leverage’s UAA instance as a backend that brokers authentication with supported identity providers (currently EPA, FDIC, GSA, NSF, and a provider that supports other agencies). You can use’s authentication brokering if the users that you need to authenticate in your application are federal employees and contractors who can use those authentication methods.

This service handles only authentication, not authorization – it’s up to your application to manage what they can access within the application. Once you set it up, you can direct your users to the list of ways to get access; they don’t need any org or space roles, they just need to be able to log into

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:

  •, 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 basic example of how to do the OAuth dance.

Send your user to

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

  • client_id=<CLIENT_ID> (you can retrieve your client_id via cf service-key)
  • response_type=code
  • redirect_uri=<A REGISTERED CALLBACK URL> (required if you have multiple registered callback URLs)
  • state=<ANYTHING> (optional)

You only need to provide redirect_uri if you have multiple registered callback URLs for a single UAA registration (for instance, if you have both an “” URL and a production URL). The value of redirect_uri must match one of the callback URLs registered in your service key.

You can set a state parameter with any value you’d like. It will be returned to you in a later step. While optional, we strongly recommend that you use it with a high-quality random number or a hash generated with a secret key, because it protects against cross-site request forgery attacks.

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=<CLIENT_ID> (you can retrieve your client_id via cf service-key)
    • client_secret=<CLIENT_SECRET> (you can retrieve your client_secret via cf service-key)
    • redirect_uri=<A REGISTERED CALLBACK URL> (required if you have multiple registered callback URLs)
  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.

    Verify the token’s signature using’s JWK Set and the RSA256 alogrithm. This step ensures the token is authentic. The JWK Set for’s UAA is located at

    Decode the token 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.

Logging users out of UAA and your application’s UAA server provides a logout endpoint to terminate the user session. To implement this logout:

  • Provide a local logout feature specific to your application and use that to clear state in your application.
  • On success for that logout, redirect to the UAA server logout endpoint.
  • Provide a redirect link and the client_id for your application so that users come back to a familiar place when logged out.

Include the redirect link when you register your identity provider service. It’s common for this redirect link to be your application’s URL with a path of /logout.

The full URL parameters and constraints are in the latest UAA API documentation under Session Management >

Managing UAA access

If you (or a user of your app) ever need to modify or revoke the permissions of third-party applications that you’ve granted access through the UAA, visit

Using a development UAA server

During development, you may want to authenticate against a local UAA server so you can test as multiple users, skip 2-factor authentication, and view UAA logs. Running UAA in Docker can simplify this, and you can follow an example of this in the demonstrations repository.

Demonstrating the identity provider

You can go through the process of setting up a simple application, written in Node.js, to use the identity provider in the demonstrations repository.