diff --git a/.idea/codeStyles/Project.xml b/.idea/codeStyles/Project.xml index 1f3317b..5fc93d9 100644 --- a/.idea/codeStyles/Project.xml +++ b/.idea/codeStyles/Project.xml @@ -9,7 +9,7 @@ diff --git a/img/token_confirm.jpg b/img/token-confirm.jpg similarity index 100% rename from img/token_confirm.jpg rename to img/token-confirm.jpg diff --git a/img/token-nihlogin.jpg b/img/token-nih-login.jpg similarity index 100% rename from img/token-nihlogin.jpg rename to img/token-nih-login.jpg diff --git a/obtaining_a_token.md b/obtaining_a_token.md index e3df337..03963ea 100644 --- a/obtaining_a_token.md +++ b/obtaining_a_token.md @@ -1,123 +1,101 @@ - +# Obtaining a token to access dbGaP data -## Obtaining a token to access dbGaP data +The following describes a simple web application to obtain a "passport" or token to access controlled access data via programmatic interfaces (APIs). It requires you to log in to dbGaP and download a file containing a token which can be used in calls to the APIs. -The following describes a simple web application to obtain a "passport" or token to access controlled access data via programmatic interfaces (APIs). It requires you to log in to dbGaP and download a file containing a token which can be used in calls to the APIs. +## Note on use of controlled access data -### Note on use of controlled access data +Your access to controlled data is granted under a project previously +submitted by an investigator. You, the user, may be that investigator, or have been designated by that investigator as a 'downloader'. The specific terms of use are described in a Data Use Agreement. Please ensure you are familiar with the terms of use. -Your access to controlled data is granted under a project previously submitted by an investigator. You, the user, may be that investigator, or have been designated by that investigator as a 'downloader'. The specific terms of use are described in a Data Use Agreement. Please ensure you are familiar with the terms of use +## Obtain a token or passport - - -### Obtain a token or passport - -In a web browser, open the following link to open the Power User Portal +In a web browser, open the following link to open the Power User Portal https://dbgap.ncbi.nlm.nih.gov/cda/dbGaPLogin/ -token-chooseYou may request a passport or a task specific token. Each may be used as follows: +The main power-user portal page. It has options for obtaining a RAS passport or a Task-Specific TokenYou may request a passport or a task specific token. Each may be used as follows: -#### Passport +### Passport -May be used with the NCBI Data Repository Service (DRS1) to access files. +May be used with the NCBI Data Repository Service (DRS1) to access files. - Click **Get My Passport**. - Go to **Login** below +### Task Specific Token -#### Task Specific Token - -May be used with NCBI DRS or FHIR server. +May be used with NCBI DRS or FHIR server. Scroll down to the "RAS - Obtain a dbGaP Task Specific Token" -token-tst +The RAS Task Specific Token (TST) section of the power user portal. It has a button labeled "Get Task Specific Token" - Click Get **Task Specific Token** - Go to **Login** below - 1DRS is a standard published by the Global Alliance for Genomics and Health (GA4GH). -## Login - - Whether you picked Passport or Task Specific Token you will be asked to log in using the appropriate method depending on the organization you work for. - -token-nihlogin +# Login +Whether you picked Passport or Task Specific Token you will be asked to log in using the appropriate method depending on the organization you work for. +A web page entitled "Sign in" with the option to use a smart card login or an authenticator app combined with username and password The next steps depend on whether you are obtaining a Passport or TST. -### Passport +## Passport After logging in Click **Download** to save the passport to a local file according to how your web browser is set up to handle downloads. You have now obtained the passport required by the API you wish to use it with. -### Task Specific Token +## Task Specific Token -Select the dbGaP project you wish to work with and download the token as follows. +Select the dbGaP project you wish to work with and download the token as follows. ### Select dbGaP project -The one or more dbGaP projects under which you have been granted access will be listed. +The one or more dbGaP projects under which you have been granted access will be listed. -For each project the investigator will have requested access to certain dbGaP study consent groups2. Click the checkbox next to the project you wish to work with. +For each project, the investigator will have requested access to certain dbGaP study consent groups2. Click the checkbox next to the project you wish to work with. -2a consent group is a group of subjects within a study who consented to use of their data under particular terms. +2A consent group is a group of subjects within a study who consented to use of their data under particular terms. #### Single project displayed For most users only one project will be displayed. In this case you may simply select the project and click **Submit**. -Note: the individual study consent groups within the project will be displayed, and all are pre-selected. It is currently possible to select only specific study consent groups - but this is generally unnecessary. In the interests of simplification this feature will be removed in future. +Note: the individual study consent groups within the project will be displayed, and all are pre-selected. It is currently possible to select only specific study consent groups - but this is generally unnecessary. We will remove this feature in the future to simplify the interface. #### Multiple projects displayed In the case where more than one project is available the following apply: -It is possible to make selections of consent groups from more than one project. In general you should avoid this. Access to studies was granted according to the purposes of the submitted project. Combining data from studies across projects may be outside the terms under which access was granted. +It is possible to make selections of consent groups from more than one project. In general, you should avoid this. Access to studies was granted according to the purposes of the submitted project. Combining data from studies across projects may be outside the terms under which access was granted. - token-project + A list with two entries, "Engineering a centralized approach for the analysis of NIH-funded human sequence data.&quote and "Scientific and technical management of data commons projects at NIH" Each entry has a check box on the right and a "plus" icon on the right one may click to expand to see the options under it. - Scroll down and select **Submit**. +Scroll down and select **Submit**. -## Select token duration +### Select token duration Choose how long you would like the token to be valid, and click **Submit**. -token-duration - - +A radio box entitled "Select token duration from this list." It has four choices: 1 minute, 10 minutes, 1 hour, and 12 hours. -## Confirm details +### Confirm details Click **Confirm** if you are happy with the selections made. You may click **Re-Select** to return to the project selection page -Graphical user interface Description automatically generated - -## Download - -Click **Download** to save the token to a local file. - - - -Graphical user interface, text, application, email Description automatically generated - - - - - - Use the downloaded token with the API you wish to use. Consult the API documentation for how to include the token in your request to the API. - ------- - - +The bottom of a page. It displays several studies with their accession and a brief description. Each study is in black text on a gray background. Below is a field entitled "Selected Duration" containing the text "12 hours" Finally, at the bottom is a section entitled "Confirm your selections:" This section contains two buttons, Re-select and Confirm. +### Download +Click **Download** to save the token to a local file. Ensure only you can access the file. +A success screen containing the message "Hello. You have successfully logged into RAS. Click the Download button to download your NCBI Task-Specific-Token!." Below the message is a button labeled Download. At the bottom is a link to return to the dbGaP Authorized Access Portal. +Use the downloaded token with the API you wish to use. Consult the API documentation for how to include the token in your request to the API. +---