README.md 6.19 KB
Newer Older
Jochen Kressin's avatar
Jochen Kressin committed
1
2
# Search Guard Kibana Plugin

Jochen Kressin's avatar
Jochen Kressin committed
3
4
5
<p align="center">
<img src="http://docs.search-guard.com/latest/search-guard-frontmatter.png" style="width: 60%" class="md_image"/>
</p>
Jochen Kressin's avatar
Jochen Kressin committed
6

Jochen Kressin's avatar
Jochen Kressin committed
7
## About this plugin
Jochen Kressin's avatar
Jochen Kressin committed
8

9
This plugin for Kibana adds session management and true multi-tenancy to a [Search Guard](https://search-guard.com) secured cluster.
Jochen Kressin's avatar
Jochen Kressin committed
10

11
For Kibana 7.x and 6.x it also provides a configuration GUI for Search Guard.
Jochen Kressin's avatar
Jochen Kressin committed
12

13
14
15
16
## Commercial use

This software is licensed under the Apache2 license and can be used freely also for commercial purposes. Some features may require the [Search Guard Enterprise Edition](https://search-guard.com/licensing/) or above to function.

Jochen Kressin's avatar
Jochen Kressin committed
17
18
19
20
21
22
23
24
## Installation

Download the release matching your Kibana installation, and install it like any other Kibana plugin:

```
bin/kibana-plugin install file:///path/to/searchguard-kibana-<version>.zip
```

25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
## Configuration

Execute the install_demo_configuration script to configure the Search Guard Kibana plugin with a demo configuration and create a self-signed TLS certificate. Afterward, make sure you configured the Search Guard Elasticsearch plugin accordingly. [Check the documentation](https://docs.search-guard.com/latest/authentication-authorization).

```
  ____                                 _          ____                              _ 
 / ___|    ___    __ _   _ __    ___  | |__      / ___|  _   _    __ _   _ __    __| |
 \___ \   / _ \  / _` | | '__|  / __| | '_ \    | |  _  | | | |  / _` | | '__|  / _` |
  ___) | |  __/ | (_| | | |    | (__  | | | |   | |_| | | |_| | | (_| | | |    | (_| |
 |____/   \___|  \__,_| |_|     \___| |_| |_|    \____|  \__,_|  \__,_| |_|     \__,_|
                                                                                      
? What do you want to configure? (Use arrow keys)
❯ Basic Login demo 
  OpenID Connect demo 
  JWT demo 
  SAML demo 
  Proxy demo 
  Kerberos demo 
```

### Linux
```
cd kibana/plugins/searchguard
./install_demo_configuration.sh
```

### Windows
```
cd kibana\plugins\searchguard
powershell -ExecutionPolicy Bypass -File install_demo_configuration.ps1
```
Jochen Kressin's avatar
Jochen Kressin committed
56
57
58

## Documentation

59
### Kibana 7.x
Jochen Kressin's avatar
Jochen Kressin committed
60
* [Installation](http://docs.search-guard.com/latest/kibana-plugin-installation)
61
* [Authentication](https://docs.search-guard.com/latest/kibana-authentication-types)
Jochen Kressin's avatar
Jochen Kressin committed
62
63
* [Multi Tenancy](http://docs.search-guard.com/latest/kibana-multi-tenancy)
* [Configuration GUI](http://docs.search-guard.com/latest/configuration-gui)
Jochen Kressin's avatar
Jochen Kressin committed
64

65
66
67
68
69
70
### Kibana 6.x
* [Installation](http://docs.search-guard.com/6.x-25/kibana-plugin-installation)
* [Authentication](http://docs.search-guard.com/6.x-25/kibana-authentication-types)
* [Multi Tenancy](http://docs.search-guard.com/6.x-25/kibana-multi-tenancy)
* [Configuration GUI](http://docs.search-guard.com/6.x-25/configuration-gui)

Jochen Kressin's avatar
Jochen Kressin committed
71
72
73
74
### Kibana 5.x
* [Installation](http://docs.search-guard.com/v5/kibana-plugin-installation)
* [Authentication](http://docs.search-guard.com/v5/kibana-authentication)
* [Multi Tenancy](http://docs.search-guard.com/v5/kibana-multi-tenancy)
Jochen Kressin's avatar
Jochen Kressin committed
75

76
77
78
79
## Development

See the [kibana contributing guide](https://github.com/elastic/kibana/blob/master/CONTRIBUTING.md) and the Search Guard documentation above for instructions setting up your development environment. Once you have completed that, use the following yarn scripts.

Sergii Bondarenko's avatar
Sergii Bondarenko committed
80
  - `yarn kbn bootstrap`
81
82
83
84
85
86
87
88
89
90
91
92
93

    Install dependencies and crosslink Kibana and all projects/plugins.

    > ***IMPORTANT:*** Use this script instead of `yarn` to install dependencies when switching branches, and re-run it whenever your dependencies change.

  - `yarn start`

    Start kibana and have it include this plugin. You can pass any arguments that you would normally send to `bin/kibana`

      ```
      yarn start --elasticsearch.hosts http://localhost:9220
      ```

Lyudmila Huzenko's avatar
Lyudmila Huzenko committed
94
  - `./build.sh <install-local|deploy-snapshot-maven>`
95

Lyudmila Huzenko's avatar
Lyudmila Huzenko committed
96
    Build locally a distributable archive of your plugin or deploy snapshot to maven repository.
97
98
99

  - `yarn test:browser`

Sergii Bondarenko's avatar
Sergii Bondarenko committed
100
    Run UI unit tests.
101
102
103

  - `yarn test:server`

Sergii Bondarenko's avatar
Sergii Bondarenko committed
104
    Run server unit tests.
105

106
107
108
109
  - `yarn test:prepare_integration_test`

    Run script for integration tests when Elasticsearch and Kibana should have different version in the same cluster: eliminate Kibana version check error and install required packages.

110
111
For more information about any of these commands run `yarn ${task} --help`. For a full list of tasks checkout the `package.json` file, or run `yarn run`.

112
113
### Development tips

Sergii Bondarenko's avatar
Sergii Bondarenko committed
114
115
  - Use [NVM](https://github.com/nvm-sh/nvm) to manage multiple versions of Node.js.

116
117
  - Comment `/plugins` in Kibana .eslintignore file to make the eslint working in your IDE.

118
119
120
121
122
123
### Integration tests
#### Custom branch
  You can make CI to run integration tests against specific Kibana branch or/and specific branch of Search Guard Suite plugin, for example: 
  **package.json**
```json  
    "searchguard": {  
124
        "test_sg_version": "7.8.0-42.0.0-SNAPSHOT",
125
126
127
128
        "kibana_branch": "7.7"
    }
```
where
129
  - `test_sg_version` - is the location of the latest SNAPSHOT for specified Search Guard and ES versions in Search Guard maven repository.
130
131
132
133
134
  - `kibana_branch` - is the branch in the official Kibana repository, which should be used for building and testing Search Guard Kibana plugin.
  
  These parameters are optional - if you don't specify them, the integration tests will be executed according to standard procedure.
  > ***IMPORTANT:*** Please, do not use these parameters in production branches of Search Guard Kibana plugin.

CI Runner's avatar
CI Runner committed
135
## License
136

CI Runner's avatar
CI Runner committed
137
Copyright 2015-2018 floragunn GmbH
Jochen Kressin's avatar
Jochen Kressin committed
138
139
140

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Jochen Kressin's avatar
Jochen Kressin committed
141
http://www.apache.org/licenses/LICENSE-2.0
Jochen Kressin's avatar
Jochen Kressin committed
142
143
144

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

CI Runner's avatar
CI Runner committed
145
## Legal
Jochen Kressin's avatar
Jochen Kressin committed
146
147

Search Guard is a trademark of floragunn GmbH, registered in the U.S. and in other countries
Jochen Kressin's avatar
Jochen Kressin committed
148

CI Runner's avatar
CI Runner committed
149
Elasticsearch, Kibana, Logstash, and Beats are trademarks of Elasticsearch BV, registered in the U.S. and in other countries.
Jochen Kressin's avatar
Jochen Kressin committed
150

151
floragunn GmbH is not affiliated with Elasticsearch BV.