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:

Onboarding

The following are the recommended onboarding steps to using this document:

For NIH internal users

  1. Create a ServiceNow request.
  2. Go to CIT Enterprise Services (For IT Professionals).
  3. Select New NIH Login Service request and provide the scope, redirect Uniform Resource Identified (URI) and all required information.
  4. Submit ticket.
  5. The ticket will be assigned to an NIH Login OIDC administrator who will complete the client registration for the user/institution in the development (DEV) environment.
  6. The client ID and client secret will be provided to the user/institution for integration testing.

For non-NIH users

  1. Request a sponsor at NIH to create a ServiceNow request on your behalf.
  2. The sponsor must follow the steps outlined above for NIH internal users.

Note: The Virtual IP (VIP) URLs for testing and go-live will be provided by secure communication.

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
/openid/connect/v2/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, GA4GH AAI OIDC RFC.

FISMA, NIST & GA4GH Compliance

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.

Additionally, 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.

RAS Visa Compliance

When the client application initiates an authorization request with RAS, user authentication and consent is obtained following the standard OIDC flow: RAS issues a root access token (OIDC access token). The root access token does not feed client workflows, Data Repository Service (DRS), or clearinghouses.

  • The root access token SHOULD only be used by the client applications to get the RAS Passport and Visa (Embedded Access Token).
  • The root access token MUST NOT be passed down the chain of token flow.
  • The root access token MUST NOT be passed by the client to any downstream application.
  • The RAS-signed Visas containing the authorizations SHOULD be used to provide user entitlements to downstream applications.
  • The root access token MUST NOT be used for access to DRS endpoints. Instead, a different token - the target "resource" of the root access token - or another token derived from it, should be passed by the client. The RAS Visa (the target resource of the root access token) therefore can be used to access a DRS server.
  • The RAS Visas MUST NOT be used to request a new Visa or refresh a Visa.
  • The root access token SHOULD be used to request a new/refreshed RAS Visa.
  • The RAS Visa, like all Visas, cannot be altered by any intermediary entity.
  • A RAS Visa may be repackaged within another Passport or omitted from a Passport but cannot be altered in any way.
  • The Passport SHOULD be sent as a POST request or in the Header to access the DRS Server.

Testing Considerations

Development

To engage in development testing with NIH RAS, the following steps must be adhered to:

  1. When using the authorize request, the scope parameter must include “openid” in order to get an ID Token returned.
  2. ID Tokens returned from RAS should be checked to ensure secure delivery and validity.
  3. Profile, phone, and email information should be retrieved via the “userinfo” request.
  4. To comply with GA4GH, only the following signing algorithm will be supported: RS256.
  5. 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:

  1. ServiceNow request was raised for the integration in a non-production environment
  2. Integration was successfully implemented in the lower environment
  3. End-to-end testing was successfully completed
  4. Documented test results or summary was provided to the IAM OIDC team showing successful Integration and User Acceptance Testing
  5. A ServiceNow request was raised for the Production deployment
  6. 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"
}

Authenticate ID Token Payload Sample (non-GA4GH)

{
  "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"
}

UserInfo Response Sample (Scopes: openid email profile ga4gh_passport_v1 {decoded})

{
  "sub":"Ei4sFoHQ1KO-E2LAK13XWmT0fB5KfUOLS6HgwLUYqZ0",
  "name" : "John Doe",
  "preferred_username":"johndoe@era.nih.gov",
  "UserID":"johndoe",
  "email" : "john.doe@nih.gov",
  "ga4gh_passport_v1": [{
	"iss": "https://stsstg.nih.gov",
	"sub": "Ei4sFoHQ1KO-E2LAK13XWmT0fB5KfUOLS6HgwLUYqZ0",
	"iat": 1593396168,
	"exp": 1593439368,
	"scope": "openid email profile ga4gh_passport_v1",
	"jti": "40d91a9a-1ee3-4007-bf63-631c737bb863",
	"txn": "U9xWWGpMGEo=.f3fd16565ea86e66",
	"ga4gh_visa_v1": {
		"type": "https://ras.nih.gov/visas/v1",
		"asserted": 1593396168,
		"value": "https://stsstg.nih.gov/passport/dbgap/v1.0",
		"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": "2022-01-01 00:00:00"
		},
		{
			"consent_name": "General Research Use",
			"phs_id": "phs000006",
			"version": "v1",
			"participant_set": "p1",
			"consent_group": "c1",
			"role": "pi",
			"expiration": "2022-01-01 00:00:00"
		}
	]
  }]
}

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.