Researcher Auth Service (RAS) Project Service Offerings
Getting Started
This document explains the authentication, authorization, and logging services available to NIH Institutes and Centers and extramural systems desiring information about users requesting to access NIH’s open and controlled data assets and repositories through the NIH Researcher Auth Service (RAS).
The intended audience for this document is technical developers and leaders responsible for design and implementation of the integrations with the RAS APIs.
Prerequisites
The following are the recommended prerequisites to using this document:
- Familiarize with the OAuth 2.0 Specification, RFC 6749.
- Familiarize with the OpenID Connect 1.0 Specifications.
- Familiarize with the JSON Web Token (JWT) specification, RFC 7519 and understanding of claims and tokens.
- Familiarize with Global Alliance for Genomics & Health (GA4GH) Passport Specifications.
- Familiarize with GA4GH Authentication and Authorization Infrastructure.
Available API endpoints
The following table illustrates the OAuth 2.0 and Open ID Connect 1.0 endpoints which are available for testing:
API Endpoint | Purpose | Reference |
---|---|---|
/auth/oauth/v2/authorize | Initiate process to allow resource owner to permit client access | OAuth 2.0 |
/auth/oauth/v2/authorize/login | Prompts resource owner to login before permitting client access | OAuth 2.0 |
/auth/oauth/v2/authorize/consent | Prompts resource owner to allow or deny client access | OAuth 2.0 |
/auth/oauth/v2/token | Processes the token issuance step | OAuth 2.0 |
/auth/oauth/v2/token/revoke | Revokes an issued token | OAuth 2.0 |
/openid/connect/v1/userinfo (deprecated - date 3/31/2022) |
If presented with a valid access token, returns claims about the requested user | OIDC 1.0, GA4GH Passports Spec, GA4GH AAI OIDC RFC. |
/openid/connect/v1.1/userinfo | If presented with a valid access token, returns claims about the requested user | OIDC 1.0, GA4GH Passports Spec, GA4GH AAI OIDC RFC. |
/connect/session/logout | Terminates the current Open ID active session | OIDC 1.0 |
/openid/connect/jwks.json | Used to publish the JWK set public keys used by clients to validate a JSON Web token (JWT). | OIDC 1.0 |
/.well-known/openid-configuration | Used to retrieve metadata about the RAS OpenID Connect configuration. | OIDC 1.0 |
Available Identity Providers (IdP)
RAS currently offers the following IdPs as authentication sources for researchers accessing an integrated system:
- NIH Active Directory Identity Assurance Level (IAL) 3 identity that is authenticated at Authenticator Assurance Level (AAL) 3 when using NIH issued PIV card. First name, last name and email address are available.
- eRA Commons IAL1 identity that is authenticated at AAL1. First name, last name and email address are available. Role and affiliation information from eRA is available if needed.
- Login.gov Options to require IAL 1 and 2 are available along with various multi factor authentication options. Email address is available at IAL1; first and last name at IAL2.
- InCommon Federation Individuals from U.S. and international research institutions that participate in this federation (https://auth.nih.gov/CertAuthV3/forms/compliancecheck.aspx) can use their home institution credentials. Options for various Identity Assurance Profiles (IAP – https://wiki.refeds.org/display/ASS/REFEDS+Assurance+Framework+ver+1.0) are available with multi-factor authentication (MFA). First name, last name, email address, and organization are available.
Requests for RAS to integrate additional IdPs should be included with system integration requirements and will be considered by the project team.
Note: The different IAL and AAL levels are defined by the National Institute of Standards and Technology in NIST Special Publication 800-63.
Compliance and Security FAQs
The National Institutes of Health’s (NIH) Office of Data Science Strategy (ODSS) is committed to continuous improvement of partner engagement with the Researcher Auth Service (RAS). The purpose of the FAQ site is to ensure that all RAS partners understand and are applying the appropriate NIH Chief Information Security Officer approved best practice security requirements.
Please refer to this site regularly for updates to frequently asked questions (FAQs) from RAS partner systems. (Last updated: April 6, 2022)
- Which security and other standards frameworks does RAS follow?
- RAS is part of the NIH CIT IAM General Support System (GSS) which is a Federal Information Security Management Act (FISMA) High system. As such, RAS will adhere to NIST (National Institute of Standards and Technology) 800-53 and 800-57 guidelines pertaining to configuration management, least privilege, and cryptographic key establishment & management.
- For authentication processing, RAS will comply with the Global Alliance for Genomics and Health (GA4GH) approved specifications for packaging “passport claims” and “passport visas” as detailed in the GA4GH Passports and Authentication and Authorization Infrastructure specifications.
- Will all our system users have to log in with RAS?
- Yes - Once a partner system is using RAS to access NIH controlled access data, their users will be required to log-in via RAS with a supported identity provider to access those data.
- Can we link user accounts from RAS with non-RAS accounts?
- No – Partner side linking of non-RAS IdP accounts to RAS accounts is prohibited. In order to maintain authentication method and ID proofing security controls, RAS tokens currently can only be released based upon RAS authentication.
- Can we repackage RAS visas into a non-RAS passport, and use those passports for access to NIH data?
- No - RAS Visas must not be repackaged into a Passport issued by any other broker. The integrity of the RAS passport, and the ability to validate passport-level claims and visa tokens, are critical aspects of the overall RAS security model.
- How can we trust an external system that requests data using a RAS passport?
- Trust is established with NIH Approved third party Certificate Authority (CA) certifications that facilitate client/server mutual authentication in order to securely exchange the RAS passport.
- How do we know that we’ve been presented with a real RAS passport?
- A RAS Clearinghouse verifies the Passport being presented is a real RAS Passport by verifying that the issuer is NIH and that it has been signed by NIH RAS. Currently, existing and new partners create their own RAS Clearinghouses using NIH-supplied instructions in the Interconnection Security Agreement (ISA). These RAS Clearinghouses will be subject to testing and ongoing inspection to ensure NIH contractual compliance.
Testing Considerations
Development
To engage in development testing with NIH RAS, the following steps must be adhered to:
- When using the authorize request, the scope parameter must include “openid” in order to get an ID Token returned.
- ID Tokens returned from RAS should be checked to ensure secure delivery and validity.
- Profile, phone, and email information should be retrieved via the “userinfo” request.
- To comply with GA4GH, only the following signing algorithm will be supported: RS256.
- Only the following encryption algorithm will be supported: RSA.
Production
The following steps should have been completed prior to promoting an integration with RAS into Production:
- ServiceNow request was raised for the integration in a non-production environment.
- Integration was successfully implemented in the lower environment.
- End-to-end testing was successfully completed.
- Documented test results or summary was provided to the IAM OIDC team showing successful Integration and User Acceptance Testing.
- A ServiceNow request was raised for the Production deployment.
- Production deployment planning activities (date/time of rollout, shakeout activities and responsibilities and production support plan) were discussed and agreed to with the IAM OIDC team at least a week prior to the planned go-live date.
Appendix A. OIDC Token Exchange Samples
Authentication Response Sample
{ "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImRlZmF1bHRfc3NsX2tleSJ9.ew0KICAiaXNzIjogImh0dHBzOi8vZmVkZXJhdGlvbmRldi5uaWguZ292OjQ0MyIsDQogICJpYXQiOjE1NzYxNzYwNzEsDQogICJhdWQiOiI1ZWVkODY4ZS03YWQwLTQxNzItODhmMi03MDRiY2Y3OGI2MWUiLA0KICAiZXhwIjoxNTc2MTc5NjcxLA0KICAianRpIjoiNDA1NWE4Y2ItNTVlNC00YmQyLTkyYWEtYjVhOWM5YWM0NjEyIiwNCiAgInRva2VuX2RldGFpbHMiOiB7DQogICAgInNjb3BlIjoicGhvbmUgZW1haWwgYWRkcmVzcyBwcm9maWxlIG9wZW5pZCIsDQogICAgImV4cGlyZXNfaW4iOjM2MDAsDQogICAgInRva2VuX3R5cGUiOiJCZWFyZXIiLA0KICAgICJwcmVmZXJyZWRfdXNlcm5hbWUiOiJyb2JpbnNvbmpld0BuaWguZ292IiwNCiAgICAibmFtZSIgOiAiQWJoaXNoZWsgQmFqcGFpIiwNCiAgICAiZW1haWwiIDogImFiLmJhanBhaUBuaWguZ292IiwNCiAgICAiVUlEIiA6ICJhYi5iYWpwYWlAbmloLmdvdiINCiAgfQ0KfQ.LNhOk4cW16VP48PZqa5vV23KcLl9mCzsQdmtZzB3XFLSlj7kEaJNde07Bu4pqnrWuLMTilIjwZIy1P389aZwDCfVHUlLf9sBUAZSID8ug-Pdgnso7gBaALhSrztGGQ7GYsg4UAKs9XNDEgXaHJ5yCbxxOFusNTFX3LMwYMkKAgMPpYyexAZMpB__AAPfqqR4FWN6-OWs7vJhBbRcfNFAS_7WrJ-bQtc4i1HYFfowOrfooJ0Q3e9JcQJvVpuln_0eB_y9_KlMsv0LkWNbKbPM26dz5nvled1s6i6U8BxafYlz7F-1p8aF31P4AVz3iPDbW6dxbWaw79aWwBHLaVEg", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "63cba819-aa3d-4492-a02e-a48ca3040xxx", "scope": "phone email address profile openid", "id_token": "eyH0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImRlZmF1bHRfc3NsX2tleSJ9.ewogInNYiI6ICJoek8zRGtKLTNDSXVqSTFob3F1RU5ITEtiRUJVNkxXLW9VR0hMWXBwN2M0IiwKICJhdWQiOiAiNWVlZDg2OGUtN2FkMC00MTcyLTg4ZjItNzA0YmNmNzhiNjFlIiwKICJjX2hhc2giOiAiZlhLSnlfTzB1bk NEeHo4MXgyUGNZZyIsCiAiYWiMbCgyPl0-JLN62_UJTh0uZFP2xNlo0fqc5wYxHS7YoGU26xakrcMGRXJZpbZHSwofZ5x5K7h3_dMM5y_KEDoiytlG8mQFjD6w3bCmQKsiMfvDVC0rRzBrVbZjzk7r3daJFbw6S0gxt3BObNmfmBHXlEQBH0QY2lVN7AupmFOpOLgmRcqQpRKaAeXS6fwPHRVPFl4_g6_hSq-A0s7ZZx7O1u7SlFblEIvTUpZF8QIACvhfNroPmFqZYpldtMLmHN5ZO3eRsIfmRm6EeVnXbucyihRhcJTapX3--ypl5mStfGRiyAw7qEa3ju1tK58Bje8w", "id_token_type": "urn:ietf:params:oauth:grant-type:jwt-bearer" }
ID Token Payload Sample
{ "sub": "BPO3DkJ-3CIujI1hoquENHLKbEBU6YY-oUGHLYpp7xx", "aud": "6ffd868e-7ad0-4172-88f2-704bcf78b6ff", "c_hash": "fYMJy_O0unCDxz81x2PcYg", "acr": "0", "azp": "5eed868f-7ad0-4172-88f2-704bcf78b6ff", "auth_time": 1276176058, "iss": "https://fqdn.gov", "exp": 1226262466, "iat": 1226176072, "nonce": "000000000" }
Version 1.1 UserInfo Response Sample with Encoded Passport
(Scopes: openid email profile federated_identities ga4gh_passport_v1){ "sub": "ROcDp0JG4LxZrU7bjBjyzXO_jiv-AWYDrkKDPitt-Xo", "name": "JohnDoe", "preferred_username": "Doej_pi@era.nih.gov", "userid": "Doej_pi", "email": "John.Doe@nih.gov", "federated_identities": { "default_identity": "Doej_pi@era.nih.gov", "authenticated_identity": "Doej_pi@era.nih.gov", "sources": [{ "login.gov": { "identity_username": "03de52c8-194c-4eae-915f-1de3a34206f0@login.gov", "ial": 1 }, "era": { "identity_username": "Doej_pi@era.nih.gov", "ial": 1 } }], "identities": [{ "login.gov": { "userid": "03de52c8-194c-4eae-915f-1de3a34206f0", "mail": "John.Doe@nih.gov" }, "era": { "mail": "John.Doe@nih.gov", "firstname": "John", "lastname": "Doe", "userid": "Doej_pi" } }] }, "txn": "68f70cf32eed4e64.96ae81a37b343b9a", "passport_jwt_v11": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImRlZmF1bHRfc3NsX2tleSJ9.ew0KInN1YiI6IlJPY0RwMEpHNEx4WnJVN2JqQmp5elhPX2ppdi1BV1lEcmtLRFBpdHQtWG8iLA0KImp0aSI6Ijc1YzRmNmZkLTc0NmUtNGEyMi1iZjBhLTM0NTg3ZGNiZDhmOCIsDQoic2NvcGUiOiJvcGVuaWQgZ2E0Z2hfcGFzc3BvcnRfdjEiLA0KInR4biI6IjY4ZjcwY2YzMmVlZDRlNjQuOTZhZTgxYTM3YjM0M2I5YSIsDQoiaXNzIjogImh0dHBzOi8vc3Rzc3RnLm5paC5nb3YiLCAKImlhdCI6IDE2MjkyMzA1NjQsCiJleHAiOiAxNjI5MjczNzY0LAoiZ2E0Z2hfcGFzc3BvcnRfdjEiIDogWyJldzBLSUNBaWRIbHdJam9nSWtwWFZDSXNEUW9nSUNKaGJHY2lPaUFpVWxNeU5UWWlMQTBLSUNBaWEybGtJam9nSW1SbFptRjFiSFJmYzNOc1gydGxlU0lOQ24wLmV3MEtJQ0FpYVhOeklqb2dJbWgwZEhCek9pOHZjM1J6YzNSbkxtNXBhQzVuYjNZaUxBMEtJQ0FpYzNWaUlqb2dJbEpQWTBSd01FcEhORXg0V25KVk4ySnFRbXA1ZWxoUFgycHBkaTFCVjFsRWNtdExSRkJwZEhRdFdHOGlMQ0FOQ2lBZ0ltbGhkQ0k2SURFMk1qa3lNekExTmpRc0RRb2dJQ0psZUhBaU9pQXhOakk1TWpjek56WTBMQTBLSUNBaWMyTnZjR1VpT2lBaWIzQmxibWxrSUdkaE5HZG9YM0JoYzNOd2IzSjBYM1l4SWl3TkNpQWdJbXAwYVNJNklDSXhNMlkyT1dNMk5pMDBOMlExTFRRNE9EQXRZak15TVMxaVlqQTRORFUwWW1FellUY2lMQTBLSUNBaWRIaHVJam9nSWpZNFpqY3dZMll6TW1WbFpEUmxOalF1T1RaaFpUZ3hZVE0zWWpNME0ySTVZU0lzRFFvZ0lDSm5ZVFJuYUY5MmFYTmhYM1l4SWpvZ2V5QU5DaUFnSUNBZ0luUjVjR1VpT2lBaWFIUjBjSE02THk5eVlYTXVibWxvTG1kdmRpOTJhWE5oY3k5Mk1TNHhJaXdnRFFvZ0lDQWdJQ0poYzNObGNuUmxaQ0k2SURFMk1qa3lNekExTmpRc0RRb2dJQ0FnSUNKMllXeDFaU0k2SUNKb2RIUndjem92TDNOMGMzTjBaeTV1YVdndVoyOTJMM0JoYzNOd2IzSjBMMlJpWjJGd0wzWXhMakVpTEEwS0lDQWdJQ0FpYzI5MWNtTmxJam9nSW1oMGRIQnpPaTh2Ym1OaWFTNXViRzB1Ym1sb0xtZHZkaTluWVhBaUxBMEtJQ0FnSUNBaVlua2lPaUFpWkdGakluMHNEUW9nSUNBZ0lDSnlZWE5mWkdKbllYQmZjR1Z5YldsemMybHZibk1pT2lCYkRRb2dJQ0FnSUNBZ0lDQU5DaUFnSUNBZ1hTQU5DbjAubHBFUG1pdVBzX0tpcURfazlfTUZoaXFWc3FnZnlEMVFIeHRVU2gwMWZFMVlGX2dTamR6N2pjTGVROVpzb09rT01wbktJcFowV0tsSmVrOFFEaE16VFpxRTJHektXRXdrUGl1NklSMTdxWDN0M2ZUVkw3TTBRTzNMVHZPNlg5NVNyVGVBU19ROHNyNzdEa2IxOVhmdDctS3NzLWFvcGlMVWFRRjJVZVBmNHhTTGxRWTZPaXlhSkJhakN3TnhpcUdhNTFvOE5KY1ppVGZ3YldseVJsT2ZSNzFhU010b0xiWWlOMlNwcTdlbWV0ZWJ1TklZSkhBeWpvcHJSTDRwYU1Nbm5pNnd2VUwybTY4UHFZcmJNaF9OMUFRV3oxVzgyUW5leXF6LWtzcHQ4YVhVenJKLURuRURWNVpwSHNyRUZ0ZGpLQzMxT0laNVlGcm51ZVhwcFhxWll3Il0NCn0.G8yl1J1y5r8kE7d9dlnwnZ2Ug6yupIVqYl8J-XjAMBbi2c-rKGjx753-cxM1rLDS8KeQ0QqsGRwh09yU7kMlgAQuoR9gmTRPJuGDAk_dp2_JjV5C0QgIdGMZQvOyvCY9tjb1C6O4LlcxJR7G7GQ9hu2pOVlzYg8kkkgVLlN6bpVxenNfv1v8xh1Xyq_HBc8nloTRyDBXUbrVcLGl5H5pexHyHUQ7idCEoIIpycfMsqYuuJH_vVy3H_6ruYwcefrgzitzOtib6LaCHLkzxwVHd5t-IO6R6XUYs5dp5jqVrlxjCA_AncOIrO-ZDg7vL4IrVWSpR5qd0-NLk4IZ1nvtzA" }RAS Passport Decoded with Encoded Visa
{ "sub": "ROcDp0JG4LxZrU7bjBjyzXO_jiv-AWYDrkKDPitt-Xo", "jti": "75c4f6fd-746e-4a22-bf0a-34587dcbd8f8", "scope": "openid ga4gh_passport_v1", "txn": "68f70cf32eed4e64.96ae81a37b343b9a", "iss": "https://stsstg.nih.gov", "iat": 1629230564, "exp": 1629273764, "ga4gh_passport_v1": ["ew0KICAidHlwIjogIkpXVCIsDQogICJhbGciOiAiUlMyNTYiLA0KICAia2lkIjogImRlZmF1bHRfc3NsX2tleSINCn0.ew0KICAiaXNzIjogImh0dHBzOi8vc3Rzc3RnLm5paC5nb3YiLA0KICAic3ViIjogIlJPY0RwMEpHNEx4WnJVN2JqQmp5elhPX2ppdi1BV1lEcmtLRFBpdHQtWG8iLCANCiAgImlhdCI6IDE2MjkyMzA1NjQsDQogICJleHAiOiAxNjI5MjczNzY0LA0KICAic2NvcGUiOiAib3BlbmlkIGdhNGdoX3Bhc3Nwb3J0X3YxIiwNCiAgImp0aSI6ICIxM2Y2OWM2Ni00N2Q1LTQ4ODAtYjMyMS1iYjA4NDU0YmEzYTciLA0KICAidHhuIjogIjY4ZjcwY2YzMmVlZDRlNjQuOTZhZTgxYTM3YjM0M2I5YSIsDQogICJnYTRnaF92aXNhX3YxIjogeyANCiAgICAgInR5cGUiOiAiaHR0cHM6Ly9yYXMubmloLmdvdi92aXNhcy92MS4xIiwgDQogICAgICJhc3NlcnRlZCI6IDE2MjkyMzA1NjQsDQogICAgICJ2YWx1ZSI6ICJodHRwczovL3N0c3N0Zy5uaWguZ292L3Bhc3Nwb3J0L2RiZ2FwL3YxLjEiLA0KICAgICAic291cmNlIjogImh0dHBzOi8vbmNiaS5ubG0ubmloLmdvdi9nYXAiLA0KICAgICAiYnkiOiAiZGFjIn0sDQogICAgICJyYXNfZGJnYXBfcGVybWlzc2lvbnMiOiBbDQogICAgICAgICANCiAgICAgXSANCn0.lpEPmiuPs_KiqD_k9_MFhiqVsqgfyD1QHxtUSh01fE1YF_gSjdz7jcLeQ9ZsoOkOMpnKIpZ0WKlJek8QDhMzTZqE2GzKWEwkPiu6IR17qX3t3fTVL7M0QO3LTvO6X95SrTeAS_Q8sr77Dkb19Xft7-Kss-aopiLUaQF2UePf4xSLlQY6OiyaJBajCwNxiqGa51o8NJcZiTfwbWlyRlOfR71aSMtoLbYiN2Spq7emetebuNIYJHAyjoprRL4paMMnni6wvUL2m68PqYrbMh_N1AQWz1W82Qneyqz-kspt8aXUzrJ-DnEDV5ZpHsrEFtdjKC31OIZ5YFrnueXppXqZYw"] }RAS Visa Decoded
{ "iss": "https://stsstg.nih.gov", "sub": "ROcDp0JG4LxZrU7bjBjyzXO_jiv-AWYDrkKDPitt-Xo", "iat": 1629230564, "exp": 1629273764, "scope": "openid ga4gh_passport_v1", "jti": "13f69c66-47d5-4880-b321-bb08454ba3a7", "txn": "68f70cf32eed4e64.96ae81a37b343b9a", "ga4gh_visa_v1": { "type": "https://ras.nih.gov/visas/v1.1", "asserted": 1629230564, "value": "https://stsstg.nih.gov/passport/dbgap/v1.1", "source": "https://ncbi.nlm.nih.gov/gap", "by": "dac" }, "ras_dbgap_permissions": [{ "consent_name": "General Research Use", "phs_id": "phs000298", "version": "v4", "participant_set": "p3", "consent_group": "c2", "role": "pi", "expiration": 1226262466 }, { "consent_name": "General Research Use", "phs_id": "phs000006", "version": "v1", "participant_set": "p1", "consent_group": "c1", "role": "pi", "expiration": 1226262466 } ] }
Appendix B. Glossary
Term | Explanation |
---|---|
Access Token | A unique value used to grant and request authorization to protected resources. |
API Gateway | A server that acts as a front-end receives API requests, enforces API usage policy, controls access, collects statistics, etc. |
Claim | A unique name/data pair describing information according to the RFC 7519 specification. |
Client | An application making protecting resource requests on behalf of the resource owner (RFC 6749). |
DRS | Data Repository Service. A system which provides data to consumers and conforms to the DRS specifications. |
Embedded token |
There are two types of embedded tokens: Embedded Access Tokens and Embedded Document Tokens. Embedded Access Tokens are claims in a Broker’s token that can then be sent to OTHER brokers’ /userinfo endpoints for further user claims. In GA4GH Passports, embedded access tokens will usually carry full claims so as not to interrogate /userinfo each time. Embedded Document Tokens cannot be revoked and no /userinfo endpoint is provided for them, however they still offer a signature that can be used to verify their provenance and always contain the necessary claims in them already. |
FISMA | Federal Information Security Management Act. |
GA4GH Claim | A JWT claim as defined by a GA4GH documented technical standards. |
ID Token | A token containing claims about the identity of a person. |
JWT | According to RFC 7519, a JWT is a “JSON Web Token”, a compact means of representing claims. |
OAuth | An Authorization framework enabling third-party access on behalf of a resource owner to a protected resource (RFC 6749). |
OIDC | An acronym for OpenID Connect, a protocol which adds authentication and identity layer for OAuth 2.0. |
Partner Organizations | Partner systems integrating with RAS. |
Passport | A GA4GH-compatible access token (“GA4GH Access Token”), as per the GA4GH AAI specification, along with the Passport Claim that is returned from Passport Broker service endpoints using such an access token. |
Passport Claim | A claim conforming to the GA4GH AAI specification. |
Passport Visa | According to the GA4GH Passport specification, a Visa is embedded in a Passport Claim and provides access information pertaining to authorization. |
Refresh Token | A token used to request a new Access Token. |
Resource Owner | A person or other entity capable of granting access to a protected resource (RFC 6749). |
Resource Server | The server hosting the protected resource (RFC 6749). |
Appendix C. dbGaP Descriptions (Login Required)
Click here to find details on the different fields included in the RAS Database of Genotypes and Phenotypes (dbGaP).
Contact Us
For More Information: Please contact the NIH RAS Team.