Science gateways represent potential targets for cybersecurity threats to users, scientific research, and scientific resources. Custos is a software framework that provides common security operations for science gateways, including user identity and access management, gateway tenant profile management, resource secrets management, and groups and sharing management. The goals of the Custos project are to provide these services to a wide range of science gateway frameworks, providing the community with an open-source, transparent, and reviewed code base for common security operations; and to operate trustworthy security services for the science gateway community using this software base. To accomplish these goals, we implement Custos using a scalable microservice architecture that can provide highly available, fault-tolerant operations. Custos exposes these services through a language-independent Application Programming Interface that encapsulates science gateway usage scenarios.
Following diagram illustrate the architecture of the Custos Software.
To find out more, please check out the Custos website.
-
Java 17
-
Docker installed on local environment
-
Maven 3.6.x
git clone -b develop https://github.com/apache/airavata-custos.git
Following command builds the Custos source code and create two docker images of custos_core_server and custos_integration_server
cd airavata-custos
mvn clean install
Following command starts Custos main services and its depend services. All services are listed below and you should be able to access them locally if all services are correctly started.
-
Dependent Services
- Keycloak (http://localhost:8080/auth/)
- MySQL (0.0.0.0:3306)
- HashiCorp Vault (http://localhost:8201/)
- CILogon (Not available for local development)
-
Custos Services
- Custos Core Service (0.0.0.0:7001 (grpc port))
- Custos Integration Service (0.0.0.0:7000 (grpc port))
- Custos Rest Proxy (http://localhost:10000(envoy proxy)
cd custos-utilities/ide-integration/src/main/containers
docker-compose up
If all services were successfully ran. Custos bootstrap service needs to be run to create a Super tenant to launch Custos Portal
cd custos-utilities/custos-bootstrap-service/
mvn spring-boot:run
The above command should create the super tenant and it outputs super tenant credentials. Copy those credentials to configure Custos Portal.
Note: Make sure to clean up old databases for fresh start.
Follow the following link to access portal deployment instructions
You have to configure following properties in the .env file
CUSTOS_CLIENT_ID="SUPERT TENANT ID CREATED FROM ABOVE STEP"
CUSTOS_CLIENT_SEC="SUPERT TENANT CREDENTIAL CREATED FROM ABOVE STEP"
CUSTOS_API_URL="http://localhost:10000"
CUSTOS_SUPER_CLIENT_ID="SUPERT TENANT ID CREATED FROM ABOVE STEP"
UNDER_MAINTENANCE=False
Custos can be integrated with external applications using Custos REST Endpoints, Python SDK, or Java SDK.
In order to perform this operation you need to have a already activated tenant in either Custos Managed Services or Your own deployment. Following instructions are given for locally deployed custos setup which can be extended to any deployment,
####Initializing Custos Java SDK
- Add maven dependency to your project
<groupId>org.apache.custos</groupId>
<artifactId>custos-java-sdk</artifactId>
<version>1.1-SNAPSHOT</version>
</dependency>
- Initialize Custos Client Provider in your application
CustosClientProvider custosClientProvider = new CustosClientProvider.Builder().setServerHost("localhost")
.setServerPort(7000)
.setClientId(CUSTOS CLIENT ID) // client Id generated from above step or any active tenant id
.setClientSec(CUSTOS CLIENT SECRET)
.usePlainText(true) // Don't use this in production setup
.build();
Once above step is done, you can use custos available methods for authentication and authorization purposes
- Sample client code to register and enable a User
UserManagementClient userManagementClient = custosClientProvider.getUserManagementClient();
userManagementClient.registerUser("jhon","Smith","testpassword","smith@1",
"jhon@email.com",false);
userManagementClient.enableUser("jhon");
OperationStatus status = userManagementClient.isUserEnabled("Jhon");
Follow the Ansible based deployed instructions. see documentation here
Please create a github issue or subscribe to custos mailing list custos-subscribe@airavata.apache.org and send us an email.
@inproceedings{10.1145/3311790.3396635,
author = {Ranawaka, Isuru and Marru, Suresh and Graham, Juleen and Bisht, Aarushi and Basney, Jim and Fleury, Terry and Gaynor, Jeff and Wannipurage, Dimuthu and Christie, Marcus and Mahmoud, Alexandru and Afgan, Enis and Pierce, Marlon},
title = {Custos: Security Middleware for Science Gateways},
year = {2020},
isbn = {9781450366892},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3311790.3396635},
doi = {10.1145/3311790.3396635},
booktitle = {Practice and Experience in Advanced Research Computing},
pages = {278–284},
numpages = {7},
location = {Portland, OR, USA},
series = {PEARC '20}
}
@inproceedings{10.1145/3491418.3535177,
author = {Ranawaka, Isuru and Goonasekara, Nuwan and Afgan, Enis and Basney, Jim and Marru, Suresh and Pierce, Marlon},
title = {Custos Secrets: A Service for Managing User-Provided Resource Credential Secrets for Science Gateways},
year = {2022},
isbn = {9781450391610},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3491418.3535177},
doi = {10.1145/3491418.3535177},
booktitle = {Practice and Experience in Advanced Research Computing},
articleno = {40},
numpages = {4},
location = {Boston, MA, USA},
series = {PEARC '22}
}
We are thankfull to National Science Foundation(NSF) for funding this project.
We are thankfull to Trusted CI (https://www.trustedci.org/) for conducting the First Principles Vulnerability Assesment(FPVA) (https://dl.acm.org/doi/10.1145/1866835.1866852) for this software and providing the above architecture diagram and security improvements.