cloud.gov identity provider

Table of Contents

You can leverage cloud.gov’s identity hub to reduce the burden of authenticating users from government agencies and partners in your app.

Plans

These instances are available in sandbox spaces.

How to create an instance

To create a service instance that can provision identity provider credentials, run the following command:

cf create-service cloud-gov-identity-provider oauth-client <SERVICE_INSTANCE_NAME>

Note: By default, identity provider service instances use the openid  scope. The user will be prompted
to grant any permissions required by scopes the first time they login to your application.

Obtaining credentials

To create an identity provider, bind a service key to the service instance:

cf create-service-key \
    <SERVICE_INSTANCE_NAME> \
    <SERVICE_KEY_NAME> \
    -c '{
      "redirect_uri": [
        "<APP_AUTH_REDIRECT_ROUTE>",
        "<APP_LOGOUT_REDIRECT_ROUTE>"
      ]
    }'

This will create a cloud.gov identity provider and make the credentials available to you via a service key.
The redirect_uri  array registers your app’s redirect uris with your service provider.

You can retrieve your credentials with the name of the instance and service key:

cf service-key <SERVICE_INSTANCE_NAME> <SERVICE_KEY_NAME>

It will return an object like this:

  {
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET
  }

Keep these credentials secure. If they’re compromised, the way to invalidate the credentials is to delete the service key (you can create another, and it will have a fresh set of credentials). Each service key that you bind to your instance creates a separate identity provider with different credentials; you can create as many service keys per instance as you like.

Support for the PKCE authorization flow

Note: The draft for the OAuth 2.1 spec requires PKCE for all clients using the authorization code flow.

If you need to create an OAuth client that supports the PKCE authorization flow, you need to specify the allowpublic: true  option when creating a service key like so:

cf create-service-key \
    <SERVICE_INSTANCE_NAME> \
    <SERVICE_KEY_NAME> \
    -c '{
      "redirect_uri": [
        "<APP_AUTH_REDIRECT_ROUTE>",
        "<APP_LOGOUT_REDIRECT_ROUTE>",
      ],
      "allowpublic": true
    }'

If you can’t find your service keys

If you’re trying to retrieve credentials for a service instance created before July 7, 2017, those old service instances had a different way of retrieving credentials. You can check this by running cf services  to get your service instance name and then running cf service service-instance-name  – if the service information includes a link to fugacious.18f.gov , it’s an old service instance. See this post for changes – your best next step is to delete the old service instance and create a new one.

More information

See leveraging authentication for details.

Rotating credentials

The identity provider service creates unique cloud.gov credentials for each service key. To rotate credentials associated with a service key, delete and recreate the service key.

The broker in GitHub

You can find the broker here: https://github.com/cloud-gov/uaa-credentials-broker.