SHIELD Documentation

Github Authentication

Github can be used as an external OAuth2 provider for controlling SHIELD authentication and authorizations. Both public Github ( and private Enterprise Github are supported.

All you as a SHIELD site operator need to do is configure the SHIELD Core with a new authentication provider backend, and register an OAuth Application via the Github web interface.

Registering a Github OAuth Application

To start, access the Settings page by expanding the account fly-out menu underneath your profile picture, in the top right-hand side of the Github web interface:

Accessing Settings : Screenshot

Then, access the Oauth Apps panel, under the Developer Settings header on the left side of the screen:

GitHub Setup

Then, click on the Register a new application button to bring up the form for registering your SHIELD to Github:

GitHub Setup

Then, just fill out the form:

The Authorization callback URL field must be set to:


Where https://$shield is the address of the SHIELD instance, and $identifier is the name you configured the authentication provider with, via the SHIELD Core configuration file.

Github will generate a new Client ID and Client Secret. Take note of these, as they are necessary for the next step.

Configuring SHIELD

To configure SHIELD to work with Github, you need to add a new authentication provider configuration stanza to the SHIELD Core configuration file:

# ... all the other shield core configuration ...

  - identifier: github  # or whatever you used when registering
    name:       Github
    backend:    github
      client_id:      YOUR-GITHUB-CLIENT-ID
      client_secret:  YOUR-GITHUB-CLIENT-SECRET

      mapping:  []    # more on this later

The auth key is a list of all configured authentication providers; if your configuration already features other providers, like token or UAA, you will just need to append the Github configuration to that.

The top-level of each auth item has the following required keys:

Configuring Github Authentication Properties

The properties key has the following sub-keys:


Each element of the properties.mapping list specifies a rule for translating Github's organizations and teams into SHIELD tenants and roles. This rule scheme allows for a great deal of flexibility in bridging the two systems, allowing you to mix multiple Github orgs into a single SHIELD tenant, split a single org into multiple tenants, etc.

The format of each rule is:

- github: Github Organization Name
  tenant: SHIELD Tenant Name
    - team: Github Team Name
      role: SHIELD Role
    # ... etc ...

The github field matches the Github organization name. If a user is found to belong to this organization, the rest of the rule is processed. Processing starts by looking through the list of rights, until a match on team to Github team name is found, at which point the specified role is assigned to the user, on the given tenant.

Here's an example:

  - identifier: github
    name:       Github
    backend:    github
      client_id:      YOUR-GITHUB-CLIENT-ID
      client_secret:  YOUR-GITHUB-CLIENT-SECRET

        - github: cloudfoundry-community
          tenant: Cloud Foundry Community
            - team: Owners
              role: admin
            - team: Engineers
              role: engineer
            - role: operator

In this configuration, SHIELD will assign someone in the Owners team of the cloudfoundry-community org to the Cloud Foundry Community SHIELD tenant, as an admin. Members of the Engineers Github team (on the same org) who are not in Owners will be assigned the engineer role instead. Everyone else in the Github org will be assigned the operator role.

These rights rules are processed until one matches; subsequent rules are skipped.

If there is more than one mapping, each of them is tried, in order; this can lead to multiple tenant assignments for a single user, which provides a lot of power to the SHIELD site operator.

Tenants that do not already exist in the database, but have been defined in the authentication configuration, will be created as needed.

Valid values for the role field are:

The SYSTEM Tenant

There is a special tenant, called the SYSTEM tenant, that exists solely to allow SHIELD site operators to assign system-level rights and roles to Github users, based on the same rules as tenant-level role assignment.

The SYSTEM tenant has its own set of assignable roles: