Page History

NCI uses Okta for authentication and authorization services for the CTRP applications and APIs. This page describes the tasks required to obtain the proper authorization to use the CTRP API. For any questions or support contact CTRP_support@nih.gov.

1. Create NCI CTRP user account

All users are required to have a valid Okta CTRP user account to access CTRP applications (CTRP Registration and CTRP Accrual) and use the CTRP API. For instructions on requesting an Okta CTRP account, refer to the following: Creating New NCI CTRP User Accounts.

2. Obtain Okta Client ID and Client Secret

Once your Okta CTRP user account has been created, contact CTRP_support@nih.gov to request authorization to use the CTRP APIs. CTRP Support will review the request and, if approved, will generate a Client ID and Client Secret associated with your account and provide these key values to you. The Client ID and Client secret are required parameters to generate an Okta access token. 

3. Generate Okta access token

All service endpoints require Okta access token authentication. To generate an Okta access token, a request must be made to the environment service endpoint using a valid Client ID and Client Secret. See below for additional details on how to construct the access token request.

Method: POST

Service Endpoints:

Once you have received your Client ID and Client Secret from CTRP Support, follow the steps below to use the NCI CTRP and PRS REST services. An Okta authentication token is required to use these services. There are different processes between PRS and CTRP users, see below for explanations.

For CTRP users

Users accessing the CTRP Accrual, Trial Registration, Participating Site REST services. See the following for additional details on the various CTRP web services: 

• NCI CTRP Trial Registration REST Service Guide
• NCI CTRP Accrual REST Service Guide
• NCI CTRP Participating Site REST Service Guide

1. Get Okta access token

The following endpoint will generate an Okta access token provided the parameters passed in are valid. Please contact CTRP_support@nih.gov for any questions or issues in regards to generating the Okta access token.

POST:

...

...

...

Headers

...

Parameters:

...

...

Authorization:

...

Authorization Type	Basic
UsernameclientId	Client ID generated by CTRP Support for the user account
PasswordclientSecret	Client Secret generated by CTRP Support for the user account

Response:

{"token_type":"Bearer","expires_in":43200<seconds>,"access_token":<accessToken>}

...

4. Call REST Service with Bearer Authentication

Include Once the access token has been generated, it will need to be included in the 'Authorization: Bearer' parameter when submitting API requests. The following example uses the accrual-services URL in the Stage environment and lists the required header and parameters values.

...

Method: PUT

Service Endpoint:

...

...

Headers

Authorization:

...

--header 'Content-Type: application/json' \

--header 'Accept: application/xml' \

--header 'Authorization: Bearer <accessToken>'

Parameters:

Response:

   JSON or XML data, depending on which service is being used.

For PRS users

1. Get Okta access token

The following endpoint will generate an Okta access token provided the parameters passed in are valid. Please contact CTRP_support@nih.gov for any questions or issues in regards to generating the Okta access token.

POST:

curl --request POST “https://<clientId>:<clientSecret>@bioappdev.okta.com/oauth2/aus3ym6wniM6O3MGE297/v1/token” \
--header “Accept: application/json” \
--header “Content-Type: application/x-www-form-urlencoded” \
--data-urlencode “grant_type=password” \
--data-urlencode “username=<username>” \
--data-urlencode “password=<password>” \
--data-urlencode “scope=openid”

Parameters:

...

clientId

...

Client ID

...

clientSecret

...

Client Secret

...

username

...

CTRP OKTA account email ID

...

password

...

CTRP OKTA account password

Response:

{"token_type":"Bearer","expires_in":43200,"access_token":<accessToken>,"scope":"openid","id_token":<idToken>}

2. Call REST Service with Bearer Authentication

Include the access token in the 'Authorization: Bearer' parameter when submitting API requests.

curl --location --request GET 'https://trials.nci.nih.gov/services/trials/<NCT> ' \

--header 'Content-Type: application/json' \

--header 'Accept: application/xml' \

--header 'Authorization: Bearer <accessToken>'

Parameters:

...

accessToken

...

Access Token generated in step 1.

...

NCT

...

Trial ID (e.g. NCI-2017-02883)

Body:

<tns:studySubjects xmlns:tns="gov.nih.nci.accrual.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="gov.nih.nci.accrual.webservices.types ../../src/resources/ws.xsd ">
    <tns:studySubject>
        <tns:identifier>SU001</tns:identifier>
        <tns:birthDate>2002-01-01</tns:birthDate>
        <tns:gender>Female</tns:gender>
        <tns:race>Black or African American</tns:race>
        <tns:ethnicity>Not Hispanic or Latino</tns:ethnicity>
        <tns:country>USA</tns:country>
        <tns:zipCode>22201</tns:zipCode>
        <tns:registrationDate>2014-01-01</tns:registrationDate>
        <tns:methodOfPayment>MEDICAID_AND_MEDICARE</tns:methodOfPayment>
        <tns:disease codeSystem="ICD9">861.20</tns:disease>       
    </tns:studySubject>
</tns:studySubjects>

Response:

   XML data

Error Codes for the Okta API

...

The Client ID and Client Secret need to be updated on a yearly basis. The CTRP team will provide the Contact the CTRP Support to obtain a new Client ID / Client Secret combination to PRS two weeks before each update. During the two-week grace period, both old and new credentials will work.

Test Site

https://trials-stage.nci.nih.gov/services/trials/

Error Codes for the Okta API

...

Error

...

Code

...

Message

...

Invalid Client Id

...

401

...

{

    "errorCode": "invalid_client",

    "errorSummary": "Invalid value for 'client_id' parameter.",

    "errorLink": "invalid_client",

    "errorId": "oaejDJuWCiRTQeH8n6WG2116A",

    "errorCauses": []

}

...

Invalid Client Secret

...

401

...

{

    "error": "invalid_client",

    "error_description": "The client secret supplied for a confidential client is invalid."

}

...

Invalid User Credentials / Account Locked*

...

400

.

CTRP REST services

See the following for additional details on the various CTRP web services: 

• NCI CTRP Trial Registration REST Service Guide
• NCI CTRP Accrual REST Service Guide
• NCI CTRP Participating Site REST Service Guide

{

    "error": "invalid_grant",

    "error_description": "The credentials provided were invalid."

...