Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Cloud Foundry Login Server

Cloud Foundry Login Server

Build Status Coverage Status

Handles authentication on and delegates all other identity management tasks to the UAA. Also provides OAuth2 endpoints issuing tokens to client apps for (the tokens come from the UAA and no data are stored locally).

Running and Testing the Login Server

The Login Server is a standard JEE servlet application, and you can build a war file and deploy it to any container you like (mvn package and look in the target directory). For convenience there is also a Maven profile that will run the Login Server, the UAA and some sample apps all in the same container from the command line (assuming you have the UAA and Login Server cloned in separate directories with a common parent):

$ (cd uaa; mvn clean install)
$ cd login-server
$ mvn clean install
$ mvn tomcat7:run -P integration

The unit tests will have been run as part of mvn install, or can be run on their own with mvn test.

You can run the Login Server integration tests using the command line as well. These integration tests will be skipped automatically if a Login Server and UAA have not been started locally. These tests require PhantomJS to be installed.

$ mvn verify

There are two documents that can help you configure the login server in your environment.

Login Server Configuration in deployment manifest

OpenAM Configuration

The Login Application

The UAA can authenticate user accounts, but only if it manages them itself, and it only provides a basic UI. The Login app can be branded and customized for non-native authentication and for more complicated UI flows, like user registration and password reset.

The login application is actually itself an OAuth2 endpoint provider, but delegates those features to the UAA server. Configuration for the login application therefore consists of locating the UAA through its OAuth2 endpoint URLs, and registering the login application itself as a client of the UAA. There is a login.yml for the UAA locations, e.g. for a local vcap instance:


and there is an environment variable (or Java System property), LOGIN_SECRET for the client secret that the app uses when it authenticates itself with the UAA. The Login app is registered by default in the UAA only if there are no active Spring profiles (so not at all in vcap). In the UAA you can find the registration in the oauth-clients.xml config file. Here's a summary:

id: login
secret: loginsecret
authorized-grant-types: client_credentials
authorities: ROLE_LOGIN
resource-ids: oauth

Use Cases

  1. Authenticate

    GET /login

    The Login Server presents a form login interface for the backend UAA, or with other services (such as SAML).

  2. Approve OAuth2 token grant

    GET /oauth/authorize?client_id=app&response_type=code...

    Standard OAuth2 Authorization Endpoint. Client credentials and all other features are handled by the UAA in the back end, and the login server is used to render the UI (see access_confirmation.html).

  3. Obtain access token

    POST /oauth/token

    Standard OAuth2 Authorization Endpoint passed through to the UAA.

Contributing to the Login Server

Here are some ways for you to get involved in the community:

  • Get involved with the Cloud Foundry community on the mailing lists. Please help out on the mailing list by responding to questions and joining the debate.
  • Create github tickets for bugs and new features and comment and vote on the ones that you are interested in.
  • Github is for social coding: if you want to write code, we encourage contributions through pull requests from forks of this repository. If you want to contribute code this way, please reference an existing issue if there is one as well covering the specific issue you are addressing. Always submit pull requests to the "develop" branch.
  • Watch for upcoming articles on Cloud Foundry by subscribing to the blog

The Cloud Foundry SAML Login Server

The saml_login server supports two additional features on top of what you get from the regular login-server. It adds authentication using an external SAML source. We have tested our authentication with OpenAM and the vCenter SSO appliance.

Configuring cf-release for a saml_login deployment

The saml_login deploys the same way as the login-server, with additional configuration parameters. Enabling saml is done using the spring_profiles configuration parameter. SAML can be used together, as two different profiles active at the same time.

  • Open your infrastructure manifest - for example cf-release/templates/cf-infrastructure-warden.yml

    Add your Tomcat JVM options as well as the intended protocol to use (http/https)

          catalina_opts: -Xmx384m -XX:MaxPermSize=128m
          protocol: http

    Scroll down to your login job and change the template to saml_login, it will be found under

        - name: login_z1
          template: saml_login
  • Open your cf-jobs.yml manifest and change the template for the login job

        - name: login_z1
          release: (( ))
          template: saml_login
  • Open your cf-properties.yml manifest to configure saml_login properties

    Please note the spring_profiles setting

    • spring_profiles: saml (uses only saml with an external SAML provider)
        #standard login server configuration
        catalina_opts: (( merge ))
        uaa_certificate: ~
        protocol: https
          home: (( "https://console." domain ))
          passwd: (( "https://console." domain "/password_resets/new" ))
          signup: (( "https://console." domain "/register" ))
        #if you wish to use saml
        spring_profiles: saml
        #saml authentication information, only required if 'saml' is part of spring_profiles
        entityid: cloudfoundry-saml-login-server
        idpEntityAlias: vsphere-local
        idpMetadataURL: "https://win2012-sso2:7444/websso/SAML2/Metadata/vsphere.local"
        serviceProviderKeyPassword: password
        serviceProviderKey: |
          -----BEGIN RSA PRIVATE KEY-----
          Proc-Type: 4,ENCRYPTED
          DEK-Info: DES-EDE3-CBC,231BD428AF94D4C8
          -----END RSA PRIVATE KEY-----
        serviceProviderKeyPassword: password
        serviceProviderCertificate: |
          -----BEGIN CERTIFICATE-----
          -----END CERTIFICATE-----
        nameidFormat: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
Something went wrong with that request. Please try again.