Dataset authorisation info

Original trac page

Introduction

(updated 20230215)

This document describes how the authorisation system works. It covers public, registered user and restricted resources.

To set up access control fully there are 3 systems that need interacting with:

• accessInstructor- this is where the actual access control within the archive is set for FTP and web download and JASMIN access
• userDB - this is where the application system is set up and maps to user accounts for actual user access
• MOLES - to provide the link for people to register/get information on access control/licencing that is in place

For the following 'access group' refers to the archive access group NOT the Linux group, which will be referred to as the 'jasmin group'.

Important basic principles to note

• To proceed you need to know the archive path where you wish to set the rules to apply. This does NOT have to be done for every dataset within a given point in the archive, but could be higher up the directory tree if there is a common access control, licencing and JASMIN access that applies to all the datasets within a given part of the archive.
• A 'default' entry can be set at this higher point which can be overwritten/superseded by a more specific rule further down.
• These more specific rules can be set to expire and then access will go to the default option. This is very useful for embargoed data where the embargo will expire on a given day.
• The default rule, if nothing is set, should be to prevent people from accessing the data, but beware of what has been set further up the directory tree!
• for 'restricted data' a 'group' can be used to give access to a set of resources where the access control and licencing will be in common.

1. Licence file

From the DMP you should have an idea of what licence is needed for the data you are looking to get up access control for. Ideally, it should be one of the common licences. The 'licence selector' spreadsheet can help determine this. NOTE this also includes two generic licences specifically designed for 'embargoed/restricted access' data (the RUGL and RUNCGL licences), which should remove the need to create any bespoke licences in most cases!.

However, should you need to have a new, specific licence not already in the CEDA Artefacts server then :

1. get a PDF of the licence file 
2. add it to the CEDA Artefacts server under the licences/specific_licences folder in the github repository (https://github.com/cedadev/artifacts). This will then be copied to the live artefacts server by a cron job in a few minutes.
3. Inform Graham that you've added a new licence as this will then need to be classified for the types of use the licence permits. 

2. Set up accessInstructor rules

This is where the '.ftpacecs' and XACML policy files are set, plus the JASMIN group. The .ftpaccess files control access via FTP and XACML policy files set the web access control. JASMIN access is driven by this process, though there isn't an option to set this directly due to a mapping that is required... see note lower down.

1. login to https://accessctl.ceda.ac.uk/admin/
2. select 'rules' and do a quick search for the upper most directory covering the path you want to set a rule to see what has already been set.. if there isn't one that meets your needs, then proceed
3. select 'add rule', top right
4. enter the path where the rule should apply (use + to add a new one)
5. set 'rule type' - select ONE only of :
6. 1. 'public' for fully 'public' data (non-registered user AND registered users will have access). 
   2. 'reguser' for those just needing a CEDA user account
   3. 'group' if specific restriction is needed.
      This will then present a Group' selection list - either use a pre-existing group or add a new group. If you need to set up a new 'group' use the green plus symbol REMEMBER THE SELECTED GROUP! This should be lowercase, with no spaces and use '[a-z0-9], '-' or '_' as needed
7. Search for and select a licence or add a new licence (see note below)
8. If required, set expiry date for the rule
9. Add comment if you wish
10. click Save

JASMIN access

Due to the limited number of linux groups that can be utilised to control local (JASMIN) access and to enable systems to work properly with the archive, it is not possible to implement the archive access groups fully as jasmin groups. Instead there are mappings between some archive access options and jasmin groups. Changes _can_ be made, but will need to be discussed with the head of curation.

The following table describes the main JASMIN access groups in use:

Adding a new licence.

If you need to add a new licence then provide the following

• Code - a lowercase, short code to be used to speed selection
• title - a full verbose name for the title
• url link - link to the licence URL in a reliable location (if not external then add to the artefacts server), preferably the link to the item on the artefacts server (see top of this page)
• comment - a free comment if you wish 
• categories - these are classifications for the types of permitted use that the licence permits - speak to Graham about this.

3. Set up CEDA userDB entries (for 'restricted data')

IF you have set up a new group in step 2.6c above you will also need to set up the access application route in the CEDA UserDB as follows:

1. log into http://cedadb.ceda.ac.uk/admin/udbadmin/
2. under Datasets select 'add'
3. enter the new group as defined for 2.6c above in the 'datasetid' and 'group' fields. Fill all other fields in as per the table below:

   datasetid	Identifier for this entry in the table. This should normally be the same as the 'group'.
   authtype	Authentication type. The registration system recognises the values 'online' or 'manual'. The other values which have been used are 'public' if the group has been made public following a period of restricted access, 'none' if the dataset has been removed, 'internal' if this group will only be assigned manually by the BADC team, or 'badc' (?? can remember what this represents ??).
   group	This is the group name which is used to control access to the dataset. Ideally this should be the same as the datasetID (to reduce confusion). This will be the name that you use in the .ftpaccess file(s).
   description	Text description of dataset that will appear on various forms (some of which will be seen by users). This should be short and meaningfully convey what the application will get access to
   directory	not used any more
   conditions	URL of the PDF file containing the licence to be used in the applicaiton process.
   defaultRegLength	Default number of months before users dataset registration will expire. Value can be modified when dataset is approved.
   dataCentre	'badc' or 'neodc' (not used)
   infourl	This is a url which points to a page that gives information about what this group provides access to. This will appear as a link in the 'my groups' section of MyCEDA and may be used in other places in the future. If there is a one-to-one relationship between this group and a dataset then this page could be the dataset page. However, if there is a more complicated relationship (eg. only providing access to part of a dataset) then you should create a page explaining how this group works and set infourl to point to it.
   Associated linux group id	not used anymore
   Check for public key	not used any more
   comments	Any comments, for internal documentation purposes only.

4. Select 'save' 
5. If authtype was set as 'Manual' then go to http://cedadb.ceda.ac.uk/admin/udbadmin/privilege/. Here is where to set the external authoriser for the resource - for this you will need to know the CEDA user account of the authorisers for the data.... or CEDA helpdesk if this is to be used
6. Select 'add privilege'
7. look up the user for the 'userkey' using the looking glass icon to the right of the box and searching in the pop-up dialogue
8. select type to be 'authorise'
9. Select the dataset ID that you have set up as per step 3 above
10. add a comment and save

This will then enable you to test the application system. To do this use the following URL (replace the <datasetid> with the one you've set up:

https://services.ceda.ac.uk/cedasite/resreg/application?attributeid=<datasetid>

Fill in the application and submit. This will send the first 'authorisation' email off to the external authoriser.

4. Set up Catalogue (MOLES) 'permission/Constraint' for datasets

The final step is to then make sure that the access control and licencing is conveyed to the user and provide the link to gain access if required. This is done via the CEDA data catalogue (MOLES) using an record called a 'Constraint' object... these are linked to Dataset records (Observations) via the 'permission' field.  

NOTE - Where possible, pre-existing 'Constraints' should be used. For example, for 'public' access under the Open Goverment licence then the Constraint object to use is: https://catalogue.ceda.ac.uk/admin/cedamoles_app/constraints/129/.  If you're not sure of the licence at this point, don't worry - there is a constraint object for that too!

4.1 Setting up a new Constraint object

1. go to https://catalogue.ceda.ac.uk/admin/cedamoles_app/constraints/ and check for Constraints that already meet your requirements and re-use
2. else click the 'add constraints' button
3. give a label that is meaningful to help search for the constraint object
4. select access category to match that set in the securityDB
5. IF access category is 'restricted' then add in the Access Roles - i.e. the 'group' set in step 2.6c
6. Add a link to the licence file in the CEDA Artefacts service
7. Select Save

4.2 Linking to Observation/Dataset record

1. Open up Observation record to add 'constraint' object to
2. find the 'permission' box and search for the constraint you require and select it...
3. save the Observation record
4. check the user-view.. if record is not in 'preview' there should be an appropriate button displayed - e.g. Apply for Access. Informaiton should also be under the 'details' tab.
5. If able to - check that the 'apply for access button does work