mirror of
https://github.com/Telecominfraproject/wlan-cloud-ucentralsec.git
synced 2026-01-27 10:23:15 +00:00
172 lines
8.8 KiB
Markdown
172 lines
8.8 KiB
Markdown
<p align="center">
|
|
<img src="images/project/logo.svg" width="200"/>
|
|
</p>
|
|
|
|
# OpenWiFi Security (OWSEC)
|
|
|
|
## What is it?
|
|
The OWSEC is a service for the TIP OpenWiFi CloudSDK (OWSDK).
|
|
OWSEC is the Authentication and Resource Policy Access service for the TIP
|
|
OpenWiFi Cloud SDK (OWSDK). OWSEC,
|
|
like all other OWSDK microservices, is defined using an OpenAPI definition and uses the ucentral communication
|
|
protocol to interact with Access Points. To use the OWSUB, you either need to [build it](#building) or use the
|
|
[Docker version](#docker).
|
|
|
|
## Building
|
|
To build the microservice from source, please follow the instructions in [here](./BUILDING.md)
|
|
|
|
## Docker
|
|
To use the CLoudSDK deployment please follow [here](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy)
|
|
|
|
## OpenAPI
|
|
You may get static page with OpenAPI docs generated from the definition on [GitHub Page](https://telecominfraproject.github.io/wlan-cloud-ucentralsec/).
|
|
Also, you may use [Swagger UI](https://petstore.swagger.io/#/) with OpenAPI definition file raw link (i.e. [latest version file](https://raw.githubusercontent.com/Telecominfraproject/wlan-cloud-ucentralsec/main/openapi/owsec.yaml)) to get interactive docs page.
|
|
|
|
## Usage
|
|
Like all other OWSDK services, OWSEC is defined through an OpenAPI. You can use this API to build your own
|
|
applications or integration modules into your own systems. If all you need it to access the OWGW for
|
|
example (the service that manages the APs), you will need to:
|
|
- get a token (`/oauth2`)
|
|
- find the endpoints on the system (`/systemEndpoints`)
|
|
- choose a microservice to manage (pick an endpoint that matches what you are trying to do by looking at its
|
|
`type`. For the Cloud SDK Controller, type = owgw)
|
|
- make your calls (use the PublicEndPoint of the corresponding entry to make your calls,
|
|
do not forget to add `/api/v1` as the root os the call)
|
|
|
|
The CLI for the [OWGW](https://github.com/telecominfraproject/wlan-cloud-ucentralsec/blob/main/test_scripts/curl/cli) has
|
|
a very good example of this. Look for the `setgateway` function.
|
|
|
|
You may get static page with OpenAPI docs generated from the definition on [GitHub Page](https://telecominfraproject.github.io/wlan-cloud-ucentralsec/).
|
|
|
|
Also, you may use [Swagger UI](https://petstore.swagger.io/#/) with OpenAPI definition file raw link (i.e. [latest version file](https://validator.swagger.io/validator?url=https://raw.githubusercontent.com/Telecominfraproject/wlan-cloud-ucentralsec/main/openpapi/owsec.yaml)) to get interactive docs page.
|
|
|
|
#### Expected directory layout
|
|
From the directory where your cloned source is, you will need to create the `certs`, `logs`, and `uploads` directories.
|
|
```bash
|
|
mkdir certs
|
|
mkdir certs/cas
|
|
mkdir logs
|
|
mkdir uploads
|
|
```
|
|
You should now have the following:
|
|
```text
|
|
--+-- certs
|
|
| +--- cas
|
|
+-- cmake
|
|
+-- cmake-build
|
|
+-- logs
|
|
+-- src
|
|
+-- test_scripts
|
|
+-- openapi
|
|
+-- uploads
|
|
+-- owsec.properties
|
|
```
|
|
|
|
### Certificate
|
|
The OWSEC uses a certificate to provide security for the REST API Certificate to secure the Northbound API.
|
|
|
|
#### The `certs` directory
|
|
For all deployments, you will need the following `certs` directory, populated with the proper files.
|
|
|
|
```text
|
|
certs ---+--- restapi-ca.pem
|
|
+--- restapi-cert.pem
|
|
+--- restapi-key.pem
|
|
```
|
|
|
|
## Firewall Considerations
|
|
| Port | Description | Configurable |
|
|
|:------|:-------------------------------------------|:------------:|
|
|
| 16001 | Default port from the devices to the OWSEC | yes |
|
|
|
|
### Environment variables
|
|
The following environment variables should be set from the root directory of the service. They tell the OWGW process where to find
|
|
the configuration and the root directory.
|
|
```bash
|
|
export OWGW_ROOT=`pwd`
|
|
export OWGW_CONFIG=`pwd`
|
|
```
|
|
You can run the shell script `set_env.sh` from the microservice root.
|
|
|
|
### OWSEC Service Configuration
|
|
The configuration is kept in a file called `owsec.properties`. To understand the content of this file,
|
|
please look [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/blob/main/CONFIGURATION.md)
|
|
|
|
### Default username and password
|
|
The default username and password are set in `owsec.properties` file. The following entries manage the username and password
|
|
```properties
|
|
authentication.default.username = tip@ucentral.com
|
|
authentication.default.password = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
|
```
|
|
The password is a long sequence of hexadecimal digits. It is the result of hashing the `username` and the `password`.
|
|
In order to create the password, please follow these simple instructions.
|
|
```bash
|
|
echo -n "<password><username>" | shasum -a 256
|
|
```
|
|
Here is a complete example for username "root@system.com" and the password being "weLoveWifi".
|
|
```bash
|
|
echo -n "weLoveWifiroot@system.com" | shasum -a 256
|
|
b5bfed31e2a272e52973a57b95042ab842db3999475f3d79f1ce0f45f465e34c -
|
|
```
|
|
Then you need to modify your properties file like this
|
|
```properties
|
|
authentication.default.username = root@system.com
|
|
authentication.default.password = b5bfed31e2a272e52973a57b95042ab842db3999475f3d79f1ce0f45f465e34c
|
|
```
|
|
Remember, when you login, use `root@system.com` with the password `weLoveWifi`, not this monster digit sequence.
|
|
|
|
### Changing default password
|
|
On the first startup of the service new user will be created with the default credentials from properties `authentication.default.username` and `authentication.default.password`, but **you will have to change the password** before making any real requests.
|
|
You can this using [owgw-ui](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw-ui/) on first login or using the following script:
|
|
|
|
```bash
|
|
export OWSEC=openwifi.wlan.local:16001 # endpoint to your owsec RESTAPI endpoint
|
|
#export FLAGS="-k" # uncomment and add curl flags that you would like to pass for the request (for example '-k' may be used to pass errors with self-signed certificates)
|
|
export OWSEC_DEFAULT_USERNAME=root@system.com # default username that you've set in property 'authentication.default.username'
|
|
export OWSEC_DEFAULT_PASSWORD=weLoveWifi # default password __in cleartext__ from property 'authentication.default.password'
|
|
export OWSEC_NEW_PASSWORD=NewPass123% # new password that must be set for the user (must comply with 'authentication.validation.expression')
|
|
test_scripts/curl/cli testlogin $OWSEC_DEFAULT_USERNAME $OWSEC_DEFAULT_PASSWORD $OWSEC_NEW_PASSWORD
|
|
```
|
|
|
|
CLI is also included in Docker image if you want to run it this way:
|
|
|
|
```bash
|
|
export OWSEC=openwifi.wlan.local:16001
|
|
#export FLAGS="-k"
|
|
export OWSEC_DEFAULT_USERNAME=root@system.com
|
|
export OWSEC_DEFAULT_PASSWORD=weLoveWifi
|
|
export OWSEC_NEW_PASSWORD=NewPass123%
|
|
docker run --rm -ti \
|
|
--network=host \
|
|
--env OWSEC \
|
|
--env FLAGS \
|
|
--env OWSEC_DEFAULT_USERNAME \
|
|
--env OWSEC_DEFAULT_PASSWORD \
|
|
--env OWSEC_NEW_PASSWORD \
|
|
tip-tip-wlan-cloud-ucentral.jfrog.io/owsec:main \
|
|
/cli testlogin $OWSEC_DEFAULT_USERNAME $OWSEC_DEFAULT_PASSWORD $OWSEC_NEW_PASSWORD
|
|
```
|
|
|
|
It is very important that you not use spaces in your OrgName.
|
|
## Kafka topics
|
|
Toe read more about Kafka, follow the [document](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/KAFKA.md)
|
|
|
|
## Contributions
|
|
We need more contributors. Should you wish to contribute,
|
|
please follow the [contributions](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/CONTRIBUTING.md) document.
|
|
|
|
## Pull Requests
|
|
Please create a branch with the Jira addressing the issue you are fixing or the feature you are implementing.
|
|
Create a pull-request from the branch into master.
|
|
|
|
## Additional OWSDK Microservices
|
|
Here is a list of additional OWSDK microservices
|
|
| Name | Description | Link | OpenAPI |
|
|
| :--- | :--- | :---: | :---: |
|
|
| OWSEC | Security Service | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralsec) | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/blob/main/openpapi/owsec.yaml) |
|
|
| OWGW | Controller Service | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw) | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/openapi/owgw.yaml) |
|
|
| OWFMS | Firmware Management Service | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralfms) | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralfms/blob/main/openapi/owfms.yaml) |
|
|
| OWPROV | Provisioning Service | [here](https://github.com/Telecominfraproject/wlan-cloud-owprov) | [here](https://github.com/Telecominfraproject/wlan-cloud-owprov/blob/main/openapi/owprov.yaml) |
|
|
| OWANALYTICS | Analytics Service | [here](https://github.com/Telecominfraproject/wlan-cloud-analytics) | [here](https://github.com/Telecominfraproject/wlan-cloud-analytics/blob/main/openapi/owanalytics.yaml) |
|
|
| OWSUB | Subscriber Service | [here](https://github.com/Telecominfraproject/wlan-cloud-userportal) | [here](https://github.com/Telecominfraproject/wlan-cloud-userportal/blob/main/openapi/userportal.yaml) |
|