scripts

README

FEUDAL Scripts Version 3

FEUDAL scripts (also called adapters) are used to deploy feudal users in a customizable fashion. They are executed by a feudalClient and have a specific input and output.

This go library can be used as a basis to implement such a script. Examples can be found here: a simple stub, creating SSH access, and handling questionnaires.

The scripts use json for input and output. The specific formats are outlined below. The input is passed to the scripts via stdin.

The feudalClient can be used to generate and validate json schema for input and output, see:

   feudalClient schema --help
   feudalClient validate --help

Input Format

{
    // The state which is to be reached by this script execution
    //
    // deployed     -> the script is supposed to deploy the user
    // not_deployed -> the script is supposed to remove the user
    "state_target": "deployed" or "not_deployed",


    // The user which is requesting access
    "user": {
        "userinfo": <OpenID Connect userinfo as json dict>

        // The credentials from the user, which need to be deployed
        // The dict maps a credential type to a list of credentials of this type.
        "credentials": {
            "ssh_key": [
                {
                    "name": "unity_key",
                    "value": "ssh-... ..."
                }
            ]
        },
    },


    // Answers to a previously requested questionnaire, may not be present
    "answers": {
      "question_name": "user answer to this question",
      "age_question": 18,
      "list_question": "person_a",
      "list_question_2": 2,
      "are_you_sure": true
    }
}

Output Format

{
    // The state as of now (after the script run)
    //
    // deployed     -> The deployment was processed successfully
    // not_deployed -> The removal of the user was processed successfully
    // failed       -> An error occured and the script could not reach the 'state_target' from the Input
    // rejected     -> The user is not permitted to use this service, for whatever reason
    // questionnaire-> The script needs more information to deploy the user
    "state": "deployed" or "not_deployed" or "failed" or "rejected" or "questionnaire",


    "message": "<message for the user describing what happened. Must not be empty.",

    // In case we need more info from the user: set state to "questionnaire" and put
    // questions in this dictionary.
    // The user can answer these questions (and we will receive the answers some input in the future)
    "questionnaire": {
        "question_name": "question",
        "age_question": "How old are you?",
        "list_question": "Who are you?",
        "list_question_2": "How many do you want?",
        "are_you_sure": "What you are trying is wrong. Are you sure?"
    },

    // By default questions in questionnaire expect answers are strings. You can change this here:
    // Add a mapping with the same key here
    "questionnaire_answers": {
        "question_name": "question",                    // string default value
        "age_question": 18,                             // age_question must be an integer, defaulting to 18
        "list_question": ["person_a", "person_b"],      // list_question must be one of the listed options
        "list_question_2": [1, 2],                      // list_question_2 must be one of the listed options
        "are_you_sure": false                          // are_you_sure must be a boolean, with false being the default value
    },

    // additional credentials and instructions, the user needs to access the service (in addition to her credentials from the Input)
    // an example would be the user name of the provisioned user.
    "credentials": {
        "key": "value"
    }
}

Documentation

Index

• type Credential
• type Input
  • func UnmarshalInput(inputBytes []byte) (i Input, err error)
  • func (i Input) Marshal() (iBytes []byte, err error)
  • func (i Input) String() string
• type Output
  • func UnmarshalOutput(inputBytes []byte) (i Output, err error)
  • func (o Output) Marshal() (oBytes []byte, err error)
  • func (o Output) String() string
• type State
• type User
  • func (u User) String() string
• type UserCredentialStates
• type UserCredentials
• type UserInfo

Types

type Credential

type Credential struct {
	ID    int    `json:"id,omitempty"`
	Type  string `json:"type,omitempty"`
	Name  string `json:"name"`
	Value string `json:"value"`
}

Credential is currently a ssh key, but may be a password hash in the future

type Input

type Input struct {
	// StateTarget is the state which is to be reached by this deployment task
	// StateTarget is either Deployed or NotDeployed
	StateTarget State `json:"state_target"`

	// User describes the user of this deployment task
	User User `json:"user"`

	// Credentials the credentials to deploy
	// maps the credential type to the according credentials
	//
	// This is now located in Input.User.Credentials
	// This field will therefore be removed in the future!
	Credentials UserCredentials `json:"credentials,omitempty"`

	// Questionnaire is an answered questionnaire
	// Maps a question name to the answer of the user
	// The keys (question names) *must* be identical to those of the Output.Questionnaire
	// containing the questions
	Questionnaire map[string]string `json:"questionnaire,omitempty"`
}

Input of the deployment script

func UnmarshalInput

func UnmarshalInput(inputBytes []byte) (i Input, err error)

UnmarshalInput decodes a json encoded input

func (Input) Marshal

func (i Input) Marshal() (iBytes []byte, err error)

Marshal encodes an Input as json

func (Input) String

func (i Input) String() string

type Output

type Output struct {
	// State of the deployment, after the script execution
	// when State == Questionnaire then Output.Questionnaire *must* be set
	// when State == Deployed then Output.Credentials *can* be set
	State State `json:"state"`

	// Message for the user
	Msg string `json:"message"`

	// Questionnaire requested by the script
	// Ignored when State is not Questionnaire
	// Maps a question name to a description of the question
	Questionnaire map[string]string `json:"questionnaire,omitempty"`

	// Credentials for the user
	// Ignored when State is not Deployed
	// Maps a credential name to a credential value
	Credentials map[string]string `json:"credentials,omitempty"`

	// UserCredentialStates are the State s of the credentials found in Input.User.Credentials.
	//
	// This field is not mandatory. The client will assume that all credentials have the State
	// Output.State if this field is not given.
	UserCredentialStates UserCredentialStates `json:"user_credential_states,omitempty"`
}

Output of the deployment script

func UnmarshalOutput

func UnmarshalOutput(inputBytes []byte) (i Output, err error)

UnmarshalOutput decodes a json encoded output

func (Output) Marshal

func (o Output) Marshal() (oBytes []byte, err error)

Marshal encodes an Output as json

func (Output) String

func (o Output) String() string

type State

type State string

State is a string enum The enum values for State are listed below

const (
	// Deployed value for State
	Deployed State = "deployed"

	// NotDeployed value for State
	NotDeployed State = "not_deployed"

	// Rejected value for State
	// the user can never be deployed
	Rejected State = "rejected"

	// Failed value for State
	// the deployment can be retried
	Failed State = "failed"

	// Questionnaire value for State
	// the user has to fill the questionnaire
	// with the questionnaire data the deployment can be retried
	Questionnaire State = "questionnaire"
)

type User

type User struct {
	UserInfo    UserInfo        `json:"userinfo"`
	Credentials UserCredentials `json:"credentials"`
}

User contains information concerning the user of a deployment

func (User) String

func (u User) String() string

type UserCredentialStates

type UserCredentialStates map[string]map[string]State

UserCredentialStates serves to inform the backend about the per credential states after the script run

type UserCredentials

type UserCredentials map[string][]Credential

UserCredentials maps a credential type to the credentials of this type

type UserInfo

type UserInfo map[string]interface{}

UserInfo info about the user