auth

README

Overview

This directory implements authentication and authorization for Veraison API. Authentication can be performed using the Basic HTTP scheme (with the basic backend), or using a Bearer token (with the keycloak backend). Once an API user is authenticated, authorization is role-based. See documentation for specific services for which role(s) are needed to access their API.

Configuration

• backend: specifies which auth backend will be used by the service. The valid options are:

  • passthrough: a backend that does not perform any authentication, allowing all requests.
  • none: alias for passthrough.
  • basic: Uses the Basic HTTP authentication scheme. See RFC7617 for details. This is not intended for production.
  • keycloak: Uses OpenID Connect protocol as implemented by the Keycloak authentication server.

  See below for details of how to configure individual backends.

Passthrough

No additional configuration is required. passthrough will allow all requests. This is the default if auth configuration is not provided.

Basic

• users: this is a mapping of user names onto their bcrypt password hashes and roles. The key of the mapping is the user name, the value is a further mapping for the details with the following fields:

  • password: the bcrypt hash of the user's password.
  • roles: either a single role or a list of roles associated with the user. API authrization will be performed based on the user's roles.

On Linux, bcrypt hashes can be generated on the command line using mkpasswd utility, e.g.:

mkpasswd -m bcrypt --stdin <<< Passw0rd!

For example:

auth:
  backend: basic
  users:
    user1:
      password: "$2b$05$XgVBveh6QPrRHXI.8S/J9uobBR7Wv9z4CL8yACHEmKIQmYSSyKAqC" # Passw0rd!
      roles: provisioner
    user2:
      password: "$2b$05$x5fvAV5WPkX0KXzqf5FMKODz0uyi2ioew1lOrF2Czp2aNH1LQmhki" # @s3cr3t
      roles: [manager, provisioner]

Keycloak

• host (optional): host name of the Keycloak service. Defaults to localhost.
• port (optional): the port on which the Keycloak service is listening. Defaults to 8080.
• realm (optional): the Keycloak realm used by Veraison. A realm contains the configuration for clients, users, roles, etc. It is roughly analogous to a "tenant id". Defaults to veraison.
• ca-cert: the path to a PEM-encoded x509 cert that will be added to CA certs when establishing connection to the Keycloak server. This should be specified if the server has HTTPS enabled and the root CA for its cert is not installed in the system.

For example:

auth:
  backend: keycloak
  host: keycloak.example.com
  port: 11111
  realm: veraison

Usage

"github.com/gin-gonic/gin"
"github.com/veraison/services/auth"
"github.com/veraison/services/config"
"github.com/veraison/services/log"

func main() {
    // Load authroizer config.
	v, err := config.ReadRawConfig(*config.File, false)
	if err != nil {
		log.Fatalf("Could not read config: %v", err)
	}
	subs, err := config.GetSubs(v, "*auth")
	if err != nil {
		log.Fatalf("Could not parse config: %v", err)
	}

    // Create new authorizer based on the loaded config.
	authorizer, err := auth.NewAuthorizer(subs["auth"], log.Named("auth"))
	if err != nil {
		log.Fatalf("could not init authorizer: %v", err)
	}

    // Ensure the authorizer is terminated properly on exit
	defer func() {
		err := authorizer.Close()
		if err != nil {
			log.Errorf("Could not close authorizer: %v", err)
		}
	}()

    // Use the authorizer to set a middleware handler in the appropriate gin
    // router, with an appropriate role.
    router := gin.Default()
	router.Use(authorizer.GetGinHandler(auth.ManagerRole))

    // Set up route handling here
    // ...
    // ...

    // Run the service.
    if err := router.Run("0.0.0.0:80"); err != nil {
		log.Errorf("Gin engine failed: %v", err)
    }
}

Documentation

Overview

Copyright 2023-2024 Contributors to the Veraison project. SPDX-License-Identifier: Apache-2.0

Copyright 2023 Contributors to the Veraison project. SPDX-License-Identifier: Apache-2.0

Copyright 2024 Contributors to the Veraison project. SPDX-License-Identifier: Apache-2.0

Copyright 2023 Contributors to the Veraison project. SPDX-License-Identifier: Apache-2.0

Index

• Variables
• func ReportProblem(c *gin.Context, status int, details ...string)
• type BasicAuthorizer
  • func (o *BasicAuthorizer) Close() error
  • func (o *BasicAuthorizer) GetGinHandler(role string) gin.HandlerFunc
  • func (o *BasicAuthorizer) Init(v *viper.Viper, logger *zap.SugaredLogger) error
• type IAuthorizer
  • func NewAuthorizer(v *viper.Viper, logger *zap.SugaredLogger) (IAuthorizer, error)
  • func NewPassthroughAuthorizer(logger *zap.SugaredLogger) IAuthorizer
• type KeycloakAuthorizer
  • func (o *KeycloakAuthorizer) Close() error
  • func (o *KeycloakAuthorizer) GetGinHandler(role string) gin.HandlerFunc
  • func (o *KeycloakAuthorizer) Init(v *viper.Viper, logger *zap.SugaredLogger) error
• type PassthroughAuthorizer
  • func (o *PassthroughAuthorizer) Close() error
  • func (o *PassthroughAuthorizer) GetGinHandler(role string) gin.HandlerFunc
  • func (o *PassthroughAuthorizer) Init(v *viper.Viper, logger *zap.SugaredLogger) error

Variables

var ManagerRole = "manager"

var NoRole = ""

var ProvisionerRole = "provisioner"

Functions

func ReportProblem

func ReportProblem(c *gin.Context, status int, details ...string)

Types

type BasicAuthorizer

type BasicAuthorizer struct {
	// contains filtered or unexported fields
}

func (*BasicAuthorizer) Close

func (o *BasicAuthorizer) Close() error

func (*BasicAuthorizer) GetGinHandler

func (o *BasicAuthorizer) GetGinHandler(role string) gin.HandlerFunc

func (*BasicAuthorizer) Init

func (o *BasicAuthorizer) Init(v *viper.Viper, logger *zap.SugaredLogger) error

type IAuthorizer

type IAuthorizer interface {
	// Init initializes the backend based on the configuration inside the
	// provided Viper object and using the provided logger.
	Init(v *viper.Viper, logger *zap.SugaredLogger) error
	// Close terminates the backend. The exact nature of this method is
	// backend-specific.
	Close() error
	// GetGinHandler returns a gin.HandlerFunc that performs authorization
	// based on the specified role. This function can be set as gin
	// middleware by passing it to gin.Engine.Use().
	GetGinHandler(role string) gin.HandlerFunc
}

IAuthorizer defines the interface that must be implemented by the veraison auth backends.

func NewAuthorizer

func NewAuthorizer(v *viper.Viper, logger *zap.SugaredLogger) (IAuthorizer, error)

func NewPassthroughAuthorizer

func NewPassthroughAuthorizer(logger *zap.SugaredLogger) IAuthorizer

type KeycloakAuthorizer

type KeycloakAuthorizer struct {
	// contains filtered or unexported fields
}

func (*KeycloakAuthorizer) Close

func (o *KeycloakAuthorizer) Close() error

func (*KeycloakAuthorizer) GetGinHandler

func (o *KeycloakAuthorizer) GetGinHandler(role string) gin.HandlerFunc

func (*KeycloakAuthorizer) Init

func (o *KeycloakAuthorizer) Init(v *viper.Viper, logger *zap.SugaredLogger) error

type PassthroughAuthorizer

type PassthroughAuthorizer struct {
	// contains filtered or unexported fields
}

func (*PassthroughAuthorizer) Close

func (o *PassthroughAuthorizer) Close() error

func (*PassthroughAuthorizer) GetGinHandler

func (o *PassthroughAuthorizer) GetGinHandler(role string) gin.HandlerFunc

func (*PassthroughAuthorizer) Init

func (o *PassthroughAuthorizer) Init(v *viper.Viper, logger *zap.SugaredLogger) error