LATEST VERSION: 1.4 - CHANGELOG
Spring Cloud Services v1.4

Security Overview for Spring Cloud Services

Page last updated:

Glossary

The following abbreviations, example values, and terms are used in this topic as defined below.

  • CC: The Cloud Foundry Cloud Controller.

  • CC DB: The Cloud Controller database.

  • CF: Cloud Foundry.

  • CF Application: An application in Cloud Foundry; the application in cf push application.

  • Dashboard SSO: Cloud Foundry’s Dashboard Single Sign-On.

  • domain.com: The value configured by an administrator for the Cloud Foundry system domain.

  • Eureka Application Name: The identifier used by a CF Application to look up other CF Applications that are registered with a Spring Cloud Services Service Registry service instance. A CF Application that registers with a Spring Cloud Services Service Registry service instance will use the value of its spring.application.name property for this value by default.

  • FQDN: Fully Qualified Domain Name.

  • Instance Record: In Eureka, the core domain object; represents a CF Application that has registered with a Spring Cloud Services Service Registry service instance. An Instance Record is used to map a Virtual Hostname to a physical route (e.g. hostname, IP address, and port). An Instance Record can have metadata associated with it.

  • Operator: A user of Pivotal Cloud Foundry® Operations Manager.

  • SB: The Spring Cloud Services Service Broker.

  • SCS: Spring Cloud Services.

  • UAA: The Cloud Foundry User Account and Authentication Server.

A Note on TLS/SSL

All components in SCS force HTTPS for all inbound requests. Because SSL terminates at the load balancer, requests are deemed to originate over HTTPS by inspecting the X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Port headers. More on how this is implemented can be found in the Spring Boot documentation.

All outbound HTTP requests made by SCS components are also made over HTTPS. These requests nearly always contain credentials, and are made to other components within the Cloud Foundry environment. In an environment that uses self-signed certificates in the HA proxy configuration, outbound HTTPS requests to other components would fail because the self-signed certificate would not be trusted by the JVM’s default truststore (e.g. cacerts). To get around this, all components use the cloudfoundry-certificate-truster to add the CF environment’s SSL certificate to the JVM’s truststore on application startup.

The SSL certificate used by the CF environment must also include Subject Alternative Names (SANs) for domain wildcards *.login.domain.com and *.uaa.domain.com. This is needed for the correct operation of Multi-tenant UAA, which relies on subdomains of UAA.

A Note on Multi-Tenant UAA

SCS uses the multi-tenancy features of UAA to implement “the principle of least privilege”. This is required because SCS creates and deletes OAuth clients when applications bind and unbind to service instances. These clients must also have non-empty authorities. In order to create clients with arbitrary authorities, the actor must have the scopes uaa.admin and clients.write; essentially they must be the admin.

Making admin-level credentials (e.g. the UAA admin client) accessible to an application is dangerous and should be avoided. For example, if one were to break into that application and get those credentials, the credentials could be used to affect the entire CF environment. This is why SCS operates in two UAA domains (also called Identity Zones).

The platform Identity Zone (e.g. uaa.domain.com) contains the users of SCS (e.g. Space Developers) and the Dashboard SSO clients used by each Service Instance. An admin-level client is not required for creating and deleting SSO clients because the SSO client’s scope values are fixed and only the most basic uaa.resource authority is needed by the SSO client.

The other Identity Zone is specific to SCS (e.g. p-spring-cloud-services.uaa.domain.com). This Identity Zone contains no users, but it contains the clients used by bound applications to access protected resources on SCS service instances. These clients require dynamic authority values, which can only be created by an admin-level actor. This admin-level actor (the p-spring-cloud-services-worker client) also exists in the Spring Cloud Services Identity Zone, but because it exists in this Identity Zone, it cannot affect anything in the platform Identity Zone. If these credentials were leaked, the damage would be limited to SCS.

The following diagram illustrates the OAuth clients used by SCS and the Identity Zones in which they exist.

Oauth2 clients

Spring Cloud Services Overview

Before continuing, you should familiarize yourself with the following diagram, which shows the direct lines of communication between application components.

Component communication

Core Components

The Installation File

The installation file is the .pivotal file that contains the Spring Cloud Services product.

The installation file is generated from source code repositories hosted on github.com. The repositories are can only be accessed by authorized persons and cannot be accessed over a non-encrypted channel. No credentials are stored in any source repository used by Spring Cloud Services.

Concourse is used as the build pipeline to generate the installation file. The infrastructure that hosts Concourse can only be accessed from within the Pivotal network, using a username and password stored internally by Concourse. The build pipeline configuration contains credentials to the S3 bucket which hosts the installation file and intermediate artifacts, as well as the GitHub API key providing read/write access to the source code repositories. The resulting installation file built by the Concourse pipeline does not contain any credentials.

The installation file is downloaded from https://network.pivotal.io, can only be accessed by authorized persons, and cannot be accessed over a non-encrypted channel.

To install Spring Cloud Services, the installation file must be uploaded to Pivotal Cloud Foundry® Operations Manager. Ops Manager can only be accessed over HTTPS by persons knowing the username and password for Ops Manager.

Spring Cloud Service Broker

The Spring Cloud Service Broker is responsible for receiving Service Broker API requests from the Cloud Controller (CC), and hosts the primary dashboard UI for all service types.

Deployment Details

Org: system
Space: p-spring-cloud-services
CF Application Name: spring-cloud-broker

Entry Points

The Service Broker API

Service Broker API endpoints require HTTPS and Basic authentication. Valid credentials for Basic authentication are made available to the SB via environment variables, and are therefore stored in the CC database in encrypted form. The CC also makes Service Broker API requests, and the credentials used to make these API requests are stored in the CC DB in encrypted form as well.

Service Broker Dashboard

Dashboard endpoints require HTTPS and an authenticated session. Unauthenticated requests are redirected to UAA to initiate the OAuth 2 Authorization Code flow as documented here; for the flow to complete, the user must be authenticated with UAA. Once the token is obtained, the session is authenticated. The token is then used to access the CC API to check permissions on the service instance being accessed, as documented here. This flow is typical of Dashboard Single Sign-On for Service Instances.

The service instance ID used in the permission check is the first GUID that is present in the URL, and this value is also used by the rest of the SB application to identify the service instance that the user is trying to access.

GET /dashboard/instance/{serviceInstanceId}

This endpoint returns service instance details such as service name, plan ID, org, and space, as well as credentials that need to be propagated to applications bound to this service instance. Because the service instance permission check is performed, this endpoint is only accessible to Space Developers who can bind applications to this service instance. Once an application is bound to this service instance, a Space Developer can see the same credentials returned by this endpoint in the bound application’s binding credentials (e.g. via Pivotal Cloud Foundry Applications Manager.)

GET|POST /dashboard/instance/{serviceInstanceId}/env

This endpoint gets or modifies environment variables for the service instance’s backing application. Environment variables that can be viewed or modified with this endpoint must be whitelisted; this whitelisting can only be modified by the Operator or the developers of Spring Cloud Services. Each service type has its own whitelist, and the only service type with whitelisted environment variables is Config Server. The Config Server’s whitelisted environment variables specify the repository type, the URI of the repository, and the username and password used to access the repository. Any POST to this endpoint will result in a restart of the backing application, regardless of whether any environment variables were actually modified.

GET /dashboard/instance/{serviceInstanceId}/health

This endpoint returns the response of the /health endpoint on the backing application. The /health endpoint is provided by Spring Boot Actuator and may be accessed anonymously for summary information or using OAuth2 authentication for detailed information. This is used by the Config Server configuration page to indicate if there are any problems with the Config Server’s configuration.

Caching the Service Instance Permission Check

The service instance permission check is cached in session (if available). The cache is used only during GET, HEAD, and OPTIONS requests, with the exception of the /instances/{service_instance_guid}/env endpoint. Any request for this endpoint does not use the cache, because this endpoint exposes application environment variables—and, in the case of Config Server, the username and password used to access the Config Server’s backing repository.

Caching the permission check in this manner avoids the load and extra round trip to the CC for doing the permission check, while still checking permissions before performing any critical operation.

Actuator Endpoints

Actuator endpoints are enabled and require HTTPS and an authenticated session. The token is obtained from UAA via the OAuth 2 Authorization Code flow as documented here; the token is then used to make a request to the CC /v2/apps/:guid/env endpoint, which can only be accessed by Space Developers in the space that hosts the SB. The GUID used in the request is extracted from the VCAP_APPLICATION environment variable, whose value is given by the CC. The only user that can access these endpoints is the Operator.

This Actuator SSO flow is used by other components that already use Dashboard SSO, as no additional dependencies are required to enable this.

External Dependencies

p-mysql

The SB uses a p-mysql service instance to store information about SCS service instances. The most sensitive information stored here is credentials for the p-rabbitmq instances used for the Circuit Breaker service instances, which could be used to disable the Hystrix dashboard as described in app turbine-{guid} > External Dependencies > p-rabbitmq. The only way to access the data in this p-mysql service instance is through the SB’s binding credentials or directly from the filesystem, and these would only be accessible to the Operator.

p-rabbitmq

The SB uses a p-rabbitmq service instance to communicate with the spring-cloud-broker-worker application (the Worker). The messages passed propagate the provision, deprovision, bind, and unbind requests received by the SB API to the Worker, as well as getting and setting application environment variables for service instance backing applications in the “instances” space. The credentials for accessing the p-rabbitmq service instance are provided through the SB’s VCAP_SERVICES environment variable as a result of binding to the service instance. The credentials would only be visible to a Space Developer in the “p-spring-cloud-services” space, and only the Operator would have this access.

The Cloud Controller

The SB communicates to the CC via HTTPS to perform permission checks using the current user’s token as described in the Service Broker Dashboard section, and to derive URIs for UAA. The URI to the CC is set at installation time in the SB’s environment variables, under the name CF_TARGET. The environment variable could be modified so that the user’s token is sent to another party. The environment variable can only be modified by a Space Developer in the “p-spring-cloud-services” space, and only the Operator would have this access.

UAA

The SB communicates with UAA via HTTPS to enable Dashboard SSO. All requests to UAA are authenticated as per the OAuth 2 specification, using the p-spring-cloud-services client credentials. The URI to UAA is derived from the CC API /v2/info endpoint, whose threat mitigations are described in the previous section.

OAuth Clients

p-spring-cloud-services

Identity Zone: UAA
Grant Type: Authorization Code
Redirect URI: https://spring-cloud-broker.domain.com/dashboard/login
Scopes: cloud_controller.read, cloud_controller.write, cloud_controller_service_permissions.read, openid
Authorities: uaa.resource
Token expiry: default (12 hours)

This client is used for SSO with UAA. The scopes allow the SB to access the Cloud Controller API on the user’s behalf, and are auto-approved. The uaa.resource authority allows the SB to access the token verification endpoints on UAA. The client ID and client secret are made available to the SB via environment variables, which are set at installation time and are stored in encrypted form in the CC DB.

Spring Cloud Service Broker Worker

The Spring Cloud Service Broker Worker (the Worker) is responsible for managing service instance backing applications. Some of this work is done asynchronously from the requests that initiate it.

Deployment Details

Org: system
Space: p-spring-cloud-services
CF Application Name: spring-cloud-broker-worker

Entry Points

The RabbitMQ Message Listener

The Worker listens for messages posted to the p-rabbitmq service instance. The SB posts these messages as described in Spring Cloud Service Broker > External Dependencies > p-rabbitmq. Only the Operator, the SB, and the Worker can access this instance of p-rabbitmq.

Actuator Endpoints

Actuator endpoints are enabled and require HTTPS and OAuth 2 authentication.

External Dependencies

p-rabbitmq

The Worker uses a p-rabbitmq service instance to receive messages from the SB. The messages received originate from the provision, deprovision, bind, and unbind requests received by the SB API, as well as from the /dashboard/instance/{serviceInstanceId}/env endpoint. The credentials for accessing the p-rabbitmq service instance are provided through the Worker’s VCAP_SERVICES environment variable as a result of binding to the service instance. The credentials would only be visible to a Space Developer in the “p-spring-cloud-services” space, and only the Operator would have this access.

The Cloud Controller

The Worker communicates to the CC via HTTPS to carry out management tasks for service instance backing apps. All backing applications reside in the “p-spring-cloud-services” org, “instances” space. The Worker uses its own user credentials to obtain a token for accessing the CC API and acts as a Space Developer in the “instances” space.

The URI to the CC is set at installation time in the Worker’s environment variables, under the name CF_TARGET, which is set at installation time and can only be modified by the Operator.

UAA

The Worker uses the client management APIs of UAA to create and delete clients in both the platform and Spring Cloud Services Identity Zones. All requests are authenticated by including the OAuth 2 bearer token in the request, and are made over HTTPS. The credentials used in these requests are detailed in the OAuth Clients section. The URI to UAA is derived from the CC API /v2/info endpoint.

OAuth Clients

p-spring-cloud-services-worker

Identity Zone: UAA
Grant Type: Client Credentials
Redirect URI: https://spring-cloud-broker.domain.com/dashboard/login
Scopes: cloud_controller.read, cloud_controller_service_permissions.read, openid
Authorities: clients.write
Token expiry: default (12 hours)

This client is used to create and delete SSO clients for each Service Registry and Circuit Breaker Dashboard service instance, which use Dashboard SSO for their own dashboards. The grant type is Client Credentials, which allows the Worker to act on its own. The clients.write authority allows the Worker to create and delete clients, but this client is limited in the kinds of clients which it can create. The scopes that are registered allow this client to create other clients with the same scopes, but these clients cannot have any authorities. In other words, clients created via this client cannot act on their own, and can only act on behalf of a user within the scopes that are registered for this client. This limitation prevents privilege escalation.

While arbitrary clients cannot be created via this client, this client is able to delete any client in the UAA Identity Zone due to the clients.write authority.

The client ID and client secret are made available to the SB via environment variables, which are set at installation time and are stored in encrypted form in the CC DB. The credentials are only visible to the Operator.

p-spring-cloud-services-worker

Identity Zone: Spring Cloud Services
Grant Type: Client Credentials
Authorities: clients.read, clients.write, uaa.admin
Token expiry: default (12 hours)

This client is used to create and delete clients in the Spring Cloud Services Identity Zone for each Config Server and Service Registry service instance. The grant type is Client Credentials, which allows the Worker to act on its own. The uaa.admin authority allows the Worker to create and delete clients in the Spring Cloud Services Identity Zone without any limitations, unlike the corresponding client in the UAA Identity Zone. However, these privileges do not extend into the UAA Identity Zone.

The client ID and client secret are the same as the corresponding client in the UAA Identity Zone.

Users

p-spring-cloud-services

This user is a Space Developer in the “p-spring-cloud-services” org, “instances” space. The user has no other roles. The username and password are made available to the Worker via environment variables, which are set at installation time and are stored in encrypted form in the CC DB. The credentials are only visible to the Operator.

Config Server Service Instances

Config Server

The Config Server CF Application is a backing application for a Config Server service instance. This application is responsible for handling requests for configuration values from bound applications.

Deployment Details

Org: p-spring-cloud-services
Space: instances
CF Application Name: config-[guid], where [guid] is the service instance ID

Entry Points

Config Server REST endpoints

The following entry points are defined by Spring Cloud Config Server.

GET /{application}/{profile}[/{label}]

This returns configuration values for a requesting application. The request must be authenticated with an OAuth 2 Bearer token issued by the Spring Cloud Services Identity Zone. The following claims are checked:

  • aud: must equal config-server-[guid]
  • iss: must equal https://p-spring-cloud-services.uaa.domain.com/oauth/token
  • scope: must equal config-server-[guid].read

The GUID in the aud and scope values must match the SERVICE_INSTANCE_ID environment variable that is set in the Config Server application at provision time.

GET /health

This is used by the Dashboard UI for checking if the Config Server is configured properly. Requests sent to this endpoint using an OAuth 2 Bearer token receive a JSON object response containing health details for each configuration source. The following example shows a typical response from an authenticated request to a health endpoint; in this example, the Config Server is using a Git confoguration source:

{
  "status": "UP",
  "git": {
    "status": "UP",
    "default": {
      "status": "UP",
      "repository": {
        "uri": "https://github.com/spring-cloud-services-samples/cook-config"
      }
    },
    "cook": {
      "status": "UP",
      "repository": {
        "uri": "https://github.com/spring-cloud-services-samples/cook-config"
      }
    }
  },
  "diskSpace": {
    "status": "UP",
    "total": 1056858112,
    "free": 889167872,
    "threshold": 10485760
  },
  "refreshScope": {
    "status": "UP"
  }
}

The overall health status can only be UP if all of the configuration source health indicators report UP. In the example response below, the Config Server is using a composite of configuration sources, and the Vault source’s health status is DOWN. This in turn leads to the overall summary health status for the Config Server being set to DOWN:

{
  "status": "DOWN",
  "git": {
    "status": "UP",
    "git-1": {
      "status": "UP",
      "repository": {
        "uri": "https://github.com/spring-cloud-services-samples/cook-config"
      }
    },
    "cook": {
      "status": "UP",
      "repository": {
        "uri": "https://github.com/spring-cloud-services-samples/cook-config"
      }
    }
  },
  "vault": {
    "status": "DOWN",
    "vault-1": {
      "status": "DOWN",
      "server": {
        "scheme": "http",
        "port": 8200,
        "host": "myvault.mycompany.com"
      },
      "error": "Unable to contact Vault server at http://myvault.mycompany.com:8200/v1/sys/health",
      "reason": "I/O error on GET request for \"http://myvault.mycompany.com:8200/v1/sys/health\": null; nested exception is org.apache.http.client.ClientProtocolException"
    }
  },
  "diskSpace": {
    "status": "UP",
    "total": 1056858112,
    "free": 889167872,
    "threshold": 10485760
  },
  "refreshScope": {
    "status": "UP"
  }
}

The endpoint may also be accessed anonymously, in which case it will only return {"status":"UP"} or {"status":"DOWN"}.

OAuth 2 Clients for Bound Applications

To provide access to bound applications, each SB bind request creates the following OAuth 2 client:

Client ID: p-config-server-[bindingId]
Identity Zone: Spring Cloud Services
Grant Type: Client Credentials
Scopes: uaa.none
Authorities: p-config-server-[guid].read
Token expiry: 30 seconds

The client ID and client secret for this client are provided to the bound application via the binding credentials in the VCAP_SERVICES environment variable. Only a Space Developer in the space that contains the bound application would have access to this.

No Application-Level Access Control

Other than checking for the claims mentioned in the previous section, no other attributes are considered when making an access control decision. Because of this, any application bound to the service instance will be able to access any configuration served by this Config Server.

Actuator Endpoints

Actuator endpoints are enabled and require OAuth 2 authentication, with the exception of /health as described above; the health endpoint can also be accessed anonymously to receive less-detailed information.

External Dependencies

Git repository

The actual configurations are stored in a Git repository and retrieval of these configurations by the Config Server is subject to the Git repository’s security requirements. The URI and the username and password (if applicable) are set by the Space Developer that configures the service instance. The UI gets and sets these credentials through the Service Broker’s /dashboard/instances/{guid}/env endpoint, so that the credentials are made available to the Config Server via environment variables (and hence stored encrypted in the CC DB).

UAA

The Config Server accesses the /token_key endpoint on UAA to retrieve the token verification key. This key material is used to verify the JWT signature of the token in order to authenticate the request.

OAuth Clients

config-server-{guid}

Identity Zone: Spring Cloud Services
Grant Type: Client Credentials
Scopes: uaa.none
Authorities: uaa.resource
Token expiry: default (12 hours)

The uaa.resource authority allows the config-server application to access the token verification endpoints on UAA. The client is created by the p-spring-cloud-services-worker client at provision time. The client ID and client secret are made available to the config-server application via environment variables set at provision time, and are only visible to the Operator.

Service Registry Service Instances

Eureka

The Eureka CF Application is a backing application for Service Registry service instances. This application hosts a REST API for the Service Registry and a dashboard UI for viewing the status of the Service Registry.

Deployment Details

Org: p-spring-cloud-services
Space: instances
CF Application Name: eureka-[guid](-node[n]), where [guid] is the service instance ID. When running in HA mode, (-node[n]) uniquely identifies the application node.

Roles

Clients are categorized into three roles, and the authorization model is designed around these three roles.

Node

When a Service Registry is deployed in High Availability mode, the Node role represents other Eureka servers that are part of the same service instance as this server.

For an incoming request to be identified as coming from a Node, the request must contain a token with the following claims:

  • iss: must be the same issuer as this server
  • sub: must be the same client_id as this server
  • scope: must equal p-service-registry-[guid].read, p-service-registry-[guid].write, where [guid] is the service instance ID of this server

Peer

When a Service Registry is configured for peer replication with other service instances, the Peer role represents one of the Eureka servers of a configured peer service instance.

For an incoming request to be identified as coming from a Peer, the request must contain a token with the following claims:

  • iss: must be the issuer as reported by the peer’s /info endpoint
  • sub: must be the hostname portion of the configured peer’s FQDN
  • scope: must equal p-service-registry-[peer-guid].read, p-service-registry-[peer-guid].write, where [peer-guid] is the GUID contained in the peer’s hostname

Bound Application

A Bound Application is a CF Application bound to this service instance. It does not represent a CF Application bound to a Peer service instance, as a Bound Application is only authorized to communicate with the service instance to which it is bound.

For an incoming request to be identified as coming from a Bound Application, the request must contain a token with the following claims:

  • iss: must be the same issuer as this server
  • sub: must start with p-service-registry
  • scope: must equal p-service-registry-[guid].read, p-service-registry-[guid].write, where [guid] is the service instance ID of this server

Entry Points

Eureka REST endpoints

GET /info

This endpoint returns basic information about the server’s configuration as part of the handshake process before a Peer can replicate state with the service instance. Authentication is not required to access this endpoint. The endpoint returns the URIs of the service instance’s configured peers, the URI of the service instance’s token issuer, the service instance’s node count, and the service instance’s version.

POST /eureka/peerreplication/batch/

This endpoint receives batches of replicated requests from other Eureka servers. Only requests from Nodes and Peers are accepted.

GET|POST|PUT|DELETE /eureka/** (all other endpoints)

These remainder of the REST endpoints can be found in the Netflix Eureka documentation. These endpoints can only be accessed by Nodes or Bound Applications.

Record Level Access Control

In addition to checking token claims, further checks are done on POST, PUT, and DELETE requests to ensure that a Eureka Instance Record can only be modified or deleted by the CF Application that created it. In addition, Spring Cloud Services enforces restrictions on the registration of Eureka Application Names within a Eureka cluster (i.e. a service instance and its configured peers, if any).

Instance Record Ownership

The Eureka server enforces ownership of Instance Records to prevent binding credentials from being misused to affect other Instance Records, especially those originating from CF Applications in other spaces. To ensure that a Instance Record can only be modified by the CF Application that created it, the Eureka server has been modified to record the CF Application’s identity, which is conveyed by the sub claim of the Bound Application’s token. This value is saved in the Instance Record’s metadata under the key registrant_principal upon registration. Any request to modify an Instance Record must contain a token whose sub claim matches the registrant_principal. Also, the registrant_principal metadata field cannot be modified after the Instance Record is created.

Application Name Ownership

The Eureka server enforces the ownership of Eureka Application Names within a cluster. For a given Eureka cluster, possibly comprised of peers spanning multiple PCF installations, only one service instance in a PCF installation may register instances with a particular Eureka Application Name. This is enforced to ensure that CF Applications in other spaces cannot register and draw traffic away from a given application, as a form of man-in-the-middle attack. However, a service instance in a different PCF installation can still register the same Eureka Application Name. This is allowed so that CF Applications in other PCF installations can be used for failover, in case all instances with a given Eureka Application Name in a particular PCF are down.

To enforce Eureka Application Name ownership, the URI of the Eureka server that registers the Instance Record is recorded under the metadata key registrar_uri. A portion of this URI is used to identity the PCF installation that hosts the Eureka server. When a CF Application registers with the server by submitting an Instance Record, all other Instance Records with the same Eureka Application Name are inspected. If an Instance Record already exists in the same PCF installation as the server receiving the registration request, and this Instance Record’s registrar_uri does not match the server’s, the registration request is rejected.

The ownership of Eureka Application Names by a service instance parallels the ownership of routes by a space in CF. However, Eureka Application Names cannot be reserved by a service instance at this time, in contrast to the creation of a route in a space, where the route is not yet bound to a CF Application. If one service instance were to register Instance Records with a particular Eureka Application Name and then all such Instance Records became de-registered (through either planned or unplanned outages), another CF Application in a different space could register with that same Eureka Application Name by binding with a peer service instance. This would prevent the original CF Application(s) from registering again when they came back online.

Eureka Application Name Ownership Example

PCF West is a PCF installation with Service Registry service instances in different organizations. These service instances are configured for peer replication with one another. One space hosts a CF Application accounting and the other hosts a CF Application inventory. They both register with Eureka Application Names accounting and inventory as underlined, respectively.

App id ownership before

Later on, the accounting-west/production space wants to deploy accounting using a Blue/Green deployment strategy. The accounting CF Application is renamed accounting-blue, but its Eureka Application Name stays the same. Then accounting-green is pushed, bound to the Service Registry service instance, and started. On startup it successully registers with the Eureka Application Name accounting. This is allowed because there are no other service instances in this cluster, in PCF West, that have registered the Eureka Application Name accounting.

App id ownership after

A space developer with access to the inventory-west/production space wishes to deploy a CF Application accounting-red in that space and register it with the Eureka Application Name accounting. When accounting-red starts up, it tries to register but its registration requests are rejected. This is because the Eureka Application Name accounting has already been registered with another service instance in the cluster, in the same PCF installation.

PCF East comes online, and provides failover for accounting and inventory apps. This is allowed because there are no other service instances in this cluster, in PCF East, that have registered the Eureka Application Names accounting or inventory.

OAuth 2 Clients for Bound Applications

To provide access to the Eureka REST API for bound applications, each SB bind request creates the following OAuth 2 client:

Client ID: p-service-registry-[bindingId]
Identity Zone: Spring Cloud Services
Grant Type: Client Credentials
Scopes: uaa.none
Authorities: p-service-registry-[guid].read, p-service-registry-[guid].write
Token expiry: 30 seconds

The client ID and client secret for this client is provided to the bound application via the binding credentials in the VCAP_SERVICES environment variable. Only a Space Developer in the space that contains the bound application would have access to this.

Eureka Dashboard

The Eureka Dashboard requires the typical Dashboard SSO flow. The service instance ID used in the permission check is supplied by an environment variable set at provision time by the Worker. The service instance permission check is cached in the same manner as the checks done by the service broker.

Actuator Endpoints

Actuator endpoints require the same Actuator SSO flow used by the Service Broker.

External Dependencies

UAA

The Eureka Server accesses the /token_key endpoint on UAA to retrieve the token verification key. This key material is used to verify the JWT signature of the token in order to authenticate the request.

The Cloud Controller

The SB communicates to the CC via HTTPS to perform permission checks using the current user’s token, as described in the Entry Points section, and to derive URIs for UAA. The URI to the CC is set at installation time in the SB’s environment variables, under the name CF_TARGET. The environment variable could be modified so that the user’s token is sent to another party. The environment variable can only be modified by a Space Developer in the “p-spring-cloud-services” space, and only the Operator would have this access.

OAuth Clients

eureka-{guid}

Identity Zone: UAA
Grant Type: Authorization Code
Redirect URI: https://eureka-{guid}.domain.com/dashboard/login
Scopes: openid, cloud_controller.read, cloud_controller_service_permissions.read
Authorities: uaa.resource
Token expiry: default (12 hours)

This client is used for Dashboard SSO with UAA. The scopes allow the Eureka application to access the Cloud Controller API on the user’s behalf, and are auto-approved. The uaa.resource authority allows the Eureka application to access the token verification endpoints on UAA. The client is created by the p-spring-cloud-services-worker client at provision time. The client ID and client secret are made available to the Eureka application via environment variables set at provision time.

eureka-{guid}

Identity Zone: Spring Cloud Services
Grant Type: Client Credentials
Scopes: uaa.none
Authorities: p-service-registry-[guid].read, p-service-registry-[guid].write, uaa.resource
Token expiry: default (12 hours)

The uaa.resource authority allows the Eureka application to access the token verification endpoints on UAA. The other authorities allow it to access other members of the cluster. The client is created by the p-spring-cloud-services-worker client at provision time. The client ID and client secret are made available to the Eureka application via environment variables set at provision time. The credentials are the same as the corresponding client in the UAA Identity Zone.

Circuit Breaker Dashboard Service Instances

Hystrix

The Hystrix application is one of two backing applications for a Circuit Breaker Dashboard service instance. This application is derived from the Netflix Hystrix Dashboard.

Deployment Details

Org: p-spring-cloud-services
Space: instances
CF Application Name: hystrix-[guid], where [guid] is the service instance ID

Entry Points

Hystrix Dashboard

The Hystrix Dashboard requires the typical Dashboard SSO flow. The service instance ID used in the permission check is supplied by an environment variable set at provision time by the Worker. The service instance permission check is cached in the same manner as the checks done by the service broker.

Actuator Endpoints

Actuator endpoints require the same Actuator SSO flow used by the Service Broker.

External Dependencies

Turbine

The Hystrix Dashboard UI uses an EventSource in the browser to listen to Server Sent Events emitted by the Turbine application. Because the Turbine application’s origin differs from the Hystrix application, and EventSources do not support CORS, the Hystrix application must handle the EventSource request and proxy this request to the Turbine application.

The Turbine application must authenticate this request, so the Hystrix application includes the token in the proxy request. The proxy request is handled on Hystrix via the endpoint /proxy.stream?origin=[turbine url]. This endpoint on open-source Hystrix can be used as an open proxy, so to protect the token from being leaked, the Turbine URL in the origin query parameter must match the TURBINE_URL environment variable of the Hystrix application. This variable is set at provision time, always begins with https://, and can only be modified by the Operator.

UAA

The Hystrix application accesses the /token_key endpoint on UAA to retrieve the token verification key. This key material is used to verify the JWT signature of the token in order to authenticate the request.

The Cloud Controller

The Hystrix application communicates to the CC via HTTPS to perform permission checks using the current user’s token, as described in the Entry Points section, and to derive URIs for UAA. The URI to the CC is set by the Worker at provision time in the application’s environment variables, under the name CF_TARGET. The environment variable can only be modified by the Operator.

OAuth Clients

hystrix-{guid}

Identity Zone: UAA
Grant Type: Authorization Code
Scopes: openid, cloud_controller.read, cloud_controller_service_permissions.read
Authorities: uaa.resource
Token expiry: default (12 hours)

This client is used for SSO with UAA. The scopes allow the Hystrix application to access the Cloud Controller API on the user’s behalf, and are auto-approved. The uaa.resource authority allows the Hystrix application to access the token verification endpoints on UAA. The client is created by the p-spring-cloud-services-worker client at provision time. The client ID and client secret are made available to the Hystrix application via environment variables set at provision time.

Turbine

The Turbine application is the other backing application for a Circuit Breaker Dashboard service instance. This application is derived from Netflix Turbine, which aggregates Hystrix AMQP messages and emits them as a Server Sent Event stream.

Deployment Details

Org: p-spring-cloud-services
Space: instances
CF Application Name: turbine-[guid], where [guid] is the service instance ID

Entry Points

GET /turbine.stream

This emits the Server Sent Event stream and is the only HTTP-based entry point. To authenticate the request, the Turbine application uses the Authorization header of the incoming request (containing the OAuth 2 Bearer token) to make a request to the CC API to check permissions on the service instance being accessed, as documented here. The service instance ID used in the permission check is supplied by an environment variable set at provision time by the Worker. This check is done once per SSE request, and because there is no session involved, it is not cached. However, SSE requests are kept alive until the browser window is closed, so the permission check will happen infrequently.

Hystrix AMQP messages

The Turbine application listens for AMQP messages posted by applications bound to the Circuit Breaker Dashboard service instance. Applications bound to the Circuit Breaker Dashboard receive credentials to the p-rabbitmq service instance in order to post these messages. All bound applications receive the same credentials.

External Dependencies

p-rabbitmq

As described earlier, bound applications use an instance of p-rabbitmq to post circuit breaker metrics. The Turbine application listens to these messages, aggregates the metrics, and emits a Server Sent Event stream. The credentials for the p-rabbitmq service instance are provided to the Turbine application though service instance binding. These same credentials are provided to applications bound to the Circuit Breaker Dashboard service instance, and would be visible to any user that is able to bind to the service instance. These credentials can be used for admin access to the RabbitMQ.

Since this RabbitMQ is only used for collecting and disseminating @HystrixCommand metrics from bound applications, one risk here is breaking the ability for metrics to be gathered and reported in the Hystrix dashboard. Doing this would not affect the operation of any application bound to the service instance.

The Cloud Controller

The Turbine application communicates to the CC via HTTPS to perform permission checks using the current user’s token, as described in the section on the Server Sent Event stream. The URI to the CC is set by the Worker at provision time in the application’s environment variables, under the name CF_TARGET. The environment variable can only be modified by the Operator.

Create a pull request or raise an issue on the source for this page in GitHub