Prerequisites
- Four different email accounts
- One will be used to request a tenant from the Custos (This is the default tenant admin or we can name it as University CIO)
- Email account for a professor
- Email account for a student
- Email account for a teaching assistant
- Docker installed computer
- instructions
Verify successful installation through docker version verification.
docker --version Docker version 19.03.13, build 4484c46d9d
OR If unable to install docker then follow the instructions given below.
Install latest stable nodejs (v14.17) https://nodejs.org/en/download/ and npm https://www.npmjs.com/get-npm
A. Sample Canvas Scenario
We have a sample canvas integrated with Custos to simulate student, teaching assistant, and professor assignment management use-case.
a) Professor will create an assignment and share it with "viewer" permission to student and TA group.
b) Students will do submission and share it with the professor and TA group.
c) TA will Grade the submission and share it with the "editor" permission to Professor.
d) Professor will release final grades with "viewer" permission.
B. Workflow
Step 1: Federated Authentication
a) Login to the sample canvas .
1) Click on Institution Login
2) Select your Institutional Identity Provider and insert credentials
3) You will be logged into the Sample Canvas home page, but you don't have any authorized access.
Step 2: Role-based Authorization
You need to have one of the roles assigned from Student, TA, or Professor to get an authorized view. Tenant admin will assign different roles to different users. Based on the role you will have a different view
Tenant admin need to do the following operations
- create roles → student, teaching-assistant, professor
- Assigned roles to users.
a). Professor view
b). Student view
c). TA View
Step3: Group-based authorization
Next, we need to implement more fine-grain sharing rules for assignment, submission, and grading. Tenant admin will do the following operations in the tenant.
- Create Permission Types→ EDITOR, VIEWER
- Create Entity Types→ ASSIGNMENT, GRADING, SUBMISSION
- Create Groups→ student group, the teaching assistant group
Next, the tenant admin will point the student group and teaching assistant group to the sample canvas. Once those are configured Professor can create an assignment, students can submit submissions, and TAs can grade the submissions.
a) Professor creates an assignment
c) Student view an assignment
d) Student do a submission
e) TA view submission and add grading
g) Professor release final grades
C. Tenant creation
Need to create a Custos workspace (tenant) for your application.
Step 1
a) Go to https://portal.usecustos.org
b) Log in to the application using Institutional Login/ Google/ Github
c) Select Google/Github or Institution from the list based on the email account you created for a tenant admin.
d) Enter email credentials and successful authentication will redirect you to the Custos Home page
You will see all tenants requested by you. If there are no tenants, the page will be empty. you can start with creating a new tenant.
Step 2
a) Input tenant admin details (Highest privilege role of the tenant you are creating for your application)
Field | Value |
---|---|
Username | By default, this is set to the username of the account you logged into Custos Portal |
First Name | By default, this is set to the First Name of the account you logged into Custos Portal |
Last Name | By default, this is set to the Last Name of the account you logged into Custos Portal |
By default, this is set to the email of the account you logged into Custos Portal | |
Password | Please specify 8 characters long string contains a letter. number and one special character. |
Confirm Password | Re-enter the above password |
Step 3
a) Tenant details
Field | Value | Description |
---|---|---|
Tenant Name | Sample Canvas | Application name |
Redirect URI | http://localhost:8080/callback | http:// your_application_hosted_domain:port/callback This is used to capture authentication responses from the Custos |
Scope | openid, email, profile, org. cilogon.userinfo | These are used to fetch user claims (username, firstname, lastname, email, profile ..etc) |
Domain | 127.0.0.1 | The domain name of hosted application |
Client URI | http://localhost:8080/ | Landing page URL of application |
Logo URI | http://localhost:8080/logo.png | Logo URL of your application, where logo is stored |
Comment | This is Sample canvas custos tenant | Any note to Custos admin or about your tenant. |
Application Type | Web | By default, it supports web applications |
b) Click on Create Tenant and it will create a tenant for your application
c) Custos Admin will activate your tenant. Now, you have an activated Custos tenant to be integrated with your application.
d) Refresh your tenant list, you will see the tenant status is Active and Tenant Profile-> Client ID and Secret is loaded.
Now, you are done with Tenant creation. Next, we can configure our tenant
D. Tenant Configuration
Role-based authorization
Step 1: Role Creation
a) Now, you have to configure the required roles in the tenant profile of your tenant.
b) Go to the Custos Portal→ Click on Admin tenant → Profile → Roles
c) Create roles professor, teaching-assistant, and student
Step 2: Role Assignment
Assign created roles to relevant users. based on the roles reference portal view will be different.
a) Go to the Custos Portal→ Click on Admin tenant → Users→ Click on selected user
b) Assign professor role to a relevant user
c) Assign teaching-assistant role to a relevant user
d) Assign student role to a relevant user
Group-based Authorization
Step 1. Group Creation
Group-based authorization is used when we need more fine-grained authorization than role-based authorization. We can control object sharing with different permission for different user groups.
a) Go to Custos Portal → Select Admin Tenant → Groups
b) Create New Groups
c) Create doctor group and nurse group
Field | Value | Description |
---|---|---|
Group ID | System generated value | Represent ID of the group |
Name | student-group, or teaching-assitant group | Group name |
Description | This is a student group, This is a TA group | Description of the group |
Step 2: Assign users to Groups
Once you created the student group and teaching assistant group. You (Tenant admin ) assign users to relevant groups.
Assign each user to each group.
user A → Assign to student group
user B → Assign to teaching-assistant group
Step 3: Create Entity Types
a) Go to the Custos Portal→ Click on Admin tenant → Profile → Entity Types
b) Create Entity Types
Step 4: Create Permission Types
a) Go to the Custos Portal→ Click on Admin tenant → Profile → Permission Types
b) Create Permission Types
D. Configure portal and run portal
Option 1: Step up canvas portal locally with docker (Recommended)
a) download docker-compose.yml
b) run mkdir canvas_portal (Create a directory called canvas_portal)
c) copy docker-compose.yml file into directory canvas_portal
d) Run the following commands
cd canvas_portal docker-compose up
e) If all the above steps are successfully executed following messages should be displayed in your console.
Recreating custos-demo-gateway_web_1 ... done Attaching to custos-demo-gateway_web_1 web_1 | Replacing env vars in JS web_1 | Processing /usr/share/nginx/html/js/app.58c969ac.js ... web_1 | Starting Nginx web_1 | 2021/06/22 15:58:53 notice 8#8: using the "epoll" event method web_1 | 2021/06/22 15:58:53 notice 8#8: nginx/1.20.0 web_1 | 2021/06/22 15:58:53 notice 8#8: built by gcc 10.2.1 20201203 (Alpine 10.2.1_pre1) web_1 | 2021/06/22 15:58:53 notice 8#8: OS: Linux 4.9.184-linuxkit web_1 | 2021/06/22 15:58:53 notice 8#8: getrlimit(RLIMIT_NOFILE): 1048576:1048576 web_1 | 2021/06/22 15:58:53 notice 8#8: start worker processes web_1 | 2021/06/22 15:58:53 notice 8#8: start worker process 9 web_1 | 2021/06/22 15:58:53 notice 8#8: start worker process 10 web_1 | 2021/06/22 15:58:53 notice 8#8: start worker process 11 web_1 | 2021/06/22 15:58:53 notice 8#8: start worker process 12 web_1 | 2021/06/22 15:58:53 notice 8#8: start worker process 13 web_1 | 2021/06/22 15:58:53 notice 8#8: start worker process 14 web_1 | 2021/06/22 15:58:53 notice 8#8: start worker process 15 web_1 | 2021/06/22 15:58:53 notice 8#8: start worker process 16
f) Now you should be able to load the landing page of the health portal. Go to: http://localhost:8080
Option 2: Run canvas portal with Node
a) Install latest stable nodejs (v14.17) https://nodejs.org/en/download/
b) git clone https://github.com/apache/airavata-custos-portal.git
c) cd ./airavata-custos-portal/custos-demo-gateway
d) git checkout custos-pearc-tutorial-2021
e) M ake sure the following entries are in .env file
VUE_APP_CLIENT_ID="" VUE_APP_CLIENT_SEC="" VUE_APP_REDIRECT_URI="http://localhost:8080/callback" VUE_APP_CLIENT_ENTITY_TYPE_ID_ASSIGNMENT="ASSIGNMENT" VUE_APP_CLIENT_ENTITY_TYPE_ID_SUBMISSION="SUBMISSION" VUE_APP_CLIENT_ENTITY_TYPE_ID_GRADING="GRADING" VUE_APP_CLIENT_ROLE_PROFESSOR="professor" VUE_APP_CLIENT_ROLE_TEACHING_ASSISTANT="teaching-assistant" VUE_APP_CLIENT_ROLE_STUDENT="student" VUE_APP_CLIENT_GROUP_ID_STUDENT="" VUE_APP_CLIENT_GROUP_ID_TEACHING_ASSISTANT="" VUE_APP_CLIENT_PERMISSION_TYPE_VIEWER="VIEWER" VUE_APP_CLIENT_PERMISSION_TYPE_EDITOR="EDITOR"
f) npm install
g) npm run serve
If 'npm install' command gives errors please try below yarn commands
f) npm install yarn -g
g) yarn install
h) yarn run serve
Now you should be able to load the landing page of the health portal. Go to: http://localhost:8080
But still, we did not configure the sample canvas to use Custos endpoints. We need to copy Custos client Id and Secret from the tenant portal and copy them into the docker-compose file and restart the docker container.
a) Go to the Custos portal again and click on your tenant and grab the Client ID and Secret.
b) Copy and paste the following credentials to your docker-compose.yaml
VUE_APP_CLIENT_ID: 'custos-3infegrx7mq9cv7akd5s-10002422' VUE_APP_CLIENT_SEC: '341sog5DlQv2vXEB3GL4yAMdz5CLfzKFyVkDLUeF'
c) Execute following commands
Press CTRL + C docker-compose up
d) If you are using the native approach just stop and start with
npm run serve
or
yarn run serve
The above steps should enable Institutional/ Google/Github login.