Polish documentation
This commit is contained in:
Phillip Webb
parent
25f74cbaef
commit
c7677d10ca
|
|
@ -4,7 +4,7 @@
|
|||
[partintro]
|
||||
--
|
||||
If you're just getting started with Spring Boot, or 'Spring' in general, this is the section
|
||||
for you! Here we answer the basic '"`what?`"', '"`how?`"' and '"`why?`"' questions. You'll
|
||||
for you! Here we answer the basic "`what?`", "`how?`" and "`why?`" questions. You'll
|
||||
find a gentle introduction to Spring Boot along with installation instructions.
|
||||
We'll then build our first Spring Boot application, discussing some core principles as
|
||||
we go.
|
||||
|
|
@ -524,7 +524,7 @@ endif::[]
|
|||
----
|
||||
|
||||
This should give you a working build, you can test it out by running `mvn package` (you
|
||||
can ignore the "`jar will be empty - no content was marked for inclusion!'`" warning for
|
||||
can ignore the "`jar will be empty - no content was marked for inclusion!`" warning for
|
||||
now).
|
||||
|
||||
NOTE: At this point you could import the project into an IDE (most modern Java IDE's
|
||||
|
|
|
|||
|
|
@ -964,10 +964,10 @@ the metrics are exported to a Redis cache for aggregation. The `RedisMetricRepos
|
|||
two important parameters to configure it for this purpose: `prefix` and `key` (passed into
|
||||
its constructor). It is best to use a prefix that is unique to the application instance
|
||||
(e.g. using a random value and maybe the logical name of the application to make it
|
||||
possible to correlate with other instances of the same application). The "key" is used to
|
||||
keep a global index of all metric names, so it should be unique "globally", whatever that
|
||||
means for your system (e.g. 2 instances of the same system could share a Redis cache if
|
||||
they have distinct keys).
|
||||
possible to correlate with other instances of the same application). The "`key`" is used
|
||||
to keep a global index of all metric names, so it should be unique "`globally`", whatever
|
||||
that means for your system (e.g. two instances of the same system could share a Redis cache
|
||||
if they have distinct keys).
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -991,33 +991,33 @@ spring.metrics.export.redis.key: keys.metrics.mysystem
|
|||
The prefix is constructed with the application name and id at the end, so it can easily be used
|
||||
to identify a group of processes with the same logical name later.
|
||||
|
||||
NOTE: it's important to set both the key and the prefix. The key is used for all
|
||||
NOTE: It's important to set both the `key` and the `prefix`. The key is used for all
|
||||
repository operations, and can be shared by multiple repositories. If multiple
|
||||
repositories share a key (like in the case where you need to aggregate across them), then
|
||||
you normally have a read-only "master" repository that has a short, but identifiable,
|
||||
prefix (like "metrics.mysystem"), and many write-only repositories with prefixes that
|
||||
you normally have a read-only "`master`" repository that has a short, but identifiable,
|
||||
prefix (like "`metrics.mysystem`"), and many write-only repositories with prefixes that
|
||||
start with the master prefix (like `metrics.mysystem.*` in the example above). It is
|
||||
efficient to read all the keys from a "master" repository like that, but inefficient to
|
||||
efficient to read all the keys from a "`master`" repository like that, but inefficient to
|
||||
read a subset with a longer prefix (e.g. using one of the writing repositories).
|
||||
|
||||
NOTE: the example above uses `MetricExportProperties` to inject and extract the key and
|
||||
prefix. This is provided to you as a convenience by Spring Boot, and the defaults for that
|
||||
will be sensible, but there is nothing to stop you using your own values as long as they
|
||||
follow the recommendations.
|
||||
TIP: The example above uses `MetricExportProperties` to inject and extract the key and
|
||||
prefix. This is provided to you as a convenience by Spring Boot, configured with sensible
|
||||
defaults. There is nothing to stop you using your own values as long as they follow the
|
||||
recommendations.
|
||||
|
||||
|
||||
|
||||
[[production-ready-metric-writers-export-to-open-tdsb]]
|
||||
==== Example: Export to Open TSDB
|
||||
If you provide a `@Bean` of type `OpenTsdbHttpMetricWriter` and mark it
|
||||
`@ExportMetricWriter` the metrics are exported to http://opentsdb.net/[Open TSDB] for
|
||||
`@ExportMetricWriter` metrics are exported to http://opentsdb.net/[Open TSDB] for
|
||||
aggregation. The `OpenTsdbHttpMetricWriter` has a `url` property that you need to set
|
||||
to the Open TSDB "/put" endpoint, e.g. `http://localhost:4242/api/put`). It also has a
|
||||
to the Open TSDB "`/put`" endpoint, e.g. `http://localhost:4242/api/put`). It also has a
|
||||
`namingStrategy` that you can customize or configure to make the metrics match the data
|
||||
structure you need on the server. By default it just passes through the metric name as an
|
||||
Open TSDB metric name and adds a tag "domain" with value "org.springframework.metrics" and
|
||||
another tag "process" with value equals to the object hash of the naming strategy. Thus,
|
||||
after running the application and generating some metrics (e.g. by pinging the home page)
|
||||
Open TSDB metric name, and adds the tags "`domain`" (with value
|
||||
"`org.springframework.metrics`") and "`process`" (with the value equal to the object hash
|
||||
of the naming strategy). Thus, after running the application and generating some metrics
|
||||
you can inspect the metrics in the TDB UI (http://localhost:4242 by default).
|
||||
|
||||
Example:
|
||||
|
|
@ -1072,7 +1072,9 @@ MetricWriter metricWriter() {
|
|||
If you provide a `@Bean` of type `JmxMetricWriter` marked `@ExportMetricWriter` the metrics are exported as MBeans to
|
||||
the local server (the `MBeanExporter` is provided by Spring Boot JMX autoconfiguration as
|
||||
long as it is switched on). Metrics can then be inspected, graphed, alerted etc. using any
|
||||
tool that understands JMX (e.g. JConsole or JVisualVM). Example:
|
||||
tool that understands JMX (e.g. JConsole or JVisualVM).
|
||||
|
||||
Example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
|
|
@ -1098,10 +1100,12 @@ period-separated prefix, and the reader will aggregate (by truncating the metric
|
|||
and dropping the prefix). Counters are summed and everything else (i.e. gauges) take their
|
||||
most recent value.
|
||||
|
||||
This is very useful (for instance) if multiple application instances are feeding to a
|
||||
central (e.g. redis) repository and you want to display the results. Particularly
|
||||
recommended in conjunction with a `MetricReaderPublicMetrics` for hooking up to the
|
||||
results to the "/metrics" endpoint. Example:
|
||||
This is very useful if multiple application instances are feeding to a central (e.g.
|
||||
Redis) repository and you want to display the results. Particularly recommended in
|
||||
conjunction with a `MetricReaderPublicMetrics` for hooking up to the results to the
|
||||
"`/metrics`" endpoint.
|
||||
|
||||
Example:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
|
|
@ -1125,17 +1129,17 @@ results to the "/metrics" endpoint. Example:
|
|||
}
|
||||
----
|
||||
|
||||
NOTE: the example above uses `MetricExportProperties` to inject and
|
||||
extract the key and prefix. This is provided to you as a convenience
|
||||
by Spring Boot, and the defaults will be sensible. They are set up in
|
||||
`MetricExportAutoConfiguration`.
|
||||
NOTE: The example above uses `MetricExportProperties` to inject and extract the key and
|
||||
prefix. This is provided to you as a convenience by Spring Boot, and the defaults will be
|
||||
sensible. They are set up in `MetricExportAutoConfiguration`.
|
||||
|
||||
NOTE: the `MetricReaders` above are not `@Beans` and are not marked as
|
||||
`@ExportMetricReader` because they are just collecting and analysing
|
||||
data from other repositories, and don't want to export their values.
|
||||
NOTE: The `MetricReaders` above are not `@Beans` and are not marked as
|
||||
`@ExportMetricReader` because they are just collecting and analyzing data from other
|
||||
repositories, and don't want to export their values.
|
||||
|
||||
|
||||
|
||||
[[production-ready-code-hale-metrics]]
|
||||
[[production-ready-dropwizard-metrics]]
|
||||
=== Dropwizard Metrics
|
||||
A default `MetricRegistry` Spring bean will be created when you declare a dependency to
|
||||
|
|
@ -1149,7 +1153,7 @@ endpoint
|
|||
When Dropwizard metrics are in use, the default `CounterService` and `GaugeService` are
|
||||
replaced with a `DropwizardMetricServices`, which is a wrapper around the `MetricRegistry`
|
||||
(so you can `@Autowired` one of those services and use it as normal). You can also create
|
||||
"special" Dropwizard metrics by prefixing your metric names with the appropriate type
|
||||
"`special`" Dropwizard metrics by prefixing your metric names with the appropriate type
|
||||
(i.e. `+timer.*+`, `+histogram.*+` for gauges, and `+meter.*+` for counters).
|
||||
|
||||
|
||||
|
|
@ -1185,7 +1189,7 @@ and obtain basic information about the last few requests:
|
|||
|
||||
[source,json,indent=0]
|
||||
----
|
||||
[{
|
||||
[{
|
||||
"timestamp": 1394343677415,
|
||||
"info": {
|
||||
"method": "GET",
|
||||
|
|
@ -1253,9 +1257,9 @@ In `META-INF/spring.factories` file you have to activate the listener(s):
|
|||
|
||||
[indent=0]
|
||||
----
|
||||
org.springframework.context.ApplicationListener=\
|
||||
org.springframework.boot.actuate.system.ApplicationPidFileWriter,
|
||||
org.springframework.boot.actuate.system.EmbeddedServerPortFileWriter
|
||||
org.springframework.context.ApplicationListener=\
|
||||
org.springframework.boot.actuate.system.ApplicationPidFileWriter,
|
||||
org.springframework.boot.actuate.system.EmbeddedServerPortFileWriter
|
||||
----
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1464,208 +1464,192 @@ features add a `@Bean` of type `WebSecurityConfigurerAdapter` with
|
|||
|
||||
|
||||
|
||||
[[boot-features-security-oauth2]]
|
||||
=== OAuth2
|
||||
If you have `spring-security-oauth2` on your classpath you can take advantage of some
|
||||
autoconfiguration to make it easy to set up Authorization or Resource Server features by
|
||||
configuring some property values in the `Environment`.
|
||||
auto-configuration to make it easy to set up Authorization or Resource Server.
|
||||
|
||||
|
||||
|
||||
[[boot-features-security-oauth2-authorization-server]]
|
||||
==== Authorization Server
|
||||
To create an Authorization Server and grant access tokens you need to
|
||||
`@EnableAuthorizationServer` and provide
|
||||
`spring.oauth2.client.[clientId,clientSecret]`. The client will be
|
||||
registered for you in an in-memory repository. Having done that you
|
||||
will be able to use the client credentials to create an access token,
|
||||
e.g.
|
||||
To create an Authorization Server and grant access tokens you need to use
|
||||
`@EnableAuthorizationServer` and provide `spring.oauth2.client.client-id` and
|
||||
`spring.oauth2.client.client-secret]` properties. The client will be registered for you
|
||||
in an in-memory repository.
|
||||
|
||||
Having done that you will be able to use the client credentials to create an access token,
|
||||
for example:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ curl client:secret@localhost:8080/oauth/token -d grant_type=password -d username=user -d password=pwd
|
||||
$ curl client:secret@localhost:8080/oauth/token -d grant_type=password -d username=user -d password=pwd
|
||||
----
|
||||
|
||||
The basic auth credentials for the `/token` endpoint are the client id
|
||||
and secret, and the user credentials are the normal Spring Security
|
||||
user details (which default in Spring Boot to "user" and a random
|
||||
password).
|
||||
The basic auth credentials for the `/token` endpoint are the `client-id` and
|
||||
`client-secret`. The user credentials are the normal Spring Security user details (which
|
||||
default in Spring Boot to "`user`" and a random password).
|
||||
|
||||
To switch off the autoconfiguration and configure the Authorization
|
||||
Server features yourself just add a `@Bean` of type
|
||||
`AuthorizationServerConfigurer`.
|
||||
To switch off the auto-configuration and configure the Authorization Server features
|
||||
yourself just add a `@Bean` of type `AuthorizationServerConfigurer`.
|
||||
|
||||
|
||||
|
||||
[[boot-features-security-oauth2-resource-server]]
|
||||
==== Resource Server
|
||||
To use the access token you need a Resource Server (which can be the
|
||||
same as the Authorization Server). Creating a Resource Server is easy:
|
||||
just add `@EnableResourceServer` and provide some configuration to
|
||||
allow the server to decode access tokens. If your app is also an
|
||||
Authorization Server it already knows how to decode tokens, so there
|
||||
is nothing else to do. If your app is a standalone service then you
|
||||
need to give it some more configuration. Here are the options, one of
|
||||
the following:
|
||||
To use the access token you need a Resource Server (which can be the same as the
|
||||
Authorization Server). Creating a Resource Server is easy, just add
|
||||
`@EnableResourceServer` and provide some configuration to allow the server to decode
|
||||
access tokens. If your appplication is also an Authorization Server it already knows how
|
||||
to decode tokens, so there is nothing else to do. If your app is a standalone service then you
|
||||
need to give it some more configuration, one of the following options:
|
||||
|
||||
* `spring.oauth2.resource.userInfoUri` to use the "/me" resource
|
||||
(e.g. "https://uaa.run.pivotal.io/userinfo" on PWS), or
|
||||
* `spring.oauth2.resource.user-info-uri` to use the "/me" resource (e.g.
|
||||
"`https://uaa.run.pivotal.io/userinfo`" on PWS)
|
||||
|
||||
* `spring.oauth2.resource.tokenInfoUri` to use the token decoding endpoint
|
||||
(e.g. "https://uaa.run.pivotal.io/check_token" on PWS).
|
||||
* `spring.oauth2.resource.token-info-uri` to use the token decoding endpoint (e.g.
|
||||
"`https://uaa.run.pivotal.io/check_token`" on PWS).
|
||||
|
||||
If you specify both the `userInfoUri` and the `tokenInfoUri` then
|
||||
you can set a flag to say that one is preferred over the other
|
||||
(`preferTokenInfo=true` is the default).
|
||||
If you specify both the `user-info-uri` and the `token-info-uri` then you can set a flag
|
||||
to say that one is preferred over the other (`prefer-token-info=true` is the default).
|
||||
|
||||
Alternatively (instead of `userInfoUri` or `tokenInfoUri`) if the
|
||||
tokens are JWTs you can configure a
|
||||
`spring.oauth2.resource.jwt.keyValue` to decode them locally,
|
||||
where the key is a verification key. The verification key value is
|
||||
either a symmetric secret or PEM-encoded RSA public key. If you don't
|
||||
have the key and it's public you can provide a URI where it can be
|
||||
downloaded (as a JSON object with a "value" field) with
|
||||
`spring.oauth2.resource.jwt.keyUri`. E.g. on PWS:
|
||||
Alternatively (instead of `user-info-uri` or `token-info-uri`) if the tokens are JWTs you
|
||||
can configure a `spring.oauth2.resource.jwt.key-value` to decode them locally (where the
|
||||
key is a verification key). The verification key value is either a symmetric secret or
|
||||
PEM-encoded RSA public key. If you don't have the key and it's public you can provide a
|
||||
URI where it can be downloaded (as a JSON object with a "`value`" field) with
|
||||
`spring.oauth2.resource.jwt.key-uri`. E.g. on PWS:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ curl https://uaa.run.pivotal.io/token_key
|
||||
{"alg":"SHA256withRSA","value":"-----BEGIN PUBLIC KEY-----\nMIIBI...\n-----END PUBLIC KEY-----\n"}
|
||||
$ curl https://uaa.run.pivotal.io/token_key
|
||||
{"alg":"SHA256withRSA","value":"-----BEGIN PUBLIC KEY-----\nMIIBI...\n-----END PUBLIC KEY-----\n"}
|
||||
----
|
||||
|
||||
WARNING: If you use the `spring.oauth2.resource.jwt.keyUri` the
|
||||
authorization server needs to be running when your application starts
|
||||
up. It will log a warning if it can't find the key, and tell you what
|
||||
to do to fix it.
|
||||
WARNING: If you use the `spring.oauth2.resource.jwt.key-uri` the authorization server
|
||||
needs to be running when your application starts up. It will log a warning if it can't
|
||||
find the key, and tell you what to do to fix it.
|
||||
|
||||
|
||||
|
||||
[[boot-features-security-oauth2-token-type]]
|
||||
=== Token Type in User Info
|
||||
Google (and certain other 3rd party identity providers) is more strict
|
||||
about the token type name that is sent in the headers to the user info
|
||||
endpoint. The default is "Bearer" which suits most providers and
|
||||
matches the spec, but if you need to change it you can set
|
||||
`spring.oauth2.resource.tokenType`.
|
||||
Google, and certain other 3rd party identity providers, are more strict about the token
|
||||
type name that is sent in the headers to the user info endpoint. The default is "`Bearer`"
|
||||
which suits most providers and matches the spec, but if you need to change it you can set
|
||||
`spring.oauth2.resource.token-type`.
|
||||
|
||||
|
||||
|
||||
[[boot-features-security-custom-user-info]]
|
||||
=== Customizing the User Info RestTemplate
|
||||
If you have a `userInfoUri`, the Resource Server features use an
|
||||
`OAuth2RestTemplate` internally to fetch user details for
|
||||
authentication. This is provided as a qualified `@Bean` with id
|
||||
"userInfoRestTemplate", but you shouldn't need to know that to just
|
||||
use it. The default should be fine for most providers, but
|
||||
occasionally you might need to add additional interceptors, or change
|
||||
the request authenticator (which is how the token gets attached to
|
||||
outgoing requests). To add a customization just create a bean of type
|
||||
`UserInfoRestTemplateCustomizer` - it has a single method that will be
|
||||
called after the bean is created but before it is initialized. The
|
||||
rest template that is being customized here is _only_ used internally
|
||||
to carry out authentication.
|
||||
If you have a `user-info-uri`, the resource server features use an `OAuth2RestTemplate`
|
||||
internally to fetch user details for authentication. This is provided as a qualified
|
||||
`@Bean` with id `userInfoRestTemplate`, but you shouldn't need to know that to just
|
||||
use it. The default should be fine for most providers, but occasionally you might need to
|
||||
add additional interceptors, or change the request authenticator (which is how the token
|
||||
gets attached to outgoing requests). To add a customization just create a bean of type
|
||||
`UserInfoRestTemplateCustomizer` - it has a single method that will be called after the
|
||||
bean is created but before it is initialized. The rest template that is being customized
|
||||
here is _only_ used internally to carry out authentication.
|
||||
|
||||
[TIP]
|
||||
====
|
||||
To set an RSA key value in YAML use the "pipe" continuation
|
||||
marker to split it over multiple lines ("|") and remember to indent
|
||||
the key value (it's a standard YAML language feature). Example:
|
||||
To set an RSA key value in YAML use the "`pipe`" continuation marker to split it over
|
||||
multiple lines ("`|`") and remember to indent the key value (it's a standard YAML
|
||||
language feature). Example:
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
oauth2:
|
||||
resource:
|
||||
jwt:
|
||||
keyValue: |
|
||||
-----BEGIN PUBLIC KEY-----
|
||||
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC...
|
||||
-----END PUBLIC KEY-----
|
||||
oauth2:
|
||||
resource:
|
||||
jwt:
|
||||
keyValue: |
|
||||
-----BEGIN PUBLIC KEY-----
|
||||
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC...
|
||||
-----END PUBLIC KEY-----
|
||||
----
|
||||
====
|
||||
|
||||
|
||||
|
||||
[[boot-features-security-custom-user-info-client]]
|
||||
==== Client
|
||||
To make your webapp into an OAuth2 client you can simply
|
||||
`@EnableOAuth2Client` and Spring Boot will create an
|
||||
`OAuth2RestTemplate` for you to autowire. It uses the
|
||||
`spring.oauth2.client.*` as credentials (the same as you might be
|
||||
using in the Authorization Server), but in addition it will need to
|
||||
know the authorization and token URIs in the Authorization Server. For
|
||||
example:
|
||||
To make your webapp into an OAuth2 client you can simply add `@EnableOAuth2Client` and
|
||||
Spring Boot will create an `OAuth2RestTemplate` for you to `@Autowire`. It uses the
|
||||
`spring.oauth2.client.*` as credentials (the same as you might be using in the
|
||||
Authorization Server), but in addition it will need to know the authorization and token
|
||||
URIs in the Authorization Server. For example:
|
||||
|
||||
.application.yml
|
||||
[source,yaml]
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
spring:
|
||||
oauth2:
|
||||
client:
|
||||
clientId: bd1c0a783ccdd1c9b9e4
|
||||
clientSecret: 1a9030fbca47a5b2c28e92f19050bb77824b5ad1
|
||||
accessTokenUri: https://github.com/login/oauth/access_token
|
||||
userAuthorizationUri: https://github.com/login/oauth/authorize
|
||||
clientAuthenticationScheme: form
|
||||
oauth2:
|
||||
client:
|
||||
clientId: bd1c0a783ccdd1c9b9e4
|
||||
clientSecret: 1a9030fbca47a5b2c28e92f19050bb77824b5ad1
|
||||
accessTokenUri: https://github.com/login/oauth/access_token
|
||||
userAuthorizationUri: https://github.com/login/oauth/authorize
|
||||
clientAuthenticationScheme: form
|
||||
----
|
||||
|
||||
An app with this configuration will redirect to github for
|
||||
authorization if you attempt to use the `OAuth2RestTemplate`. If you
|
||||
are already signed into github you won't even notice that it has
|
||||
authenticated. These specific credentials will only work if your app
|
||||
is running on port 8080 (register your own client app in Github or
|
||||
other provider for more flexibility).
|
||||
An application with this configuration will redirect to Github for authorization when you
|
||||
attempt to use the `OAuth2RestTemplate`. If you are already signed into Github you won't
|
||||
even notice that it has authenticated. These specific credentials will only work if your
|
||||
application is running on port 8080 (register your own client app in Github or other
|
||||
provider for more flexibility).
|
||||
|
||||
To limit the scope that the client asks for when it obtains an access token
|
||||
you can set `spring.oauth2.client.scope` (comma separated or an array in YAML). By
|
||||
default the scope is empty and it is up to to Authorization Server to
|
||||
decide what the defaults should be, usually depending on the settings in
|
||||
the client registration that it holds.
|
||||
To limit the scope that the client asks for when it obtains an access token you can set
|
||||
`spring.oauth2.client.scope` (comma separated or an array in YAML). By default the scope
|
||||
is empty and it is up to to Authorization Server to decide what the defaults should be,
|
||||
usually depending on the settings in the client registration that it holds.
|
||||
|
||||
NOTE: There is also a setting for
|
||||
`spring.oauth2.client.clientAuthenticationScheme` which defaults to
|
||||
"header" (but you might need to set it to "form" if, like Github for
|
||||
instance, your OAuth2 provider doesn't like header authentication). In
|
||||
fact, the `spring.oauth2.client.*` properties are bound to an instance
|
||||
of `AuthorizationCodeResourceDetails` so all its properties can be
|
||||
specified.
|
||||
NOTE: There is also a setting for `spring.oauth2.client.client-authentication-scheme`
|
||||
which defaults to "`header`" (but you might need to set it to "`form`" if, like Github for
|
||||
instance, your OAuth2 provider doesn't like header authentication). In fact, the
|
||||
`spring.oauth2.client.*` properties are bound to an instance of
|
||||
`AuthorizationCodeResourceDetails` so all its properties can be specified.
|
||||
|
||||
TIP: In a non-web application you can still `@Autowired` an
|
||||
`OAuth2RestOperations` and it is still wired into the
|
||||
`spring.oauth2.client.*` configuration, but in this case it is a
|
||||
client credentials token grant you will be asking for if you use it
|
||||
(and there is no need to use `@EnableOAuth2Client` or
|
||||
`@EnableOAuth2Sso`). To switch it off, just remove the
|
||||
`spring.oauth2.client.clientId` from your configuration (or make it
|
||||
the empty string).
|
||||
TIP: In a non-web application you can still `@Autowire` an `OAuth2RestOperations` and it
|
||||
is still wired into the `spring.oauth2.client.*` configuration. In this case it is a
|
||||
"`client credentials token grant`" you will be asking for if you use it (and there is no
|
||||
need to use `@EnableOAuth2Client` or `@EnableOAuth2Sso`). To switch it off, just remove
|
||||
the `spring.oauth2.client.client-id` from your configuration (or make it the empty
|
||||
string).
|
||||
|
||||
|
||||
|
||||
[[boot-features-security-oauth2-single-sign-on]]
|
||||
==== Single Sign On
|
||||
An OAuth2 Client can be used to fetch user details from the provider
|
||||
if such features are provided (e.g. by using the `userInfoUri` that
|
||||
the Resource Server supports as above), and then the user details can
|
||||
be converted to an `Authentication` token for Spring Security. This is
|
||||
the basis for a Single Sign On (SSO) protocol based on OAuth2, and
|
||||
Spring Boot makes it easy to participate by providing an annotation
|
||||
`@EnableOAuth2Sso`. The Github client above can protect all its
|
||||
resources and authenticate using the Github `/user/` endpoint, by
|
||||
adding that annotation and declaring where to find the endpoint (in
|
||||
addition to the `spring.oauth2.client.*` configuration already listed
|
||||
above):
|
||||
An OAuth2 Client can be used to fetch user details from the provider (if such features are
|
||||
available) and then convert them into an `Authentication` token for Spring Security.
|
||||
The Resource Server above support this via the `user-info-uri` property This is the basis
|
||||
for a Single Sign On (SSO) protocol based on OAuth2, and Spring Boot makes it easy to
|
||||
participate by providing an annotation `@EnableOAuth2Sso`. The Github client above can
|
||||
protect all its resources and authenticate using the Github `/user/` endpoint, by adding
|
||||
that annotation and declaring where to find the endpoint (in addition to the
|
||||
`spring.oauth2.client.*` configuration already listed above):
|
||||
|
||||
.application.yml
|
||||
[source,yaml]
|
||||
[source,yaml,indent=0]]
|
||||
----
|
||||
spring:
|
||||
oauth2:
|
||||
...
|
||||
resource:
|
||||
userInfoUri: https://api.github.com/user
|
||||
preferTokenInfo: false
|
||||
spring:
|
||||
oauth2:
|
||||
...
|
||||
resource:
|
||||
userInfoUri: https://api.github.com/user
|
||||
preferTokenInfo: false
|
||||
----
|
||||
|
||||
Since all paths are secure by default, there is no "home" page that
|
||||
you can show to unauthenticated users and invite them to login (by
|
||||
visiting the `/login` path, or the path specified by
|
||||
`spring.oauth2.sso.loginPath`).
|
||||
Since all paths are secure by default, there is no "`home`" page that you can show to
|
||||
unauthenticated users and invite them to login (by visiting the `/login` path, or the
|
||||
path specified by `spring.oauth2.sso.login-path`).
|
||||
|
||||
To customize the access rules or paths to protect, so you can add a
|
||||
"home" page for instance, `@EnableOAuth2Sso` can be added to a
|
||||
`WebSecurityConfigurerAdapter` and the annotation will cause it to be
|
||||
decorated and enhanced with the necessary pieces to get the `/login`
|
||||
path working. For example, here we simply allow unauthenticated access
|
||||
To customize the access rules or paths to protect, so you can add a "`home`" page for
|
||||
instance, `@EnableOAuth2Sso` can be added to a `WebSecurityConfigurerAdapter` and the
|
||||
annotation will cause it to be decorated and enhanced with the necessary pieces to get
|
||||
the `/login` path working. For example, here we simply allow unauthenticated access
|
||||
to the home page at "/" and keep the default for everything else:
|
||||
|
||||
[source,java,indent=0]
|
||||
|
|
@ -1688,6 +1672,7 @@ to the home page at "/" and keep the default for everything else:
|
|||
|
||||
|
||||
|
||||
[[boot-features-security-actuator]]
|
||||
=== Actuator Security
|
||||
If the Actuator is also in use, you will find:
|
||||
|
||||
|
|
@ -2301,12 +2286,13 @@ TIP: For complete details of Spring Data Elasticsearch, refer to their
|
|||
http://docs.spring.io/spring-data/elasticsearch/docs/[reference documentation].
|
||||
|
||||
|
||||
|
||||
[[boot-features-caching]]
|
||||
== Caching
|
||||
The Spring Framework provides support for transparently adding caching into an
|
||||
application. At its core, the abstraction applies caching to methods, reducing thus the
|
||||
number of executions based on the information available in the cache. The caching logic
|
||||
is applied transparently without any interference to the invoker.
|
||||
The Spring Framework provides support for transparently adding caching to an application.
|
||||
At its core, the abstraction applies caching to methods, reducing thus the number of
|
||||
executions based on the information available in the cache. The caching logic is applied
|
||||
transparently, without any interference to the invoker.
|
||||
|
||||
NOTE: Check the {spring-reference}/#cache[relevant section] of the Spring Framework
|
||||
reference for more details.
|
||||
|
|
@ -2324,7 +2310,9 @@ relevant annotation to its method:
|
|||
public class MathService {
|
||||
|
||||
@CacheResult
|
||||
public int computePiDecimal(int i) { ... }
|
||||
public int computePiDecimal(int i) {
|
||||
// ...
|
||||
}
|
||||
|
||||
}
|
||||
----
|
||||
|
|
@ -2339,16 +2327,17 @@ TIP: It is also possible to {spring-reference}/#cache-annotations-put[update] or
|
|||
|
||||
|
||||
=== Supported cache providers
|
||||
NOTE: To easily get started, just add `spring-boot-starter-cache` to the dependencies of
|
||||
your application.
|
||||
|
||||
The cache abstraction does not provide an actual store and relies on a abstraction
|
||||
materialized by the `org.springframework.cache.Cache` and
|
||||
`org.springframework.cache.CacheManager` interfaces. Spring Boot auto-configures a
|
||||
suitable `CacheManager` according to the implementation as long as the caching support is
|
||||
enabled via the `@EnableCaching` annotation.
|
||||
|
||||
Spring Boot tries to detect the following providers (in that order):
|
||||
TIP: Use the `spring-boot-starter-cache` "`Starter POM`" to quickly add required caching
|
||||
dependencies. If you are adding dependencies manually you should note that certain
|
||||
implementations are only provided by the `spring-context-support` jar.
|
||||
|
||||
Spring Boot tries to detect the following providers (in this order):
|
||||
|
||||
* <<boot-features-caching-provider-generic,Generic>>
|
||||
* <<boot-features-caching-provider-ehcache2,EhCache 2.x>>
|
||||
|
|
@ -2366,38 +2355,40 @@ property.
|
|||
|
||||
[[boot-features-caching-provider-generic]]
|
||||
==== Generic
|
||||
If the context defines _at least_ one `org.springframework.cache.Cache` bean, a
|
||||
`CacheManager` wrapping them is configured.
|
||||
Generic caching is used if the context defines _at least_ one
|
||||
`org.springframework.cache.Cache` bean, a `CacheManager` wrapping them is configured.
|
||||
|
||||
|
||||
|
||||
[[boot-features-caching-provider-ehcache2]]
|
||||
==== EhCache 2.x
|
||||
EhCache 2.x tries to locate a configuration file named `ehcache.xml` at the root of the
|
||||
EhCache 2.x is used if a file named `ehcache.xml` can be found at the root of the
|
||||
classpath. If EhCache 2.x and such file is present it is used to bootstrap the cache
|
||||
manager. An alternate configuration file can be provide a well:
|
||||
manager. An alternate configuration file can be provide a well using:
|
||||
|
||||
[source,properties,indent=0]
|
||||
----
|
||||
spring.cache.ehcache.config=classpath:config/another-config.xml
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[boot-features-caching-provider-hazelcast]]
|
||||
==== Hazelcast
|
||||
|
||||
Hazelcast tries to locate its configuration file as follows: An `hazelcast.xml` file
|
||||
stored either in the current working directory or at the root of the classpath, or a
|
||||
location specified via the `hazelcast.config` system property. Spring Boot detects all
|
||||
of these and allow for explicit location as well:
|
||||
Hazelcast is used if a `hazelcast.xml` file can be found in the current working
|
||||
directory, at the root of the classpath or a location specified via the `hazelcast.config`
|
||||
system property. Spring Boot detects all of these and also allows for explicit location
|
||||
using:
|
||||
|
||||
[source,properties,indent=0]
|
||||
----
|
||||
spring.cache.hazelcast.config=classpath:config/my-hazelcast.xml
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[boot-features-caching-provider-infinispan]]
|
||||
==== Infinispan
|
||||
|
||||
Infinispan has no default configuration file location so it must be specified explicitly
|
||||
(or the default bootstrap is used).
|
||||
|
||||
|
|
@ -2423,7 +2414,6 @@ configuration file, Spring Boot does its best to accommodate with implementation
|
|||
----
|
||||
# Only necessary if more than one provider is present
|
||||
spring.cache.jcache.provider=com.acme.MyCachingProvider
|
||||
|
||||
spring.cache.jcache.config=classpath:acme.xml
|
||||
----
|
||||
|
||||
|
|
@ -2456,7 +2446,7 @@ property.
|
|||
==== Guava
|
||||
If Guava is present, a `GuavaCacheManager` is auto-configured. Caches can be created
|
||||
on startup using the `spring.cache.cache-names` property and customized by one of the
|
||||
following (in that order):
|
||||
following (in this order):
|
||||
|
||||
1. A cache spec defined by `spring.cache.guava.spec`
|
||||
2. A `com.google.common.cache.CacheBuilderSpec` bean is defined
|
||||
|
|
|
|||
|
|
@ -238,7 +238,7 @@ where `+*+` is a particular type of application. This naming structure is intend
|
|||
help when you need to find a starter. The Maven integration in many IDEs allow you to
|
||||
search dependencies by name. For example, with the appropriate Eclipse or STS plugin
|
||||
installed, you can simply hit `ctrl-space` in the POM editor and type
|
||||
''spring-boot-starter'' for a complete list.
|
||||
"`spring-boot-starter`" for a complete list.
|
||||
|
||||
Third party starters should not start with `spring-boot-starter` as it is reserved for
|
||||
official starters. A third-party starter for `acme` will be typically named
|
||||
|
|
|
|||
Loading…
Reference in New Issue