Chapter 15. User Account and Authentication Management

Role-based access control (RBAC) provides a mechanism for establishing who can access specific resources (be it an internal service or a user-facing app). The term “access” refers more broadly to the specific level of authorization a user might have, allowing her to perform a specific action such as to view or modify a resource.

Cloud Foundry RBAC defines two aspects: who can use the platform, and what those individuals can use it for. Cloud Foundry employs RBAC via a component known as the UAA service. The Cloud Foundry UAA is the central identity-management service for platform components, users, and apps.

The UAA has two key modes of operation:

  • Secure the Cloud Foundry platform components and API endpoints; for example, the Cloud Controller and Doppler require clients like the Cloud Foundry CLI to use UAA access tokens when invoking the component’s API

  • Provide authentication and access control data for apps running on the platform that require access to internal services such as the Cloud Controller or any other external service that requires authentication

The UAA can manage the authentication of users internally, against the UAA’s internal user-identity store. Alternatively, you can configure it to connect to external user stores through identity providers such as Lightweight Directory Access Protocol (LDAP), Security Assertion Markup Language (SAML), and OpenID Connect (OIDC). The UAA is based on the latest of security standards like OAuth2, OIDC, and the System for Cross-Domain Identity Management (SCIM).

There is a lot of online documentation on the UAA that covers how it works and how to use it. This chapter draws your attention to the high-level concepts and how best to interact with the UAA. Where appropriate, I provide links to online documentation for access to the latest status and information.

Background Information

Before working with the UAA, there is some additional background information you should be aware of, including an understanding of OAuth 2.0, the UAA documentation, and the UAA BOSH release.

OAuth 2.0

The UAA is an OAuth2 server that you can use for centralized identity management.1

OAuth 2.0 is an open authorization protocol designed to allow apps to access each other’s data. It allows you to create two types of apps:

  • One that reads users’ data from other apps, commonly referred to as a client

  • One that provides access to users’ data to other apps, commonly referred to as a resource server, but also represented as a client in the UAA

For example, an app can access specific user data via access to another app; for example, Gmail. The original app achieves this access by asking a user to log in to the original app via Gmail. The user logs in to Gmail, and then is redirected back to the original app. Now the original app can access the user’s data in Gmail, and call functions in Gmail on behalf of the user (e.g., querying contact addresses).

OAuth 2.0 relies on an authorization server to provide two factors of authentication and authorization. The user can be a person trying to authenticate and perform action via a client app that acts on the user’s behalf or a client app simply acting on its own. For this reason, a client app is always required, but a real end user is optional.

OAuth2 token generation is via a REST API call and the token used is a JSON web token (JWT).

UAA Documentation

The UAA is primarily used within Cloud Foundry for securing the Cloud Controller API, and securing the Loggregator for end-user and client-app access. However, you can use it for many other tasks that require access and authentication management; for example, securing the BOSH Director itself or for app access to a specific service.

For a more in-depth look at the UAA, I suggest you begin with the UAA overview.

UAA Release

You can also deploy the UAA as a BOSH release. Like the other components of Cloud Foundry, it is a standalone repository that is pulled into cf-deployment. The current release is available on GitHub. The source code for the UAA can also be found at the Cloud Foundry GitHub.

Breaking out components from cf-release into their own release is a great strategy. It allows for components such as the UAA to be independently deployable and fosters a pattern of reuse. The fact that the UAA is packaged into its own independent release opens up a number of possibilities. For example, BOSH previously had just a single admin user. However, now that the UAA is packaged as an independent release, BOSH uses the UAA for its authentication and authorization. You now can manage BOSH user access via UAA. This provides the capability to plug in an external user store and potentially have multiple users with different roles for different deployments. At the very least, the UAA provides a solid audit trail for the different users accessing the BOSH Director.

UAA Responsibilities

As mentioned in Preface, the UAA has two key responsibilities within Cloud Foundry:

  • Securing Cloud Foundry components and API endpoints

  • Securing service access for apps

Securing Cloud Foundry Components and API Endpoints

You use the UAA to provide access tokens for Cloud Foundry platform components and API endpoints; for example, the Cloud Controller and Loggregator. All collaborators target a Cloud Foundry environment with their individual user account. Accounts are associated with role and grant types that govern what level and type of access the user has within that environment. Each UAA role grants permission to a specific resource that an app can target on behalf of the user.

For example, for the purposes of access decisions, user accounts are either “user” or “admin” types. These user types translate into granted authorities. Using the SCIM type field from the UAA’s core schema, the granted authorities are either [uaa.user] or [uaa.admin,uaa.user], respectively. Resource servers then can choose to use this information as part of any access decision.

For a user accessing an app, the app will delegate to the UAA, and then the UAA can delegate this authentication to an external identity provider. Authorization takes place when the resource server evaluates the scopes, which we know as authorities, in the access token.

Securing Service Access for Apps

You can use the UAA to provide access tokens for any app running on the platform. You can configure any OAuth2-aware app to require authentication using the UAA.

In addition to getting an access token for Cloud Foundry apps running on the platform, the UAA can also be used to authenticate and authorize apps that want to access an internal service such as the Cloud Controller, the Loggregator, or any other external service. For example, when using a cf command, such as cf create-org, we are invoking API endpoints on the Cloud Controller. If you run the command to create a new Org with CF_TRACE=true prepended, you will see the specific API endpoints that are invoked, as shown in the following example:

$ CF_TRACE=true cf create-org new-org

REQUEST: [2016-12-07T09:48:44-08:00]
POST /v2/organizations HTTP/1.1

REQUEST: [2016-12-07T09:48:44-08:00]
GET /v2/config/feature_flags/set_roles_by_username HTTP/1.1

...

Another concrete example of securing apps is how Pivotal uses and runs the UAA as a multitenant identity service that is packaged as part of its single sign-on (SSO) Cloud Foundry service. Each tenant of that service can use the UAA for securing a group of OAuth-aware apps for access by end users.

App authentication and authorization can be against either the UAA’s internal user-identity store or an external identity provider such as LDAP, SAML, or OIDC. For an external identity provider, apps can authenticate against the UAA and then the UAA can delegate this authentication and authorization to the external identity provider.

An access token is comprised of a set of claims. User claims are specific user information that helps identify additional user attributes; access claims, like the scope claim, contain a list of authorities used to access and manipulate a specific resource. The ability to process claim information makes it possible to qualify authorization positions. Claims play a vital role, especially when it comes to app security, because all of the authorization positions (e.g., what services apps can access) are driven by claims. Claims can also be propagated from an external identity provider.

UAA Architecture and Configuration Within Cloud Foundry

The UAA setup within Cloud Foundry is fairly standard, and you should not need to deviate too much from the standard templates (assuming that you are following the standard deployment process as described by cf-deployment and by the Cloud Foundry documentation. Depending on your IaaS platform, you might need additional configuration. A key point is that you should always configure your own set of token keys and SAML certificates.

Instance Groups Governed by the UAA

BOSH-deployed instance groups that are UAA protected, such as the Cloud Controller, Doppler (part of the Loggregator), or Clock Global, will need to set specific UAA properties so that the instance group process can accept UAA requests and interact with the UAA. Typically, the properties required will include the following:

  • URL (for accessing the UAA)

  • JWT (a JSON web token that asserts some number of claims)

  • Clients (a list of the clients with associated scopes and secrets)

  • Login (the redirect to the login server)

See the cf-deployment manifest for some concrete examples of instance group UAA properties. The general structure (or set of properties) will be similar across instance groups that have their endpoints managed by the UAA; however, the UAA “clients” list will be instance group–specific.

UAA Instance Groups

The recommended approach is to deploy a cluster of UAA servers (a server being a single machine running a UAA instance). The cluster should consist of two UAA instances (or one instance per AZ) for high availability (HA) reasons. The instances should be split across different AZs.

Tip

bosh-bootloader will try to configure three AZs by default (assuming the IaaS you deploy to will support three distinct regions). cf-deployment will then deploy multiple instances of the UAA instance groups across the three AZs.

You can find an example of the UAA instance group in the cf-deployment manifest.

UAA Database

The Cloud Foundry deployment requires a UAA database (UAADB). UAA uses a MySQL database or PostgreSQL. It is recommended that you use a highly available MySQL solution such as a Galera MariaDB cluster or the highly available RDS solution from AWS. The UAA can also run against the p-mysql service, when it is deployed as a separate release by BOSH. Your MySQL solution should provide both failover and HA because replicas of the data should be made on every node within the cluster. A Galera cluster is provided as the default deployment option for the UAA.

As discussed in Chapter 16, you should make backups of the UAADB regularly to be able to recover from any cluster outage or damage to the database. This is true for any critical datastore within Cloud Foundry, and this is discussed further in “Backup and Restore”.

You can configure all of the UAA connection parameters via the deployment manifest. The UAA specification file lists all of the UAADB configurations. You can review the #Database section for a list of the configurable properties at the Cloud Foundry GitHub page. However, you should not need to deviate from most of the defaults apart from the obvious connection base parameters such as IP.

For an example of the UAADB configuration properties, you can review the Cloud Foundry deployment manifest that you created during the steps in Chapter 5.

UAA Runtime Components

Tomcat is used as the runtime container for the core Java-based UAA web app. Setup of this environment is BOSH managed via the BOSH deployment of the UAA-release. As of this writing, this is based on Tomcat 8 and the latest OpenJDK build packaged by the Java buildpack. All of the JVM settings are configurable in the deployment manifest (e.g., catalina_opts: "-Xmx768m"); however, it is important to note that the defaults have been reported as consistently good and should not require tweaking.

UAA Logging and Metrics

The UAA system logs are written to the UAA component machine in a file named uaa.log. All of the audit events that are generated for the management and authentication operations are written to that log. As with all system components, you can stream the logs on a secure channel by a syslog forwarder to a syslog endpoint collector such as ELK or Splunk. The logs then can be correlated, and you can run reports for tasks such as audit compliance.

There is a document in GitHub that lists all the standard audit events (such as UAA requests and responses) that are logged. You can view this document at the Cloud Foundry GitHub page.

UAA-Produced Metrics

The UAA-produced metrics are under revision. As of this writing, UAA metrics focus mainly on reporting authentication success and authentication failure events. You can view the current metrics at the Cloud Foundry documentation page.

The UAA also supports integration with NewRelic, and all the agent configuration parameters are exposed in the manifest. NewRelic integration activates automatically if a valid license is configured in the manifest.

Keys, Tokens, and Certificate Rotation

When a user logs on to Cloud Foundry, she is presented with a UAA token. The UAA token can be an opaque token or a JWT signed by an RSA key-pair. The signing keys can be rotated as required. At any given time, the UAA will use only one signing key, but can use multiple verification keys.

There is a separate certificate and private key when the UAA acts as a SAML service provider. For every SAML authentication request that the UAA makes, the UAA must sign those requests with its identity. Therefore, that SAML certificate and private key are also present in the UAA manifest configuration.

Tokens

Tokens must be auditable, irrefutable, and revocable. OAuth 2.0 tokens are REST-based and easy to implement for developers, and there is polyglot support in common and popular frameworks with almost 100 percent feature parity between languages. Tokens offer open standards with no vendor lock-in.

The token specification in use by the UAA is the JWT with the authentication and authorization protocol being OAuth 2.0. JWT is an open standard (RFC 7519) JSON object with a set of claims about current authentication. It is signed with an RSA private key for verification and acceptance. The JSON object becomes a string prepended by the signature algorithm. Both the JSON claims object and the token signature are base64 encoded.

The UAA uses two different tokens: access tokens and OIDC id_token-s.

  • Access tokens are purposed for resource access to APIs such as the Cloud Controller or Doppler.

  • OpenIDConnectID id_tokens are purposed for an app setting up a user session. This token captures information (identification) about the client that has already been authenticated against an external ID provider.

Grant types

A grant type is the way an access token can be requested. Cloud Foundry provides five different grant types:

client_credentials

Client app requesting a token to represent a client only; no user credentials are involved.

password

The client uses the user’s credentials, passing them on to the UAA to generate a token.

implicit

Similar to the password grant but without the requirement for a client password (secret).

authorization_code

Relies on 302 redirects from the HTTP protocol. It is the most secure grant type because the client never sees the user’s credentials.

authorization_code using token as authentication

The OAuth token itself is used for authentication.

User Import

One of the key tasks for the Platform Operator is to define the strategy for on-boarding users. You can onboard them using one of four mechanisms:

  • Internal user management in the UAA and credentials managed in the UAA

  • External via LDAP—just-in-time provisioning

  • External via SAML—just-in-time provisioning

  • External via OIDC identity providers—just-in-time provisioning

Essentially, the Platform Operator will need to pick from among the aforementioned strategies. Internally managed users is a simple way to begin but ultimately most enterprises require an enterprise-wide userstore, both for security reasons and ease of use. For this reason, you can also manage users by using one of the three listed external identity providers.

With LDAP, OIDC, and SAML, the UAA manages a “just-in-time provisioning,” provisioning users on the fly, as required. The best way to onboard users via LDAP or SAML is through the use of the UAA import tool, which you can find at https://github.com/pivotalservices/uaaldapimport. This import tool uses a set of APIs, namely the CC API and UAA API, to provision users with Org and Space access.

Additionally, you can bootstrap users via the manifest, but outside of bootstrapping, ultimately it is advisable to pick only one of the four strategies.

Roles and Scopes

The Cloud Foundry admin role and UAA scopes can be derived from the previously listed external group memberships (LDAP, SAML, etc.).

Scopes

OAuth employs the concept of scopes. Scopes are essentially permissions; they allow roles to be defined. Scopes are added as a named claim, called a scope, in the access token. Scopes label permissions in a token by using two different names:

scope

When the token represents a client acting on behalf of a user

authorities

When the token represents the client (app) itself

When a resource server receives a request containing a token, the server can make a decision based on the scope in the token. The resource must validate the token. There are several ways of doing this, which are discussed in the OAuth 2.0 specification.

Roles

A role grants a specific set of permissions to a resource that can be targeted by an app on behalf of the user. Within the context of Cloud Foundry, there are two different sets of roles used to define different permissions:

  • Cloud Foundry defines a set of roles relating to Orgs and Spaces.

  • The UAA has a set of roles based on the UAA scope that are different from Cloud Foundry roles. UAA roles (essentially scopes) include cloudcontroller.admin, scim.read, and scim.write. The scopes define the access permissions for a user, namely what services she can interact with and what she is allowed to do with that service.

The Cloud Foundry roles must clearly map to a set of UAA roles; for example, a Cloud Foundry Space Auditor has only read access, but a Cloud Foundry Space Developer can create new services.

You must set up Cloud Foundry roles via direct interaction with the Cloud Controller. For this reason, onboarding requires two separate API calls: calls to the UAA and calls to the Cloud Controller. Therefore, the aforementioned UAA-import tool makes bulk onboarding significantly easier.

You can map these requirements to a specification file. For more information on that, go to the Cloud Foundry UAA release GitHub repository.

Separation of role concerns

UAA permissions and scopes managed by the UAA should not be confused with the Cloud Foundry roles managed by the CAPI.

Cloud Controller roles and permissions

The Cloud Controller governs Orgs and Space roles and responsibilities for a user. These roles persist in the Cloud Controller database. These roles are managed by the CAPI through any client of the Cloud Controller—typically through the Cloud Foundry CLI.

UAA roles and permissions

UAA roles (OAuth scopes) are, essentially, defined roles that allow users access to, and control of, certain resources. For example, some Cloud Foundry users (e.g., a space developer) are responsible for Cloud Controller activities such as managing apps and services. These users would need the cloudcontroller.admin scope. This gives the user rights on the platform but not permission to manage users. UAA roles are stored in the UAADB.

Other Cloud Foundry users (i.e., the Platform Operator) are responsible for user management. For this ability, you need an admin user who is authorized to create other users. Such a user would need scim.write scope to manage other Cloud Foundry users.

Additionally, access to the Firehose requires a user with the doppler.firehose scope. The “cf” UAA client needs permission to grant this custom scope to platform users. The configuration of the UAA job in Cloud Foundry adds this scope by default.2

You can achieve this separation of duties by creating a new user and associating that user with the correct scope.

The UAA provides these out-of-the-box roles. However, there is no specific fine-grained permissions, such as the ability for this user to just manage services. There are plans to add finer-grained authorization and custom roles, but for most users, the out-of-the-box roles provide a sufficient level of granularity.

An important point to note is that you can bootstap a predefined default set of CF users and UAA clients in the deployment manifest.

Summary

Cloud Foundry’s UAA is the central identity-management service for both platform users and apps. The UAA is a perfect example of the benefits of designing Cloud Foundry as a composable distributed architecture because the UAA is its own independent release, and is not tightly coupled with any other component. This decomposition has allowed the UAA to be reused for other concerns such as managing BOSH authentication and authorization user access.

The overall flexibility of the UAA provides benefits for securing the platform components, apps running on the platform, and any backing services. The UAA also achieves seamless integration with other enterprise user management technologies, allowing for the adoption of a single company user management strategy for both Cloud Foundry and other technologies with your business.

1 Before reading this chapter, an understanding of OAuth2 is required. There is an excellent presentation on OAuth 2.0 available on YouTube.

2 If your Cloud Foundry instance overrides the properties.uaa.clients.cf property in a stub, you need to add doppler.firehose to the scope list in the properties.uaa.clients.cf.scope property.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.14.144.108