Skip to content

Latest commit

 

History

History
171 lines (146 loc) · 8.76 KB

README.md

File metadata and controls

171 lines (146 loc) · 8.76 KB
Raw

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 or use the Docker version.

Building

To build the microservice from source, please follow the instructions in here

Docker

To use the CLoudSDK deployment please follow here

OpenAPI

You may get static page with OpenAPI docs generated from the definition on GitHub Page. Also, you may use Swagger UI with OpenAPI definition file raw link (i.e. latest version file) 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 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.

Also, you may use Swagger UI with OpenAPI definition file raw link (i.e. latest version file) 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.

mkdir certs
mkdir certs/cas
mkdir logs
mkdir uploads

You should now have the following:

--+-- 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.

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.

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

Default username and password

The default username and password are set in owsec.properties file. The following entries manage the username and password

authentication.default.username = [email protected]
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.

echo -n "<password><username>" | shasum -a 256

Here is a complete example for username "[email protected]" and the password being "weLoveWifi".

echo -n "[email protected]" | shasum -a 256
b5bfed31e2a272e52973a57b95042ab842db3999475f3d79f1ce0f45f465e34c  -

Then you need to modify your properties file like this

authentication.default.username = [email protected]
authentication.default.password = b5bfed31e2a272e52973a57b95042ab842db3999475f3d79f1ce0f45f465e34c

Remember, when you login, use [email protected] 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 on first login or using the following script:

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 [email protected] # 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:

export OWSEC=openwifi.wlan.local:16001
#export FLAGS="-k"
export [email protected]
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

Contributions

We need more contributors. Should you wish to contribute, please follow the contributions 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 here
OWGW Controller Service here here
OWFMS Firmware Management Service here here
OWPROV Provisioning Service here here
OWANALYTICS Analytics Service here here
OWSUB Subscriber Service here here