This page was saved using WebZIP 7.1.2.1052 offline browser on 04/26/18 10:45:53.
Address: https://apereo.github.io/cas/5.2.x/installation/Configuration-Server-Management.html
Title: CAS - Configuration Server  •  Size: 43414  •  Last Modified: Mon, 23 Apr 2018 19:41:07 GMT

Enterprise Single Sign-On for All

配置服务器

当您的CAS部署从开发到测试,最后转移到生产环境时,您需要管理这些环境之间的配置。当您的项目使用了Spring Cloud项目下的配置服务器时,您的应用程序将会有他们需要运行所有的配置。作为一种替代方案,您可以决定仅以独立模式运行CAS,这种方式简单,而不需要进行外部配置服务器部署,但代价是丧失与云部署相关的功能。

配置文件

CAS服务器Web应用程序可按照如下的策略配置

独立运行

这是默认配置模式,CAS不需要连接到外部配置服务器,并且将以嵌入式的方式独立模式运行。 启用此选项时,默认情况下,CAS将尝试查找设置名称cas.standalone.config下指定的给定目录内的设置和属性,如果找不到,将回到使用/etc/cas/config作为配置目录。 您可以通过此处列出的方法来配置CAS的设置。 还有一个cas.standalone.config.file来确定CAS配置的文件和classpath。

与Spring Cloud外部配置服务器类似,此目录的内容包括可用于设置CAS的(cas|application).(yml|properties)配置文件。 还要注意,CAS可以监视此配置目录,以便根据需要自动选择更改并刷新应用程序上下文。 请查看本指南以了解更多信息。

请注意,默认情况下,所有CAS设置和配置均通过CAS服务器Web应用程序中的application.properties文件进行控制。如果您希望在CAS的Web应用程序内配置,而不依赖外部配置文件,还有一个嵌入式application.yml文件可设置,该文件允许您覆盖所有默认值,

在外部配置文件中,找到的设置可以覆盖CAS提供的默认设置。 CAS配置目录内的配置文件的命名遵循以下模式:

  • 如果存在application.(properties|yml)文件,则加载该文件。
  • 如果properties|yml文件中有配置与spring.application.name一样的,则加载 (比如 cas.properties)
  • 如果properties|yml文件中有配置与spring.profiles.active一样的,则加载 (比如 ldap.properties)
  • 打包的Web应用程序之外的特定于配置文件(application-{profile}.properties|yml)如果需要,您可以将设置拆分为多个属性文件,然后通过将其名称分配(比如spring.profiles.active=standalone,testldap,stagingMfa
请记住

建议不要覆盖或修改内置的application.propertiesbootstrap.properties文件,这将导致你的系统变得复杂,以后部署造成困难。 相反,尽可能通过默认设置遵守CAS默认设置和引导程序CAS,通过覆盖application.yml文件或使用这里的策略。 同样,尝试让CAS找到自己外部的配置文件。 不成熟的优化只会导致混乱。

Spring Cloud

CAS能够使用外部和配置服务中心来获取状态和设置。 配置服务器为CAS(及其所有其他客户端)提供了一种非常抽象的方式,以从各种来源(如文件系统,gitsvn存储库,MongoDb数据库,Vault等)获取设置。 此解决方案的优点是,对于CAS Web应用服务器而言,重要的不是设置来自哪里,而是配置源头配了哪些属性。 配置服务器只要找到设置并继续执行即可。

Configuration 安全性

这是一个非常好的策略,可确保配置设置不会分散在各种部署环境中,从而实现更安全的部署。 配置服务器不需要暴露到外部,并且它可以安全隐藏在防火墙后面等,从而授权客户端只允许访问诸如CAS服务的Web应用程序。

Spring Cloud 项目提供了完整的指导手册

Overlay

配置服务器本身与CAS类似,可以通过以下模块部署在自己的WAR overlay

1
2
3
4
5
<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-webapp-config-server</artifactId>
  <version>${cas.version}</version>
</dependency>

除了这里的策略外, 配置服务器还可以通过以下顺序和机制加载CAS设置和属性:

  1. 打包的Web应用程序之外的配置文件(application-{profile}.properties|yml)
  2. 在打包的JAR文件内的的配置文件(application-{profile}.properties|yml)
  3. 打包的Web应用程序之外的application配置文件(application.properties|yml).
  4. 在打包的JAR文件之外的application配置文件(application.properties|yml).

配置服务器的配置和行为也由其自己的src/main/resources/bootstrap.properties文件控制。 默认情况下,它运行在/casconfigserver中的8888端口中,该服务是在Apache Tomcat服务器中与运行,由Tomcat的基本认证保护,默认管理的登录凭证是在src/main/resources/application.properties中定义的casuser和Mellon。 此外,默认情况下它会在下面描述的本机配置文件下运行。

Parameter Description
/encrypt POST请求,加密CAS配置文件
/decrypt POST请求,解密CAS配置文件
/refresh POST请求,重新更新配置服务器内部的状态值
/env GET请求,描述配置服务器的配置来源
/cas/default 描述配置服务器的默认配置
/cas/native 描述配置服务器的本地配置
/bus/refresh 如果cloud bus开启话,重新加载CAS集群中所有节点的配置
/bus/env 如果cloud bus开启话,发送key/value的配置键值,来更新每个CAS节点

一旦配置服务器配置部署生效,你可以通过下面的命令看到配置信息

1
curl -u casuser:Mellon http://config.server.url:8888/casconfigserver/cas/native

你也可以通过下面的方法,看到提供给配置服务器的源头配置属性

1
curl -u casuser:Mellon http://localhost:8888/casconfigserver/env

Clients and Consumers

要让CAS服务的Web应用程序(或任何其他客户端)与配置服务器通信,需要将以下设置应用于CAS自己的src/main/resources/bootstrap.properties 文件。 在启动阶段,必须先读入CAS服务的Web应用程序的配置,作为客户端的配置属性,然后才能从配置服务器读取应用程序配置的其余部分。

1
2
3
4
spring.cloud.config.uri=http://casuser:Mellon@localhost:8888/casconfigserver
spring.cloud.config.profile=native
spring.cloud.config.enabled=true
spring.profiles.active=default

请记住,配置服务器向应用程序提供来自/{name}/{profile}/{label} 的属性来源,其中客户端应用程序中的默认绑定如下所示:

1
2
3
"name" = ${spring.application.name}
"profile" = ${spring.profiles.active}
"label" = "master"

All of them can be overridden by setting spring.cloud.config.* (where * is “name”, “profile” or “label”). The “label” is useful for rolling back to previous versions of configuration; with the default Config Server implementation it can be a git label, branch name or commit id. Label can also be provided as a comma-separated list, in which case the items in the list are tried on-by-one until one succeeds. This can be useful when working on a feature branch, for instance, when you might want to align the config label with your branch, but make it optional (e.g. spring.cloud.config.label=myfeature,develop).

To lean more about CAS allows you to reload configuration changes, please review this guide.

Profiles

Various profiles exist to determine how configuration server should retrieve properties and settings.

Native

The server is configured by default to load cas.(properties|yml) files from an external location that is /etc/cas/config. This location is constantly monitored by the server to detect external changes. Note that this location simply needs to exist, and does not require any special permissions or structure. The name of the configuration file that goes inside this directory needs to match the spring.application.name (i.e. cas.properties).

If you want to use additional configuration files, they need to have the form application-<profile>.(properties|yml). A file named application.(properties|yml) will be included by default. The profile specific files can be activated by using the spring.profiles.include configuration option, controlled via the src/main/resources/bootstrap.properties file:

1
2
3
spring.profiles.active=native
spring.cloud.config.server.native.searchLocations=file:///etc/cas/config
spring.profiles.include=profile1,profile2

An example of an external .properties file hosted by an external location follows:

1
cas.server.name=...

You could have just as well used a cas.yml file to host the changes.

Default

The configuration server is also able to handle git or svn based repositories that host CAS configuration. Such repositories can either be local to the deployment, or they could be on the cloud in form of GitHub/BitBucket. Access to cloud-based repositories can either be in form of a username/password, or via SSH so as long the appropriate keys are configured in the CAS deployment environment which is really no different than how one would normally access a git repository via SSH.

1
2
3
4
5
6
7
8
9
10
11
# spring.profiles.active=default
# spring.cloud.config.server.git.uri=https://github.com/repoName/config
# spring.cloud.config.server.git.uri=file://${user.home}/config
# spring.cloud.config.server.git.username=
# spring.cloud.config.server.git.password=

# spring.cloud.config.server.svn.basedir=
# spring.cloud.config.server.svn.uri=
# spring.cloud.config.server.svn.username=
# spring.cloud.config.server.svn.password=
# spring.cloud.config.server.svn.default-label=trunk

Needless to say, the repositories could use both YAML and properties syntax to host configuration files.

Keep What You Need!

Again, in all of the above strategies, an adopter is encouraged to only keep and maintain properties needed for their particular deployment. It is UNNECESSARY to grab a copy of all CAS settings and move them to an external location. Settings that are defined by the external configuration location or repository are able to override what is provided by CAS as a default.

MongoDb

The server is also able to locate properties entirely from a MongoDb instance.

Support is provided via the following dependency in the WAR overlay:

1
2
3
4
5
<dependency>
     <groupId>org.apereo.cas</groupId>
     <artifactId>cas-server-core-configuration-cloud-mongo</artifactId>
     <version>${cas.version}</version>
</dependency>

Note that to access and review the collection of CAS properties, you will need to use the CAS administrative interfaces, or you may also use your own native tooling for MongoDB to configure and inject settings.

MongoDb documents are required to be found in the collection MongoDbProperty, as the following document:

1
2
3
4
5
{
    "id": "kfhf945jegnsd45sdg93452",
    "name": "the-setting-name",
    "value": "the-setting-value"
}

To see the relevant list of CAS properties for this feature, please review this guide.

HashiCorp Vault

CAS is also able to use Vault to locate properties and settings. Please review this guide.

Apache ZooKeeper

CAS is also able to use Apache ZooKeeper to locate properties and settings.

Support is provided via the following dependency in the WAR overlay:

1
2
3
4
5
<dependency>
     <groupId>org.apereo.cas</groupId>
     <artifactId>cas-server-core-configuration-cloud-zookeeper</artifactId>
     <version>${cas.version}</version>
</dependency>

To see the relevant list of CAS properties for this feature, please review this guide.

You will need to map CAS settings to ZooKeeper’s nodes that contain values. The parent node for all settings should match the configuration root value provided to CAS. Under the root, you could have folders such as cas, cas,dev, cas,local, etc where dev and local are Spring profiles.

To create nodes and values in Apache ZooKeeper, try the following commands as a sample:

1
2
3
4
5
zookeeper-client -server zookeeper1:2181
create /cas cas
create /cas/config cas
create /cas/config/cas cas
create /cas/config/cas/settingName casuser::Test

Creating nodes and directories in Apache ZooKeeper may require providing a value. The above sample commands show that the value cas is provided when creating directories. Always check with the official Apache ZooKeeper guides. You may not need to do that step.

Finally in your CAS properties, the new settingName setting can be used as a reference.

1
cas.something.something=${settingName}

…where ${settingName} gets the value of the contents of the Apache ZooKeeper node cas/config/cas/settingName.

DynamoDb

CAS is also able to use DynamoDb to locate properties and settings.

Support is provided via the following dependency in the WAR overlay:

1
2
3
4
5
<dependency>
     <groupId>org.apereo.cas</groupId>
     <artifactId>cas-server-core-configuration-cloud-dynamodb</artifactId>
     <version>${cas.version}</version>
</dependency>

The DynamoDbCasProperties table is automatically created by CAS with the following structure:

1
2
3
4
5
{
    "id": "primary-key",
    "name": "the-setting-name",
    "value": "the-setting-value"
}

To see the relevant list of CAS properties for this feature, please review this guide.

JDBC

CAS is also able to use a relational database to locate properties and settings.

Support is provided via the following dependency in the WAR overlay:

1
2
3
4
5
<dependency>
     <groupId>org.apereo.cas</groupId>
     <artifactId>cas-server-core-configuration-cloud-jdbc</artifactId>
     <version>${cas.version}</version>
</dependency>

By default, settings are expected to be found under a CAS_SETTINGS_TABLE that contains the fields: id, name and value. To see the relevant list of CAS properties for this feature, please review this guide.

CAS Server Cloud Configuration

The cloud configuration modules provided above on this page by the CAS project directky may also be used verbaitm inside a CAS server overlay. Remember that the primary objective for these modules is to simply retrieve settings and properties from a source. While they are mostly and primarily useful when activated inside the Spring Cloud Configuration server and can be set to honor profiles and such, they nonetheless may also be used inside a CAS server overlay directly to simply fetch settings from a source while running in standalone mode. In such scenarios, all sources of configuration regardless of format or syntax will work alongside each other to retrieve settings and you can certainly mix and match as you see fit.

Composite Sources

In some scenarios you may wish to pull configuration data from multiple environment repositories. To do this just enable multiple profiles in your configuration server’s application properties or YAML file. If, for example, you want to pull configuration data from a Git repository as well as a SVN repository you would set the following properties for your configuration server.

1
2
3
4
5
6
7
8
9
10
11
12
spring:
  profiles:
    active: git, svn
  cloud:
    config:
      server:
        svn:
          uri: file:///path/to/svn/repo
          order: 2
        git:
          uri: file:///path/to/git/repo
          order: 1

In addition to each repo specifying a URI, you can also specify an order property. The order property allows you to specify the priority order for all your repositories. The lower the numerical value of the order property the higher priority it will have. The priority order of a repository will help resolve any potential conflicts between repositories that contain values for the same properties.

Property Overrides

The configuration server has an “overrides” feature that allows the operator to provide configuration properties to all applications that cannot be accidentally changed by the application using the normal change events and hooks. To declare overrides add a map of name-value pairs to spring.cloud.config.server.overrides. For example:

1
2
3
4
5
6
spring:
  cloud:
    config:
      server:
        overrides:
          foo: bar

This will cause the CAS server (as the client of the configuration server) to read foo=bar independent of its own configuration.

Securing Settings

To learn how sensitive CAS settings can be secured via encryption, please review this guide.

Reloading Changes

To lean more about CAS allows you to reload configuration changes, please review this guide.

Clustered Deployments

CAS uses the Spring Cloud Bus to manage configuration in a distributed deployment. Spring Cloud Bus links nodes of a distributed system with a lightweight message broker. This can then be used to broadcast state changes (e.g. configuration changes) or other management instructions.

To learn how sensitive CAS settings can be secured via encryption, please review this guide.