GitHub Integration and Account Management

Cider-CI can integrate with GitHub in various ways. This articles discusses how to configure authentication via GitHub OAuth and how to publish job results automatically to GitHub. We will also have a look at existing and new account properties and how they relate to session handling.

updated: 2016-06-03
created: 2016-02-27
level: intermediate
keywords: account management, administration, GitHub, sessions, security, sign-in

Publishing Job Outcomes to GitHub
- GitHub Status Checks
- Configuring Status Pushes
Authenticating Users via GitHub

Publishing Job Outcomes to GitHub

GitHub Status Checks

Cider-CI can publish the outcome of a job to GitHub since version 3.3. See also status checks on GitHub.

Status checks on GitHub are shown in conjunction with pull requests. This will save integrators a lot of time when reviewing pull requests.

Status checks are also shown on the branches page in GitHub. There is unfortunately now convenient way to find out about the job outcome for a particular commit on GitHub. This information is visible in Cider-CI, see the My Workspace article.

Status checks in GitHub can also be uses to protect branches.

Configuring Status Pushes

A GitHub access token is required to push job outcomes from Cider-CI as status checks to GitHub. The token issuer must have write permission to the corresponding repository and the token must have the scope repo:status.

We can add this token to the repository via the Cider-CI UI: Administration → Repositories → select repository → Edit → GitHub Authentication Token.

Authenticating Users via GitHub

There are two ways to sign in to your Cider-CI instance: with a combination of login (e-mail address respectively) and password or via GitHub OAuth2.

Benefits

Integrating authentication with GitHub has several benefits.

It frees the administrators from managing user accounts and passwords.
The known, and confirmed e-mail addresses from GitHub are added to the corresponding account in your Cider-CI instance. The "My work" button on the workspace page requires to mach commits with e-mail addresses to function, read more about this in the My Workspace article. Hence, this feature works without requiring the users to maintain their addresses.
There are three strategies to associate users:
1. GitHub Organization Membership,
2. Team Membership, and
3. matching e-mail addresses.
Every strategy can be used multiple times and combined with two list of attributes for creating or updating the corresponding user account. This can be leveraged in many ways, e.g. to manage administrators automatically.

User-Account Management

E-Mail Address Management

When a user sings in a via GitHub for the first time a new account will be created within your Cider-CI instance. Already know e-mail addresses in your Cider-CI instance will be dissociated from existing user-account and associated with the (new) account.

Session Handling

Before Cider-CI 3.13 browser sessions did not expire. Sessions expire now with a default of 7 days. This is a configuration property of your Cider-CI server. Further every user account does have its own max_session_lifetime property. In case that these two configuration properties do not have the same value the shorter one will take precedence.

Note that the session of a user is bound to the password of the user. This is a security feature of Cider-CI. It is possible to immediately invalidated all issued sessions by reseting the password. This works of course even if the user is not allowed to sing in via password authentication.

Extended User-Account Fields

Since user accounts are not merged but newly created Cider-CI 3.13 brings a set of new fields for account management:

`account_enabled`	boolean	not null default true
`password_sign_in_allowed`	boolean	not null default true
`max_session_lifetime`	character varying	default '7 days'::character varying

These properties can be adjusted by Cider-CI administrators via the User-Interface. The provider configuration below can also be configured tho modify these properties for creation of an account and during each GitHub sign in.

Configuration

The first step in configuration is to register your application. The requested "Authorization callback URL" parameter must read like http://YOUR_CIDER-CI_SERVER/cider-ci/ui/public/auth_provider/github/sign_in.

The Provider Configuration

The provided Client ID and Client Secret are then used to configure your Cider-CI instance. To that create a configuration section in your server configuration, see Setting up an Inventory in the Setup and Deployment documentation. The section looks like the following:

authentication_providers:
  github:
    name: GitHub
    client_id: XXXXXXXXXXXXXXXXXXXX
    client_secret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    oauth_base_url: https://github.com/login/oauth
    api_endpoint: https://api.github.com
    sign_in_strategies: []

The example above is valid but it won't do anything because there are not strategies specified. We will look at each of the three strategies in a dedicated example.

We first note that it it is possible to use any of the three strategies as often as you like. However, if a user signs in successfully the attributes of the first matching strategy are applied.

The `email-address` Strategy

- type: email-addresses
  email_addresses:
    - adam.admin@example.com
  create_attributes:
    is_admin: true
    account_enabled: true
    password_sign_in_allowed: true
    max_session_lifetime: 7 days

The `team-membership` Strategy

The strategy requires an additional GitHub access token, due to the permission requirements for querying organizations. The issuer must be an owner of the corresponding organization and the token itself must have read:org scope.

Note that it is currently not possible to differentiate between organizations by GitHub access tokens: a token will have access to all organizations of the issuer. It might be wise to register a separate account on GitHub which is owner precisely for the targeted organizations (and no more), and use this account as an issuer.

- type: team-membership
  access_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  organization_login: TestOrg
  team_name: Admins
  create_attributes:
    is_admin: true
    account_enabled: true
    password_sign_in_allowed: true
    max_session_lifetime: 3 days
  update_attributes:
    is_admin: true
    account_enabled: true

The `oraganization-membership` Strategy

- type: organization-membership
  organization_login: TestOrg
  create-attributes:
    is_admin: false
    account_enabled: true
    password_sign_in_allowed: false
    max_session_lifetime: 1 day
  update_attributes:
    account_enabled: true

A Real-World Example

The ZHdK Cider-CI Inventory hosts an effectively used and maintained Cider-CI inventory and configuration. The GitHub authentication configuration can be found in the file zhdk-inventory/group_vars/cider-ci_server.yml. The secrets are templated via Jinja2 filters and actually located in the encrypted zhdk-inventory/group_vars/secrets.yml file. The interplay with this and other files in the repository is governed by Ansible's rules of Variable Precedence.