ID Broker

A Cloud Foundry service broker that creates and manages identities for applications, enabling them to generate JWT tokens for accessing external resources.

Overview

The ID Broker is an Open Service Broker API compliant service that integrates with Cloud Foundry's UAA (User Account and Authentication) service and CredHub to provide applications with dedicated identities. Applications can bind to these identities and use them to generate JWT tokens based on their CF instance client certificate.

Key Features

• Identity Management: Creates and manages UAA users for each service instance
• Secure Binding: Binds identities to specific Cloud Foundry applications
• Token Generation: Provides JWT tokens through mutual TLS authentication
• CredHub Integration: Securely stores identity credentials and binding information
• Cloud Foundry Native: Deep integration with CF's UAA, CredHub, and service broker APIs

Architecture

Components

┌─────────────────────┐
│   CF Application    │
│  (with instance     │
│   certificate)      │
└──────────┬──────────┘
           │ mTLS
           ↓
┌─────────────────────┐
│    ID Broker        │
│  ┌───────────────┐  │
│  │ Controllers   │  │
│  │ - Service     │  │
│  │ - Binding     │  │
│  │ - Token       │  │
│  └───────┬───────┘  │
│          ↓          │
│  ┌───────────────┐  │
│  │  Managers     │  │
│  │ - Identity    │  │
│  └───────┬───────┘  │
└──────────┼──────────┘
           │
    ┌──────┴──────┐
    ↓             ↓
┌────────┐   ┌────────┐
│  UAA   │   │CredHub │
└────────┘   └────────┘

Package Structure

• controllers/: HTTP endpoint handlers
  • ServiceInstanceController.go: Service instance lifecycle (create/delete/update)
  • ServiceBindingController.go: Service binding operations (bind/unbind)
  • TokenController.go: JWT token generation endpoint
  • ApiController.go: Support API for token information
• managers/: Business logic layer
  • IdentityManager.go: Identity creation, deletion, binding validation, token generation
• server/: HTTP server and security configuration
  • HttpServer.go: Route definitions and server initialization
  • security.go: Authentication and authorization logic
• cfg/: Configuration and catalog
  • config.go: Environment variable processing and initialization
  • catalog.go: Service broker catalog definition
• domain/: Data models for service broker API
• cf/: Cloud Foundry API client
• uaa/: UAA client for user management and token operations
• http/: HTTP request utilities

API Endpoints

Service Broker API (Basic Auth)

The ID Broker implements the Open Service Broker API specification:

• GET /v2/catalog - Service catalog
• PUT /v2/service_instances/{service_instance_guid} - Create service instance
• PATCH /v2/service_instances/{service_instance_guid} - Update service instance
• DELETE /v2/service_instances/{service_instance_guid} - Delete service instance
• PUT /v2/service_instances/{service_instance_guid}/service_bindings/{service_binding_guid} - Create binding
• DELETE /v2/service_instances/{service_instance_guid}/service_bindings/{service_binding_guid} - Delete binding

Token API (mTLS Auth)

Applications use their CF instance certificate to authenticate:

• GET /token/{service_instance_guid}/{service_binding_guid} - Generate JWT token

Response:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Support API (Bearer Token Auth)

For debugging and management (requires CF admin or developer permissions):

• GET /api/info/{service_instance_guid} - Get identity information

Response:

{
  "subject": "user-id",
  "issuer": "https://uaa.cf.example.com/oauth/token",
  "audience": ["openid"]
}

How It Works

1. Service Instance Creation

When a developer creates a service instance:

1. ID Broker creates a UAA user with username idb-{service_instance_guid}
2. User credentials and metadata are stored in CredHub at /idb/{service_instance_guid}
3. Service instance GUID becomes the identity identifier

2. Service Binding

When an application binds to the service:

1. ID Broker creates a binding record in CredHub at /idb/{service_instance_guid}/{binding_guid}
2. The binding associates the identity with a specific CF application GUID
3. Application receives credentials containing the token API URL:

   {
     "id_url": "https://id-broker.cf.example.com/token/{service_instance_guid}/{binding_guid}"
   }

3. Token Generation

When an application requests a token:

1. Application makes an HTTPS request to the id_url using its CF instance certificate (mTLS)
2. ID Broker extracts the app GUID from the certificate's organizational unit
3. Validates the certificate and verifies the app GUID matches the binding
4. Retrieves identity credentials from CredHub
5. Requests a token from UAA using the identity's credentials
6. Returns the JWT access token to the application

Authentication & Security

Multi-layered Security

1. Basic Authentication: Service broker API endpoints (CF Cloud Controller)
2. Bearer Token Authentication: Support API (requires CF user token with appropriate permissions)
3. Mutual TLS Authentication: Token generation endpoint (CF instance certificate)

Instance Certificate Validation

The broker validates CF instance certificates by:

• Extracting the app GUID from the certificate's organizational unit
• Verifying the app IP address matches CF routing expectations
• Ensuring the binding exists and matches the app GUID
• Validating through the CF API that the app is valid

Authorization

• Service Broker API: Basic auth with configured username/password
• Token API: mTLS with instance certificate + binding validation
• Support API: CF OAuth token with either:
  • cloud_controller.admin scope, OR
  • Developer/manager permissions on the service instance's space

Configuration

Environment Variables

Required

• USERNAME: Service broker basic auth username
• PASSWORD: Service broker basic auth password
• UAA_CLIENT_ID: OAuth2 client ID for UAA
• UAA_CLIENT_SECRET: OAuth2 client secret for UAA

Optional

• LISTEN_PORT: HTTP server port (default: 8080)
• HTTP_TIMEOUT: HTTP request timeout in seconds (default: 10)
• DEBUG: Enable debug mode (default: false)
• CREDHUB_URL: CredHub API URL (default: https://credhub.service.cf.internal:8844)
• UAA_URL: UAA URL override (auto-detected from CF API)

Cloud Foundry Environment

The broker automatically discovers configuration from:

• VCAP_APPLICATION: CF application URIs and metadata
• VCAP_PLATFORM_OPTIONS: Platform-provided CredHub URI
• CF API Info endpoint: UAA URL and OAuth endpoints

CredHub Secrets

The broker can optionally load secrets from CredHub instead of environment variables:

• PASSWORD: Broker basic auth password
• UAA_CLIENT_SECRET: UAA client secret

Quick Start

For detailed instructions on building, testing, and contributing to this project, see CONTRIBUTING.md.

Usage Example

As a CF Application Developer

# Create a service instance
cf create-service cf.identity standard my-identity

# Bind to your application
cf bind-service my-app my-identity

# Restage to receive credentials
cf restage my-app

In Your Application Code

import (
    "os"
    "encoding/json"
    "net/http"
    "crypto/tls"
)

// Parse VCAP_SERVICES
type Credentials struct {
    IdUrl string `json:"id_url"`
}

func getToken() (string, error) {
    // Get credentials from VCAP_SERVICES
    vcapServices := os.Getenv("VCAP_SERVICES")
    var services map[string][]struct {
        Credentials Credentials `json:"credentials"`
    }
    json.Unmarshal([]byte(vcapServices), &services)
    
    idUrl := services["cf.identity"][0].Credentials.IdUrl
    
    // Load CF instance certificate
    cert, _ := tls.LoadX509KeyPair(
        "/etc/cf-instance-credentials/instance.crt",
        "/etc/cf-instance-credentials/instance.key",
    )
    
    // Make request with mTLS
    client := &http.Client{
        Transport: &http.Transport{
            TLSClientConfig: &tls.Config{
                Certificates: []tls.Certificate{cert},
            },
        },
    }
    
    resp, err := client.Get(idUrl)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()
    
    var result map[string]string
    json.NewDecoder(resp.Body).Decode(&result)
    
    return result["accessToken"], nil
}

Service Catalog

The broker provides a single service offering:

• Service Name: cf.identity
• Description: Service broker that creates CF (UAA) users for which tokens can be requested to access external resources when UAA is setup as backend IDP
• Bindable: Yes
• Shareable: Yes
• Plan: standard (free)

Binding credentials include:

• id_url: URL endpoint for token generation

Plan metadata includes:

• idb_api: Base URL of the ID Broker for reference

Dependencies

Core Dependencies

• go-we: Web framework with built-in security
• go-cfclient: Cloud Foundry API client
• go-uaa: UAA client library
• credhub-client: CredHub API client
• go-cfenv: CF environment parsing

Monitoring and Health

• GET /health - Anonymous health check endpoint (returns when server is running)

Additional Resources

• Open Service Broker API Specification
• Cloud Foundry Service Broker Documentation
• UAA Documentation
• CredHub Documentation