Skip to content

Latest commit

 

History

History
671 lines (518 loc) · 24.7 KB

configuration.md

File metadata and controls

671 lines (518 loc) · 24.7 KB

Candid Configuration

Introduction

This document describes the configuration options for the Candid identity server.

Configuration File

Candid loads its configuration at startup from a YAML file. In a usual installation this file is stored in /etc/candid/config.yaml. An example configuration file is:

listen-address: :8081
location: 'http://jujucharms.com/identity'
storage:
    type: mongodb
    address: localhost:27017
public-key: OAG9EVDFgXzWQKIk+MTxpLVO1Mp1Ws/pIkzhxv5Jk1M=
private-key: q2G3A2NjTe7MP9D8iugCH9XfBAyrnV8n8u8ACbNyNOY=
identity-providers:
- type: usso

Here is a description of the most commonly used configuration options. Some less useful options are omitted here - the remaining ones are all documented here.

listen-address

(Required) This is the address that the service will listen on. This consists of an optional host followed by a port. If the host is omitted then the server will listen on all interface addresses. The port may be a well known service name for example ":http".

location

(Required) This is the externally addressable location of the Candid server API. Candid needs to know its own address so that it can add third-party caveats addressed to itself and to create response addresses for identity providers such as OpenID that use browser redirection for communication.

storage

Storage holds configuration for the storage backend used by the server. See below for documentation on the supported storage backends.

public-key & private-key

(Required) Services wishing to discharge caveats against this identity manager encrypt their third party caveats using this public-key. The private key is needed for the identity manager to be able to discharge those caveats. You can use the bakery-keygen command (available with go install gopkg.in/macaroon-bakery.v2/cmd/bakery-keygen to generate a suitable key pair.

access-log

The access-log configures the name of a file used to record all accesses to the identity manager. If this is not configured then no logging will take place.

identity-providers

This is a list of the configured identity providers with their configuration. See below for the supported identity providers. If this is not configured then a default set of providers will be used containing the Ubuntu SSO and Agent identity providers.

api-macaroon-timeout

This is the maximum time a login to the /v1 API will remain logged in for. As candid uses itself as its authentication provider, for all practical purpose the login time will be the minimum of api-macaroon-timeout and discharge-macaroon-timeout . The default value is 24 hours.

discharge-macaroon-timeout

This is the maximum time the discharge macaroon will be valid for on the target service. This is the maximum time the client will be able to access the target service without requiring re-authentication. Note that the target service may also have its own maximum time.

discharge-token-timeout

This is the maximum time that the discharge token issued to the client can be used to discharge tokens without requiring re-authentication.

redirect-login-trusted-urls

This is a list of trusted return-to addresses for use in the redirect-based login process. If a redirect-based login is attempted with a return-to address that does not match an entry in either redirect-login-trusted-urls or redirect-login-trusted-domains then candid will show an error page rather than redirect the user's browser.

To match an entry in redirect-login-trusted-urls the return-to address must match exactly.

redirect-login-trusted-domains

This is a list of trusted domains that are used in return-to addresses for use in the redirect-based login process. If a redirect-based login is attempted with a return-to address that does not match an entry in either redirect-login-trusted-domains or redirect-login-trusted-urls then candid will show an error page rather than redirect the user's browser.

Entries in the the redirect-login-trusted-domains list take the form of either a full host name (e.g www.example.com) or a wildcard domain (e.g. *.example.com). The former type causes all return-to URLs with a host part that exactly matches the entry to be trusted. The latter type causes all return-to URLs with a host part that is a subdomain of the specified domain to be trusted.

Please note that all paths in a redirect-login-trusted-domain are trusted, so these should only be used where a trusted party controls the entire domain.

mfa-rp-display-name

This is the name of the candid as a relying party for the multi-factor authentication.

mfa-rp-id

This is the id of candid as a relying party for the multi-factor authentication - in general this should be set to the FQDN of candid.

mfa-rp-origin

This is the origin url of the WebAuthn requests for candid.

Storage Backends

The storage field holds an object containing a type field which names the storage backend to use.

For example:

storage:
    type: mongodb
    address: localhost:1234

Currently supported backends are:

memory

The memory provider has no extra parameters. It stores all data ephemerally in RAM.

mongodb

This uses MongoDB for the backend. It has two parameters:

address (required) is the address of the mongoDB server to connect to, in host:port form.

database holds the database name to use. If not specified, this will default to candid .

postgres

This uses PostgresQL for the backend. It takes one parameter:

connection-string is the connection string to use when connecting to the database. This is added to connection string parameters already present as environment variables when making a connection. See here for details.

Identity Providers

The identity manager can support a number of different identity providers. These can be broken loosely into two categories, interactive and custom. Interactive providers use html based forms in some way to authorize the user and are compatible with the most basic supported clients. Custom providers use a protocol not necessarily supported in the client to provide additional authentication methods that are not necessarily based around users interacting with web pages. While it is possible to configure more than one interactive identity provider in a given identity manager, in most case this does not make sense as the identity manager will only use the first one that is found.

Agent

The agent identity provider is a custom provider that is always configured, and allows non-interactive logins to clients using public-key authentication. the agent protocol to log in. See https://github.com/canonical/candid/blob/master/docs/login.txt for details on the agent login protocol.

UbuntuSSO

- type: usso
  name: usso
  domain: external
  icon: /static/images/usso-icon.bmp
  description: Ubuntu SSO
  launchpad-teams:
    - group1
    - group2
  staging: false
  fixed-username: false

The UbuntuSSO identity provider is an interactive identity provider that uses OpenID with UbuntuSSO to log in.

The name parameter specifies the name of the provider, this should be a short name that reflects the name of the system being logged in to. The name is used in some URLS and is best if it consists only of lower-case letters.

The domain is a string added to the names of users logging in through this identity provider. The user jsmith for example would be changed to jsmith@example in the configuration above. If no domain is specified the username will remain unchanged.

The description is optional and will be used if the identity provider is presented in a human readable form, if this is not set "Ubuntu SSO" will be used.

The icon is optional and specifies the location of an icon to display when presenting the identity-provider options to a user. It this is set to URL path then that path should be relative to the candid service's location. If this is not set a default icon for Ubuntu SSO will be used.

The launchpad-teams contains any private launchpad teams that candid needs to know about.

If staging is true then the identity provider will use staging instances of Ubuntu SSO and launchpad for the identity information.

If fixed-username is true then username changes returned from Ubuntu SSO will not be automatically reflected when a user authenticates. The username in candid will remain fixed to the username that is first used.

UbuntuSSO OAuth

- type: usso_oauth

The UbuntuSSO OAuth identity provider is an custom identity provider that uses a previously obtained UbuntuSSO OAuth token to log in.

Keystone

- type: keystone
  name: canonistack
  domain: canonistack
  description: Canonistack
  icon: /static/images/keystone-icon.bmp
  url: https://keystone.canonistack.canonical.com:443/
  hidden: false

The Keystone identity provider is an interactive identity provider that uses a keystone service to log the user in using their openstack credentials.

The Keystone identity provider has a number of additional options.

The name parameter specifies the name of the provider, this should be a short name that reflects the name of the system being logged in to. The name is used in some URLS and is best if it consists only of lower-case letters.

The domain is a string added to the names of users logging in through this identity provider. The user jsmith for example would be changed to jsmith@canonistack in the configuration above. If no domain is specified the username will remain unchanged.

The description is optional and will be used if the identity provider is presented in a human readable form, if this is not set the name will be used.

The icon is optional and specifies the location of an icon to display when presenting the identity-provider options to a user. It this is set to URL path then that path should be relative to the candid service's location. If this is not set a default icon for keystone will be used.

The url is the location of the keystone server that will be used to authenticate the user.

The hidden value is an optional value that can be used to not list this identity provider in the list of possible identity providers when performing an interactive login.

Keystone Token

- type: keystone_token
  name: jujugui
  domain: canonistack
  description: Canonistack
  url: https://keystone.canonistack.canonical.com:443/

The Keystone Token identity provider is a custom identity provider that uses a keystone service to authenticate a user that already has a keystone authentication token by logging in previously through some external means. It is designed to be used in jujugui system embedded in horizon services to prevent a user having to log in twice.

The Keystone Token identity provider has a number of additional options.

The name parameter specifies the name of the provider. The name is used in some URLS and is best if it consists only of lower-case letters. The name "jujugui" can be used to indicate to a jujugui instance that this provider can be used to log in with an existing token.

The domain is a string added to the names of users logging in through this identity provider. The user jsmith for example would be changed to jsmith@canonistack in the configuration above. If no domain is specified the username will remain unchanged.

The description is optional and will be used if the identity provider is presented in a human readable form, if this is not set the name will be used.

The url is the location of the keystone server that will be used to authenticate the user.

Keystone Userpass

- type: keystone_userpass
  name: form
  domain: canonistack
  description: Canonistack
  url: https://keystone.canonistack.canonical.com:443/

The Keystone Userpass identity provider is a custom identity provider that uses a keystone service to authenticate users that have provided their username and password through a form mechanism in the client. It is designed to allow credentials to be provided through a CLI where web page access is not practical.

The Keystone Userpass identity provider has a number of additional options.

The name parameter specifies the name of the provider. The name is used in some URLS and is best if it consists only of lower-case letters. The name "form" can be used to indicate to clients that support the form protocol that the protocol can be used.

The domain is a string added to the names of users logging in through this identity provider. The user jsmith for example would be changed to jsmith@canonistack in the configuration above. If no domain is specified the username will remain unchanged.

The description is optional and will be used if the identity provider is presented in a human readable form, if this is not set the name will be used.

The url is the location of the keystone server that will be used to authenticate the user.

Azure OpenID Connect

- type: azure
  icon: /static/images/azure-icon.bmp
  client-id: 43444f68-3666-4f95-bd34-6fc24b108019
  client-secret: tXV2SRFflAGT9sUdxkdIi7mwfmQ=
  hidden: false

The Azure identity provider uses OpenID Connect to log in using Microsoft credentials via https://login.live.com. When a user first logs in with this IDP they will be prompted to create a new identity. The new identity must have a unique username and will be in the domain "@azure".

The icon is optional and specifies the location of an icon to display when presenting the identity-provider options to a user. It this is set to URL path then that path should be relative to the candid service's location. If this is not set a default icon for azure will be used.

The client-id and client-secret parameters must be specified and are created by registering the candid instance as an application at https://apps.dev.microsoft.com. When registering the application the redirect URLs should include $CANDID_URL/login/azure/callback .

The hidden value is an optional value that can be used to not list this identity provider in the list of possible identity providers when performing an interactive login.

ADFS OpenID Connect

- type: adfs
  name: example
  domain: example
  icon: /static/images/adfs.bmp
  url: https://adfs.example.com
  client-id: 43444f68-3666-4f95-bd34-6fc24b108019
  client-secret: tXV2SRFflAGT9sUdxkdIi7mwfmQ=
  hidden: true
  match-email-addr: @example.com$

The ADFS identity provider uses OpenID Connect to authenticate with an Active Directory Federation Services deployment.

The icon is optional and specifies the location of an icon to display when presenting the identity-provider options to a user. It this is set to URL path then that path should be relative to the candid service's location. If this is not set a default generic OpenID icon will be used.

The required url parameter specifies the location of the ADFS OpenID Connect service. OpenID Connect Discovery will be performed using this URL to determine the correct endpoints, keys and other parameters required to successfully perform OpenID Connect authentication.

The client-id and client-secret parameters must be specified and are created by registering the candid instance as an application on the ADFS service. When registering the application the redirect URLs should include $CANDID_URL/login/{name}/callback . When authenticating candid requests the "email" and "profile" scopes in addition to the "openid" scope in order to retrieve the required profile information.

The hidden value is an optional value that can be used to not list this identity provider in the list of possible identity providers when performing an interactive login.

The match-email-addr value is a regular expression that can be used to select the identity provider using an email address. If configured when a user attempts to login via an email address the address will be checked against the regular expression and if they match the identity provider will be used to perform the login.

Google OpenID Connect

- type: google
  icon: /static/images/google-icon.bmp
  client-id: 483156874216-rh0j89ltslhuqirk7deh70d3mp49kdvq.apps.googleusercontent.com
  client-secret: 8aENrwCL/+PU87ROkXwMB+09xe0=
  hidden: false

The Google identity provider uses OpenID Connect to log in using Google credentials. When a user first logs in with this IDP they will be prompted to create a new identity. The new identity must have a unique username and will be in the domain "@google".

The client-id and client-secret parameters must be specified and are created by registering the candid instance as an application at https://console.developers.google.com/apis/credentials. When registering the application the authorized redirect URLs should include $CANDID_URL/login/google/callback .

The icon is optional and specifies the location of an icon to display when presenting the identity-provider options to a user. It this is set to URL path then that path should be relative to the candid service's location. If this is not set a default icon for google will be used.

The hidden value is an optional value that can be used to not list this identity provider in the list of possible identity providers when performing an interactive login.

Keycloak OpenID Connect

- type: keycloak
  domain: example
  client-id: 483156874216
  client-secret: 32hf3uhud23dS@#e
  keycloak-realm: https://example.com/auth/realms/example
  hidden: false

The Keycloak identity provider uses OpenID Connect to log in using configured credentials. When a user first logs in with this IDP they will be prompted to create a new identity. The new identity must have a unique username and will be in the domain specified "@domain", otherwise default to "@KEYCLOAK".

The icon is optional and specifies the location of an icon to display when presenting the identity-provider options to a user. It this is set to URL path then that path should be relative to the candid service's location. If this is not set a default generic OpenID icon will be used.

The 'keycloak-realm and client-id parameters must be specified and should be provided by the keycloak service administrator. An optional client-secret may also be required which the keycloak service administrator should provide.

When registering the application the authorized redirect URLs should include $CANDID_URL/login/keycloak/callback .

The hidden value is an optional value that can be used to not list this identity provider in the list of possible identity providers when performing an interactive login.

LDAP

- type: ldap
  name: ldap
  description: LDAP Login
  icon: /static/images/ldap-icon.bmp
  domain: example
  url: ldap://ldap.example.com/dc=example,dc=com
  ca-cert: |
    -----BEGIN CERTIFICATE-----
    MIIBWTCCAQOgAwIBAgIBADANBgkqhkiG9w0BAQsFADAbMRkwFwYDVQQDExBsZGFw
    LmV4YW1wbGUuY29tMB4XDTE4MDQxODEwMDUzMVoXDTI4MDQyMDEwMDUzMVowGzEZ
    MBcGA1UEAxMQbGRhcC5leGFtcGxlLmNvbTBcMA0GCSqGSIb3DQEBAQUAA0sAMEgC
    QQDN2tltcVwW0bs80ABocjSZrqBDnpuxnzq2DlrLL+hldwDxVZ0sqU+o768GB6bP
    8k3WVf81yYBRbfq7pD/MX0BhAgMBAAGjMjAwMA8GA1UdEwEB/wQFMAMBAf8wHQYD
    VR0OBBYEFEMAeAXsITzTXHDfJSzrezBkaSvwMA0GCSqGSIb3DQEBCwUAA0EAw6Rh
    RlR4L5mvvDaN4NP/aNOaWGe+x1Oa7V3L75MmD3DbwcUgDCn45EaUGofbOTrbYuzm
    mrVoMF002dpQoqc38w==
    -----END CERTIFICATE-----
  dn: cn=candid,dc=example,dc=com
  password: 6IaWWtW/aTN0CIVYwLgeOayyZW8o
  user-query-filter: (objectClass=account)
  user-query-attrs:
    id: uid
    email: mail
    display-name: displayName
  group-query-filter: (&(objectClass=groupOfNames)(member={{.User}}))
  hidden: false
  require-mfa: true

The LDAP identity provider allows a user to login using an LDAP server. Candid will prompt for a username and password and attempt to use those to authenticate with the LDAP server.

name is the name to use for the LDAP IDP instance. It is possible to configure more than one LDAP IDP on a given candid server and this allows them to be identified. The name will be used in the login URL.

description (optional) provides a human readable description of the identity provider. If it is not set it will default to the value of name .

icon (optional) specifies the location of an icon to display when presenting the identity-provider options to a user. It this is set to URL path then that path should be relative to the candid service's location. If this is not set a default generic LDAP icon will be used.

domain (optional) is the domain in which all identities will be created. If this is not set then no domain is used.

url contains the URL of the LDAP server being authenticated against. The path component of the URL is used as the base DN for the connection.

ca-cert (optional) contains the CA certificate that signed the LDAPs server certificate. If this is not set then the connection either has to be unauthenticated or the CA certificate has to be in the system's certificate pool.

dn (optional) contains the distinguished name that candid uses to bind to the LDAP server to perform searches. If this is not configured then candid binds anonymously and password is ignored.

password (optional) contains the password used when candid binds to the LDAP server.

user-query-filter contains the filter that candid uses when attempting to find the user that is authenticating.

user-query-attrs contains the attributes candid uses when searching for authenticating users. When authenticating a user candid will perform a search like ($id=$username) where the value of $id is specified in the id parameter and $username is the value entered by the authenticating user. email and display-name are used to populate the created identity.

group-query-filter contains the filter candid uses when finding group memberships for a user. The filter is specified as a template (see https://golang.org/pkg/text/template) where the value of . User

will be replaced with the DN of the user for whom candid is attempting to find group memberships.

The hidden value is an optional value that can be used to not list this identity provider in the list of possible identity providers when performing an interactive login.

If require-mfa is set to true candid will require users to present valid MFA credentials when logging in.

Static Identity Provider

- type: static
  name: static
  domain: mydomain
  description: Static Identity Provider
  icon: /static/images/static-icon.bmp
  users:
    user1:
      name: User One
      email: user1@example.com
      password: password1
      groups: [group1, group2]
    user2:
      name: User Two
      email: user2@example.com
      password: password2
      groups: [group3, group4]
  hidden: false
  match-email-addr: @example.com$
  require-mfa: true

The static identity provider is meant for testing and allows defining a set of users that can authenticate, along with their passwords and a list of groups they are part of.

Note that this provider is not meant for production use as it's insecure.

name is the name to use for the LDAP IDP instance. It is possible to configure more than one LDAP IDP on a given candid server and this allows them to be identified. The name will be used in the login URL.

domain (optional) is the domain in which all identities will be created. If this is not set then no domain is used.

description (optional) provides a human readable description of the identity provider. If it is not set it will default to the value of name .

icon (optional) specifies the location of an icon to display when presenting the identity-provider options to a user. It this is set to URL path then that path should be relative to the candid service's location. If this is not set a default icon will be used.

users contains a static mapping of username to user entries for all of the users defined by the identity provider.

The hidden value is an optional value that can be used to not list this identity provider in the list of possible identity providers when performing an interactive login.

The match-email-addr value is a regular expression that can be used to select the identity provider using an email address. If configured when a user attempts to login via an email address the address will be checked against the regular expression and if they match the identity provider will be used to perform the login.

If require-mfa is set to true candid will require users to present valid MFA credentials when loggin in.

Charm Configuration

If the candid charm is being used then most of the parameters will be set with sensible defaults.

The charm parameters that must be configured for each deployment are:

  • password
  • private-key
  • public-key
  • location

Most deployments will probably also want to configure the identity-providers unless the default ones are being used.