loginapp

Loginapp

Web application for Kubernetes CLI configuration with OIDC

Usage

Perform configuration checks and run Loginapp.

Loginapp supports three configuration formats:
* Configuration file: '--config' flag
* Flags: '--oidc-xxx' flags for example
* Environment vars: each flag provides an environment var with
  'LOGINAPP_' prefix.
  Ex: '--oidc-client-secret' --> 'LOGINAPP_OIDC_CLIENT_SECRET'

Configuration precedence: flags > environment vars > configuration file

Usage:
  loginapp serve [flags]

Flags:
  -c, --config string                            Configuration file
  -h, --help                                     help for serve
  -l, --listen string                            Listen interface and port (default "0.0.0.0:8080")
      --metrics-port int                         Port to export metrics (default 9090)
  -n, --name string                              Application name. Used for web title. (default "Loginapp")
      --oidc-client-id string                    Client ID (default "loginapp")
      --oidc-client-redirecturl string           Redirect URL for callback. This must be the same than the one provided to the IDP. Must end with '/callback'
      --oidc-client-secret string                Client secret
      --oidc-crossclients strings                Issue token on behalf of this list of client IDs
      --oidc-extra-authcodeopts stringToString   K/V list of extra authorisation code to include in token request (default [])
      --oidc-extra-scopes strings                [DEPRECATED] List of extra scopes to ask. Use oidc.scopes option instead. Option will be removed in next release.
      --oidc-issuer-insecureskipverify           Skip issuer certificate validation (usefull for testing). It is not advised to use this option in production
      --oidc-issuer-rootca string                Certificate authority of the issuer
      --oidc-issuer-url string                   Full URL of issuer before '/.well-known/openid-configuration' path
      --oidc-offlineasscope                      Issue a refresh token for offline access
      --oidc-scopes strings                      List of scopes to request. Updating this parameter will override existing scopes. (default [openid,profile,email,groups])
  -s, --secret string                            Application secret. Must be identical across all loginapp server replicas (this is not the OIDC Client secret)
      --tls-cert string                          TLS certificate path
      --tls-enabled                              Enable TLS
      --tls-key string                           TLS private key path
      --web-assetsdir string                     Directory to look for assets, which are overriding embedded (default "/web/assets")
      --web-kubeconfig-defaultcluster string     Default cluster name to use for full kubeconfig output
      --web-kubeconfig-defaultnamespace string   Default namespace to use for full kubeconfig output (default "default")
      --web-mainclientid string                  Application client ID
      --web-mainusernameclaim string             Claim to use for username (depends on IDP available claims (default "email")
      --web-templatesdir string                  Directory to look for templates, which are overriding embedded (default "/web/templates")

Global Flags:
  -v, --verbose   Verbose output

Configuration

# Application name
# default: mandatory
name: "Kubernetes Auth"

# Bind IP and port (format: "IP:PORT")
# default: mandatory
listen: "0.0.0.0:5555"

# Application secret. Must be identical across
# all loginapp server replicas ( /!\ this is not the OIDC Client secret)
secret: REDACTED

# OIDC configuration
oidc:

  # Client configuration
  client:
    # Application ID
    # default: mandatory
    id: "loginapp"
    # Application Secret
    # default: mandatory
    secret: REDACTED
    # Application Redirect URL
    # must end with "/callback"
    # default: mandatory
    redirectURL: "https://127.0.0.1:5555/callback"

  # Issuer configuration
  issuer:
    # Location of issuer root CA certificate
    # default: mandatory if insecureSkipVerify is false
    rootCA: "example/ssl/ca.pem"
    # Issuer URL
    # default: mandatory
    url: "https://dex.example.com:5556"
    # Skip certificate validation
    # Default: false
    insecureSkipVerify: false

  # List of scopes to request.
  # Updating this parameter will override existing scopes.
  # Default:[openid,profile,email,groups]
  scopes: []

  # OIDC extra configuration
  extra:
    # [DEPREACTED] OIDC Scopes in addition to
    # "openid", "profile", "email", "groups"
    #
    # Use oidc.scopes instead
    #
    # default: []
    scopes: []

    # Extra auth code options
    # Some extra auth code options are required for:
    # * ADFS compatibility (ex: resource, https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/overview/ad-fs-openid-connect-oauth-flows-scenarios)
    # * Google OIDC compatibility (ex: https://developers.google.com/identity/protocols/oauth2/openid-connect#refresh-tokens)
    # See: 
    # default: {}
    authCodeOpts:
      resource: XXXXX

  # Enable offline scope
  # default: false
  offlineAsScope: true
  # Request token on behalf of other clients
  # default: []
  crossClients: []

# Tls support
tls:
  # Enable tls termination
  # default: false
  enabled: true
  # Certificate location
  # default: mandatory if tls.enabled is true
  cert: example/ssl/cert.pem
  # Key location
  # default: mandatory if tls.enabled is true
  key: example/ssl/key.pem

# Configure the web behavior
web:
  # ClientID to output (useful for cross_client)
  # default: value of 'oidc.client.id'
  mainClientID: loginapp
  # Claims to use for kubeconfig username.
  # default: email
  mainUsernameClaim: email
  # Kubeconfig output format
  kubeconfig:
    # Change default cluster for kubeconfig context
    # Default: first cluster name in `clusters`
    defaultCluster: mycluster
    # Change default namespace for kubeconfig contexts
    # Default: default
    defaultNamespace: default
    # Change default context for kubeconfig
    # If not set, use a format like 'defaultClusterName'/'usernameClaim'
    # Default: ""
    defaultContext: altcontextname
    # Extra key/value pairs to add to kubeconfig output.
    # Key/value pairs are added under `user.auth-provider.config`
    # dictionnary into the kubeconfig.
    # Ex:
    # extraOpts:
    #   mykey1: value1
    #
    # Kubeconfig Output:
    # - name: user.name@example.org
    #     auth-provider:
    #       config:
    #         mykey1: value1
    #         client-id: loginapp
    #         [...]
    extraOpts: {}

# Metrics configuration
metrics:
  # Port to use. Metrics are available at
  # http://IP:PORT/metrics
  # default: 9090
  port: 9090

# Clusters list for CLI configuration
clusters:
  - name: mycluster
    server: https://mycluster.org
    certificate-authority: |
      -----BEGIN CERTIFICATE-----
      MIIC/zCCAeegAwIBAgIULkYvGJPRl50tMoVE4BNM0laRQncwDQYJKoZIhvcNAQEL
      BQAwDzENMAsGA1UEAwwEbXljYTAeFw0xOTAyMTgyMjA5NTJaFw0xOTAyMjgyMjA5
      NTJaMA8xDTALBgNVBAMMBG15Y2EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK
      -----END CERTIFICATE-----
    insecure-skip-tls-verify: false
    # Alternative context name for this cluster
    contextName: altcontextname

Deployment

• Run the binary for development purpose

• Deploy with helm:

  • Example for testing: see ./test/genconf.sh file and Dev section
  • Prepare your deployment

Dev

Loginapp uses go modules to manage dependencies.

  # Retrieve dependencies (vendor)
  go mod vendor

Configuration files are located in example directory

  $ make

Run also gofmt before any new commit:

  make gofmt

Loginapp uses kind and skaffold for development environment.

Setup steps:

1. Launch a kind cluster:

   $ test/kubernetes/kindup.sh
   $ kubectl get node
   NAME                     STATUS   ROLES    AGE   VERSION
   loginapp-control-plane   Ready    master   25m   v1.17.0
   

2. Generate Dex & Loginapp certificates and configuration for the dev env:

   $ test/genconf.sh
   [...]
   Creating TLS secret for loginapp
   Generating dex and loginapp configurations
   [...]
   

3. Launch skaffold:

• For local dev, launch just dex:

  # Deploy dex
  $ skaffold run -p dex
  

• To test kubernetes deployment, launch dex and loginapp:

  # Deploy dex and loginapp
  $ skaffold run -p dex,loginapp
  

• Test helm deployment:

  # Deploy dex and loginapp
  $ skaffold run -p helm
  

1. [local] Compile and run loginapp:

   $ make
   # A default configurationn is generated at test/generated/loginapp-config-manual.yaml
   $ ./build/loginapp -v serve [-c test/generated/loginapp-config-manual.yaml]
   [...]
   {"level":"info","msg":"export metric on http://0.0.0.0:9090","time":"2020-04-28T18:19:19+02:00"}
   {"level":"info","msg":"listening on https://0.0.0.0:8443","time":"2020-04-28T18:19:19+02:00"}
   [...]
   

2. Access loginapp UI:

   • For local dev, access URL will be: https://loginapp.127.0.0.1.nip.io:8443
   • For kubernetes test, access URL will be: https://loginapp.${NODE_IP}.nip.io:32001, where NODE_IP is the IP of the kind control plane container.

3. Default user/password configured by Dex is:

   • User: admin@example.com
   • Password: password

Alternatives

Other projects performing OIDC authentication:

• gangway (web)
• kubelogin (cli)

MISC

The code base of this repository uses some source code from the original dexidp/dex repository.