Three horizontal lines stacked

Documentation

Earthdata Login OAuth/SSO Client Implementation

This page documents the implementation of a Earthdata Login OAuth/SSO client. The steps detailed here assume that a Earthdata Login client application has been created and configured, and its UID, Client ID, Password and Redirect URL are known.

For this documentation, we will pretend we have an application with the uid: test_app, client_id: 123456, password: Password123!, and redirect_uri: http://mywebsite.nasa.gov

Authentication Process

Following are the steps involved in the Authorization Code Grant OAuth2 flow that Earthdata Login uses to provide SSO capabilities.

Request Authorization Code

The client application requests an authorization code from the OAuth provider (in our case, Earthdata Login) by constructing a URL of the following form:

      https://[urs-host]/oauth/authorize?client_id=[your client id]&redirect_uri=[the client app's OAuth callback page]&response_type=code
    

For our test application, the link would therefore look like:

      https://urs.earthdata.nasa.gov/oauth/authorize?client_id=123456&redirect_uri=http%3A%2F%2Fmywebsite%2Enasa%2Egov&response_type=code
    

Ensure that all of the parameters are properly URL-encoded. Substitute sit.urs.earthdata.nasa.gov or uat.urs.earthdata.nasa.gov for urs.earthdata.nasa.gov if deploying to an environment other than production.

You should provide this URL to the user as a clickable link or in a 302 redirect response from your application. This will route the user through the next step, Login and Application Authorization.

(Optional) The 'state' parameter

There is an additional query parameter that can be specified at this point, named state. This parameter has no meaning to the OAuth provider, and will be returned unchanged along with the authorization code once the user has authorized the client application. This can be useful if the client app needs to, for example, redirect the user to the last page they were on upon completion of the OAuth authorization process. If this parameter is provided, ensure that it is properly URL-encoded and decoded as needed.

Login and Application Authorization

The user's browser, upon navigating to the authorization URL constructed above, will (if the user is not already logged into 'Earthdata Login') request the user's credentials, and then (if the user has not previously authorized the specific client application) ask the user whether they want to allow the client application to access their profile information.

When the user selects to authorize the application, Earthdata Login will redirect the user's browser to the client application's registered redirect URL.

Request Access Token

After authorizing a client application, the user's browser will navigate to the registered redirect URL, with a query parameter code containing the authorization code. The client application must receive this code and use it to request an access token, by sending a POST request to the URL:

      https://urs.earthdata/nasa/gov/oauth/token
    

(Again, substitute sit.urs.earthdata.nasa.gov or uat.urs.earthdata.nasa.gov as needed).

This request should be secured using HTTP Basic Auth, where the username is the client application's UID, and the password is the client application's password.

Additionally, the following parameters should be provided in the POST body as media type application/x-www-form-urlencoded:

  • grant_type
    authorization_code
  • code
    The code that was provided as a query parameter
  • redirect_uri
    The client application's registered Redirect URL. This MUST match the redirect_uri that was provided in the authorization URL (see Request Authorization Code, above).

So for our test application, if we got a code of ABCDEFG, the request would look like:

        POST /oauth/token
        Host: urs.earthdata.nasa.gov
        Authorization: Basic dGVzdF9hcHA6UGFzc3dvcmQxMjMh
        Content-Type: application/x-www-form-urlencoded

        grant_type=authorization_code&code=ABCDEFG&redirect_uri=http%3A%2F%2Fmywebsite%2Enasa%2Egov
    

Our response will have the following fields in JSON format:

  • access_token
    The access token to be used for subsequent requests (more below).
  • token_type
    "Bearer"
  • expires_in
    Number of seconds that the access token is valid for. After the expiration is reached, the refresh token can be used to request a refreshed access token with the expiration advanced (more below).
  • refresh_token
    A secondary token that can be used to extend the lifetime of an access token.
  • endpoint
    A path of the form /api/user/{username}; this is the path to the REST resource representing the currently logged-in user.

For example, our response could look like this:

      {
        "access_token":"6c563343432ab3c21a1629549f108a47f3c66d8aa6fbb69c4c2519d911d346fc",
        "token_type":"Bearer",
        "expires_in":3600,
        "refresh_token":"9d576c63932b7ea375b43878822d0ec44dcd433fa6bdde2b55c07795c0c8ba78",
        "endpoint":"/api/users/astronaut"
      }
    

Retrieve User Profile Info

In addition to the access token itself, the client application should have received a field named endpoint containing the path to a REST resource on the Earthdata Login API. This is a server-relative URL, which should be appended to the address of the Earthdata Login server in the appropriate environment. To retrieve the user's profile information, your client application must send a GET request to this URL with an "Authorization" request header set to "Bearer {{your access token}}". The response will contain user profile details in JSON format, including the users uid, which can be used to uniquely identify them in your application.

(Optional) Request Refreshed Access Token

If the access token that you received has expired or is about to expire, you can request a new one by sending a POST request to:

      https://urs.earthdata.nasa.gov/oauth/token
    

With the following application/www-form-urlencoded parameters:

  • grant_type
    refresh_token
  • refresh_token
    The refresh token that was returned in the Request Access Token step

As above, this request must be secured using HTTP Basic Auth with the client application's UID and Password.

The response to this request will have the same structure as was received in Request Access Token, though both the access_token and the refresh_token parameters will have changed. The previous tokens are no longer usable at this point.