jacamarplugins

README

Jacamar Plugins

Jacamar CI offers a flexible series of configurations to support downsoping CI users permissions to that of their equivalent local user account. Part of this strategy is the optionally enabled RunAs process. Instead of a traditional script you can leverage a GoLang plugin support in conjunction with the structures established in this project.

Please note that is an ongoing development efforts and plugin support is currently in an experimental state and subject to change. We will signify the product readiness of plugins for Jacamar CI by releasing a 1.0 version of this project.

Basic Example

To start you simply need to full the requirement of having a function that conforms to; func(jacamarplugins.RunAsInit) (jacamarplugins.RunAsOverride, error). This will be invoked by Jacamar as part of the authorization flow and all established job context provided as an argument. A simple example of such a package would appear as:

package main

import (
    "errors"

    "gitlab.com/ecp-ci/jacamar-plugins"
)

func Validate(r jacamarplugins.RunAsInit) (over jacamarplugins.RunAsOverride, err error) {
    if r.CurrentUser == "gitlab_user" {
        over.Username = "local_User"
    } else {
        err = errors.New("unsupported user")
    }

    return
}

Now simply build the associated plugin:

go build -trimpath -buildmode=plugin -o /etc/gitlab-runner/runas.so

Finally, reference this plugin in your configuration file:

[general]
executor = "shell"
data_dir = "/ci"

[auth]
downscope = "setuid"

[auth.runas]
validation_plugin = "/etc/gitlab-runner/runas.so"
user_variable = "RUNAS_TARGET"

Documentation

Overview

Package jacamarplugins implements supported structures that must be used by an admin defined RunAs validation plugin (https://golang.org/pkg/plugin/).

Index

• type JobJWT
• type RunAsInit
• type RunAsOverride
  • func (ro RunAsOverride) Validator() error

Types

type JobJWT

type JobJWT struct {
	// JobID is the unique ID of the current job that GitLab uses internally.
	JobID string `env:"JWT_JOB_ID"`
	// NamespaceID is the unique ID given to a username or group name
	// that the current project belongs to.
	NamespaceID string `env:"JWT_NAMESPACE_ID"`
	// PipelineID is the unique ID of the current CI pipeline.
	PipelineID string `env:"JWT_PIPELINE_ID"`
	// ProjectID is the unique ID of the current project.
	ProjectID string `env:"JWT_PROJECT_ID"`
	// ProjectPath is the human readable namespace for the project.
	ProjectPath string `env:"JWT_PROJECT_PATH"`
	// UserEmail is the primary email of the user who started the job.
	UserEmail string `env:"JWT_USER_EMAIL"`
	// UserID is the identification number of the user who started the job.
	UserID string `env:"JWT_USER_ID"`
	// UserLogin is the login username of the user who started the job. Can be user
	// changed depending on server deployment (always verify your deployment before
	// trusting this value).
	UserLogin string `env:"JWT_USER_LOGIN"`
}

JobJWT contains key payload values from a CI_JOB_JWT whose signature and checksum have been validated by Jacamar.

type RunAsInit

type RunAsInit struct {
	// TargetUser is a user proposed account (via the CI environment) meant to be the
	// replaced for the CurrentUser if the process is approved.
	TargetUser string `env:"RUNAS_TARGET_USER"`
	// CurrentUser is the currently identified local user account of the CI trigger user.
	// This can differ from the JWT's UserLogin depending on configuration of the authorization,
	// and should be observed when attempting to approve a local user account.
	CurrentUser string `env:"RUNAS_CURRENT_USER"`
	// AuthToken the IdP supplied token during a federated workflow.
	AuthToken string `env:"FEDERATED_AUTH_TOKEN"`
	// FedUsername the IdP supplied username during a federated workflow.
	FedUsername string `env:"FEDERATED_USERNAME"`
	JobJWT
}

RunAsInit values are used to established user context for the upcoming authorization.

type RunAsOverride

type RunAsOverride struct {
	// Username is the valid local account that will be the target henceforth
	// for the authorization process.
	Username string `json:"username" validate:"username"`
}

RunAsOverride represents potential values that can be returned to Jacamar to override or influence authorization flow behaviors beyond a simple pass/fail result.

func (RunAsOverride) Validator

func (ro RunAsOverride) Validator() error

Validator is used to ensure that all payload values confirm to Jacamar expectations.