Leveraging cloud.gov authentication
cloud.gov uses Cloud Foundry’s User Account and Authentication (UAA) server to provide identity management capabilities for the cloud.gov platform.
App developers can leverage cloud.gov’s UAA instance as a backend that brokers authentication with supported identity providers (currently EPA, FDIC, GSA, NSF, and a cloud.gov provider that supports other agencies). You can use cloud.gov’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 cloud.gov access; they don’t need any org or space roles, they just need to be able to log into cloud.gov.
Using cloud.gov authentication
Register your application instances
You will first need to register all instances (such as dev, staging, and production) with cloud.gov’s UAA. To register your instance, use the cloud.gov 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 cloud.gov URLs you will need to use:
https://login.fr.cloud.gov/oauth/authorize, which is where you will direct the user to login with their agency credentials
https://uaa.fr.cloud.gov/oauth/token, 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 login.fr.cloud.gov
First, generate a link (or redirect the user) to the authorize URL with these query parameters:
client_id=<YOUR APP'S REGISTERED NAME>
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="https://login.fr.cloud.gov/oauth/authorize?client_id=NAME&response_type=code&state=9ab894ad91d99eb9ee4b30ea7f02b9d8e43eb15db58ff93e4894f3b49817d7ab"> Log in </a>
Once the user clicks on this link, they will be sent to cloud.gov to login.
The user is returned to your site
Once the user successfully logs in with their credentials, your app will
GET request to the callback URL associated with the registered
GET request will include query parameters:
code=<A UNIQUE ACCESS CODE>
state=<VALUE FROM STATE PARAM IN AUTHORIZE LINK>
Now your site’s backend will need to exchange the access code for an access token. Here is where things get fun.
First, exchange the
codefor an authorization token by sending a
POSTrequest to the token endpoint (
https://uaa.fr.cloud.gov/oauth/token) with the following form-encoded parameters:
code=<CODE FROM QUERY PARAM IN CALLBACK REQUEST>
client_id=<YOUR APP'S REGISTERED NAME>
client_secret=<THE SECRET KEY YOU RECEIVED WHEN REGISTERING YOUR APP>
If everything works and UAA is able to verify your request, the response from that
POSTrequest will be JSON encoded and will contain these important members:
access_token- a JSON Web Token
expires_in- time in seconds until the
refresh_token- a refresh token that can be exchanged for another
access_tokenwhen the current one expires
access_tokenis a JSON Web Token that can be decoded using a library such as node-jsonwebtoken. See https://jwt.io/ for a list of libraries for various languages. Decode it to get the authenticated user’s
After decoding the token verify the signature to ensure the token is authentic. The JWK Set for cloud.gov’s UAA is located at
If you get an expired token error at some point in the future, you can exchange the
refresh_tokenfrom the previous step to get a new
access_token, so you might want to securely save the
refresh_tokenassociated with the authenticated user.
Logging users out of UAA and your application
cloud.gov’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
redirectlink and the
client_idfor your application so that users come back to a familiar place when logged out.
redirect link when you register your cloud.gov identity
service. It’s common for this redirect link to be your application’s URL with a
The full URL parameters and constraints are in the latest UAA API documentation under Session Management > Logout.do.
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 cloud.gov UAA, visit https://login.fr.cloud.gov/profile.
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 cloud.gov demonstrations repository.
Demonstrating the cloud.gov identity provider
You can go through the process of setting up a simple application, written in Node.js, to use the cloud.gov identity provider in the cloud.gov demonstrations repository.