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
UsernameBy default, this is set to the username of the account you logged into Custos Portal
First NameBy default, this is set to the First Name of the account you logged into Custos Portal
Last NameBy default, this is set to the Last Name of the account you logged into Custos Portal
EmailBy default, this is set to the email  of the account you logged into Custos Portal
PasswordPlease specify 8 characters long string contains a letter. number and one special character.
Confirm PasswordRe-enter the above password

                    

           

Step 3

a) Tenant details

Field ValueDescription
Tenant NameSample CanvasApplication name 
Redirect URIhttp://localhost:8080/callback

http:// your_application_hosted_domain:port/callback

This is used to capture authentication responses from the Custos

Scopeopenid, email, profile, org. cilogon.userinfoThese are used to fetch user claims (username, firstname, lastname, email, profile ..etc)
Domain127.0.0.1The domain name of  hosted application
Client URIhttp://localhost:8080/Landing page URL of application
Logo URIhttp://localhost:8080/logo.pngLogo URL of your application, where logo is stored
CommentThis is Sample canvas custos tenantAny note to Custos admin or about your tenant.
Application TypeWebBy 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

FieldValueDescription
Group IDSystem generated valueRepresent ID of the group
Namestudent-group,  or teaching-assitant groupGroup name
DescriptionThis is a student group, This is a TA groupDescription 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.















  • No labels