Launchpad Authentication User's Guide

Overview

Currently, users must authenticate with their Earthdata Login information in order to ingest metadata into CMR.  NASA has mandated that CMR require users to authenticate using Launchpad (NASA's single sign-on service) in order to ingest new metadata, update existing metadata, or delete metadata from CMR.  This requirement holds true for users who use a browser-based interface like the MMT to ingest and manage metadata holdings, as well as users who ingest metadata programmatically through the CMR REST APIs.

ALL CMR ingest and MMT users will need to update their workflows to accommodate these changes.

This document outlines the process for migrating providers' ingest operations from Earthdata Login to Launchpad authentication for the CMR and the MMT. For information on setting up Launchpad authentication for Cumulus deployments, go here: Cumulus Launchpad Authentication

Timeline

The migration from URS to Launchpad Authentication will have three phases:

Phase 1:  Earthdata Login Only
All CMR ingest and MMT users can authenticate using Earthdata Login credentials, but cannot authenticate using Launchpad.

Phase 2:  Earthdata Login and Launchpad Both Enabled (Current Implementation)
During Phase 2, the MMT will offer users the option to authenticate with both URS and Launchpad credentials.  Similarly, the CMR REST APIs will accept both URS and Launchpad tokens for authentication during this time.  During this period, the CMR and MMT teams will communicate the full transition plan to our users.  It is our hope that during this phase, all users will undergo the steps necessary to enable Launchpad authentication for themselves, in preparation of Phase 3 when Earthdata Login credentials will no longer be accepted for CMR ingest requests and access to the MMT.

Phase 3:  Launchpad Authentication Only
When we transition to Phase 3, the MMT will stop offering users the ability to log in using their Earthdata Login credentials, and the CMR REST APIs will stop accepting Earthdata Login tokens for ingest requests.  All users must be fully compliant with the Launchpad Authentication process at this time, or you will not be able to ingest, update, or delete metadata using the CMR REST API or access the MMT.

Linking AUID and EDL Accounts

To authenticate to either MMT or to CMR using Launchpad credentials, each user will first need to submit a NAMS request for be permitted to authentication to CMR, then a MMT NAMS request to be permitted to ingest via MMT, if appropriate.

Once the NAMS requests are approved and your account has been provisioned, each user will need to link their Earthdata Login account to their Launchpad account.

Step 1:  Submit the CMR NAMS request

1. Go to idmax.nasa.gov and submit a request for "GSFC ESDIS CMR PROD (CLIPROD)". This request has a Level of Risk (LOR) of 20.
2. Enter your NASA AUID.
3. Enter your Earthdata Login ID.
4. Under Role, select Operator.
5. Confirm that CMR is an approved application in your Earthdata account.
6. Provide a Business Justification (for faster provisioning, include a note about which provider or group you work with).
   
7. Submit the request.

Step 2:  Submit the MMT NAMS request

1. Go to idmax.nasa.gov and submit a request for "GSFC ESDIS Metadata Management Tool (MMT)."  This request has a Level of Risk (LOR) of 20.
   
2. Enter your Earthdata Login ID.
3. Under Role, select Metadata Editor (if you are a DAAC Manager or will require the ability to set permissions and groups for provider data, select Provider Administrator).
   
4. Provide a Business Justification (for faster provisioning, include a note about which provider or group you work with).
5. Submit the request.  You will still be able to access the MMT using your EDL credentials while waiting for your NAMS requests to be approved and provisioned.

For ingest access in the SIT or UAT environments, separate NAMS requests must be submitted following the same process described in steps 1 and 2 above. The table below shows the NAMS requests required for all environments:

Step 3:  Link your MMT account with your Launchpad credentials

Once your CMR and MMT NAMS requests has been approved and your account has been provisioned, your Launchpad credentials can be used to access the MMT by selecting the "Login with Launchpad" button on the MMT home page:

After entering your Earthdata Login credentials, the MMT will then automatically associate your existing provider permissions with your Launchpad account. 

Launchpad Authentication via CMR REST APIs 

In order to successfully ingest metadata via the CMR REST APIs, your ingest client will need to provide CMR with a Launchpad Authentication token in the ingest request.  The exact method of procuring this token may vary based on how your provider's ingest client has been built, but we will attempt to provide some best practices and examples to help everyone become compliant.  Your provider will need a Service Account and a PKI Certificate in order to procure the Launchpad token, and we recommend that a single person with your provider be responsible for owning the Service Account and PKI Certificate.  We will refer to this owner as the Launchpad Champion in this documentation.

Every user in your provider who needs to ingest metadata will need to submit the following NAMS request for CMR Ingest access via Launchpad:

CMR NAMS request (This is the same process detailed above for MMT users - if you have completed this request already, you do not need to do it again)

1. Go to idmax.nasa.gov and submit a request for "GSFC ESDIS CMR PROD (CLIPROD)". This request has a Level of Risk (LOR) of 20.
2. Enter your NASA AUID.
3. Enter your Earthdata Login ID.
4. Under Role, select Operator.
5. Confirm that CMR is an approved application in your Earthdata account.
6. Provide a Business Justification (for faster provisioning, include a note about which provider or group you work with).
   
7. Submit the request.

In addition, to get the provider set up for ingest, your Launchpad Champion will need to take the following steps:

1. Create the token service Service Account for your provider:
   1. Go to idmax.nasa.gov and submit a request for “AGCY0031 Active Directory Service Account”
   2. Set the Asset Expiration Date as far in the future as allowed. IDMax will likely only allow you to request an expiration date one year into the future.
   3. Click +Add Service account.  Here, you'll need to set up a name for your service account according to the specified naming convention.  Your service account name must be "sv" followed by the two-letter code for your center ("gs" for GSFC, for example), followed by any string of numbers and letters you'd like.  If you enter at least five characters into the Search Service Accounts field, you can see what account names are already in use.  Just select any name that is not already being used.
   4. In the Business Justification field, enter the name of the "provider" you are representing and indicate that "this request is for Launchpad Authentication".
2. When your AGCY0031 Active Directory Service Account NAMS request has been fully provisioned, call NASA Enterprise Service Desk at 1-877-677-2123 (Option 2) and request to have the service account activated.  You will need to verify your identity and provide them with the name of the service account to be activated.  You will be given a temporary password for the service account.
3. Obtain a PKI Certificate, using the steps on the linked wiki page.  Note that you must have your Service Account created and activated before you can request the PKI Certificate.
4. Request Authorization to Authenticate with Launchpad:
   1. Go to https://idmax.nasa.gov and on the top menu under Credentials, choose “Manage Application Service Accounts”
   2. Choose Manage NCAD Service Accounts
   3. Select the account you want and click the “Request Role Access” for it
   4. Search for “Launchpad Token Service”
   5. Submit for the SiteMinder Token Service role

Once these setup steps are complete, you will have a PFX file and a passcode issued by the PKI group.  Your ingest client can then be configured to request a Launchpad token from the Token Service, which can be passed to CMR during your ingest request.  This will likely require code changes to your ingest client.  We've provided some code samples below that may help you make these code changes, and the CMR team is available to assist by email at cmr-support@earthdata.nasa.gov or by posting in the #cmr public channel on the EOSDIS Slack instance.

Example Code for Requesting Launchpad Token

Once you obtain a Launchpad token using your ingest client, that token can be passed to CMR in the request header in place of the Earthdata Login token you are currently passing.  Below is an example curl command to ingest a collection into the CMR UAT environment using your Launchpad token:

curl -i -XPUT -H "Content-Type:application/echo10+xml" -H "Cmr-pretty:true" -H "Expect:" -H "Authorization:  PTeS3MMKY9xtG4RlWGo[redacted]" https://cmr.uat.earthdata.nasa.gov/ingest/providers/PROV1/collections/coll1 -d @/Users/yliu10/coll1.xml

ICAM Helpdesk Ticket

Once you have successfully completed Launchpad setup and you have a verified workflow, for assistance with errors in Launchpad token creation or with the icam API endpoint generally, please create an Enterprise Service Desk ticket. For details see: ESD ICAM Helpdesk Request 2022.pdf