wenxin-liu / cf-user-role-syncher

Maps members of Google GSuite Groups to Roles in CloudFoundry. It works complimentary to a sso provider for uaa, as the sso provider only handles authentication. Using this software the authorization part can be automated as well.

CF-user-role-syncher

CF-user-role-syncher automates the assignment of roles to users in CloudFoundry, by synching between a source state and CF.

• Why is this app necessary?
• Installation and configuration
• How to run locally?
• How the app works in detail
• Specifics for running in halfpipe (Springer Nature only)

Why is this app necessary?

In the current iteration of CloudFoundry single sign on, UAA handles only authentication, but not authorization. Effectively, this means that while you can log into CloudFoundry via SSO, you cannot perform any actions once logged in, because you are not assigned any roles and rights automatically. This app aims to automate this missing functionality. In other words, cf-user-role-syncher automates the assignment of roles for users in CloudFoundry.

Currently, the source state used by this app to sync to CloudFoundry is Google Groups.

Installation and configuration

1. Create source state in Google Groups

In Google groups, for org level roles, group name must follow the format below:

[e-mail] for org roles.
Possible org role names are: orgmanager, billingmanager, auditor

e.g. [e-mail].
Then add users who belong to CF org Engineering Enablement with user role orgmanager to this group.

For space level roles, group name must follow the format below:

[e-mail] for space roles.
Possible space role names are: spacemanager, spacedeveloper, spaceauditor

e.g. [e-mail].
Then add users who belong to CF org Engineering Enablement and space Live with user role spacedeveloper to this group.

For convenience, and just a common use case, group name can also be in the format below:

[e-mail]

e.g. [e-mail].
Then add users who belong to CF org Engineering Enablement and role spacedeveloper, for every space in the org, to this group.

2. Build the app

• Clone the repo
• cd cf-user-role-syncher
• go build -o gmapper

This app is using the module feature from Go 1.11. Therefore, Go 1.11 or up is required to build. If you are building from inside your $GOPATH, please keep these instructions in mind.

This will build the binary (filename: gmapper) in the current directory.

3. Configure the environment variables

CF-user-role-syncher needs a couple of environment variables to be set. In short it needs to know:

• The environment (e.g. endpoints from Google and CF)
• Credentials for both Google and CF

Environment variables overview:

Variable Name	Example Value	Notes
CFAPIENDPOINT	https://api.mycfdomain.org
UAAENDPOINT	https://uaa.mycfdomain.org
UAASSOPROVIDER	google	This is how you named the configured OpenID Connect provider in uaa
CFUSERNAME	[e-mail]	How to get this?
CFPASSWORD	gs62W!sgekjbee&3gshdhd2892SW	How to get this?
GOOGLECLIENTID	873e7823-ajhgsy652w.apps.googleusercontent.com	How to get this?
GOOGLECLIENTSECRET	qwhk3f9ewy823fuw	How to get this?
GOOGLEREDIRECTURI	urn:ietf:wg:oauth:2.0:oob	This is the first redirect URI provided by Google when you download your Oauth client ID and Secret from Google. Probably a fixed value until Google decides to change this.
GOOGLEAUTHURI	https://accounts.google.com/o/oauth2/auth	Fixed value. This will only change when Google decides to change its Oauth endpoints.
GOOGLETOKENURI	https://www.googleapis.com/oauth2/v3/token	Fixed value. This will only change when Google decides to change its Oauth endpoints.
GOOGLEOAUTHSCOPE	https://www.googleapis.com/auth/admin.directory.group	Fixed value. This will only change when Google decides to change its Oauth scope names.
GOOGLEACCESSTOKEN	dg26.s2iuwxguiw-wiwcvcxh	How to get this?
GOOGLEREFRESHTOKEN	hwqec/wqdc82dwqu21d12jw-21	How to get this?
GOOGLETOKENTYPE	Bearer	How to get this?

How to run locally?

There is a source file set-env-vars provided in the repository which sets all the required environment variables. This will fetch its values from:

• Your local cf config file (~/.cf/config.json).
• Self created json file with CF admin credentials (cfcredentials.json). Get one here.
• Downloaded Google Client credentials file (credentials.json). Get one here.
• Generated Google Oauth Token file (token.json) Get one here.

By default, your CF configuration will be saved in ~/.cf/. Please save credentials.json and token.json in the same directory as the set-env-vars file. This means in the root of the project.

Then run:

source /path/to/gmapper/repo/set-env-vars

With the environment variables set you can now run the cf-user-role-syncher binary.

How the app works in detail

The app performs the steps below:

• Search in your GSuite Directory for groups starting with the defined group name prefix. The prefix is meant to identify the groups that are used for CF authorization. For example, search for all groups starting with cfrole__. This allows for more groups to exist in Google Groups, not all used for managing CF authorization.
• Iterate over every found group. For every group do:
  • Is it about an org role or a space role? The information is extracted from the structure of the group name, e.g. [e-mail] or [e-mail]
  • Fetch the members from the group.
  • Even with sso, uaa requires an actual user account to be present. Therefore, cf-user-role-syncher checks if a group member already exists as user in uaa, using the email address as username. If not, the user will be created.
  • The org or space role is assigned to the user.
  • In case of the special group [e-mail] the spacedeveloper role is assigned to the user for every space in the org.

Specifics for running in halfpipe (Springer Nature only)

Halfpipe is the CI system within Springer Nature. The pipeline definition is configured in .halfpipe.io.yml. The pipeline is configured to first build the app as a Linux binary. The artifact is saved and then restored in the second pipeline task. The second pipeline task is to deploy the app to Cloudfoundry using the bindary buildpack. cf-user-role-syncher is build to run in a continuous loop. This makes sure Google Group members are continuously mapped to their respective roles in CF.

The needed environment variables are set in Vault. The Vault path is: springernature/engineering-enablement/cf-user-role-syncher