Frequently Asked Questions (FAQ)
Table of Contents
General
What's the difference between URS3 and Earthdata Login?
URS 3 is the term typically used to refer to all URS implementations prior to the current OAuth 2-based URS implementation. URS 3 applications used a fairly extensive REST API to interact with URS. While this allowed a lot of flexibility, it also meant that applications and websites were passing your username and password over the Internet. While this was typically done using secure connections, it's still not as safe as never passing your password around at all. While we've never had a report of stolen passwords resulting from use of URS 3, we do encourage all URS sites and applications to contact us about transitioning to Earthdata Login.
Earthdata Login is a completely reworked implementation of URS in terms of how applications interact with the system. Instead of focusing on a flexible API, Earthdata Login introduces OAuth 2. In this approach, applications redirect all users to Earthdata Login, and information (such as username, password, and email) is only entered directly into the Earthdata Login application. This ensures several things:
- Users can expect to trust a single system with their information: URS. While they can use lots of applications, only one is responsible for keeping up with their private personal information.
- Users can always expect to see a URS-branded page when entering sensitive information. If there's no URS branding, no information should be supplied!
- Applications don't have to receive and transmit sensitive user information, or worry about the overhead of secure networking. URS handles all this interaction now.
Earthdata Login does provide a simpler API for applications to request user information, but that API only responds to requests if the user has specifically granted that application permission to access their data. And passwords are never handed out to any system outside of URS!
Over the coming months, all EOSDIS systems that either currently use URS 3 or are candidates for URS interaction will be transitioned to Earthdata Login, ensuring your information is kept as safe and secure as possible.
What are all the user profile fields?
A complete list of the user profile fields:
- uid
- first_name
- last_name
- middle_initial
- email_address
- country
- user_type
- study_area
- organization
- affiliation
In addition, Earthdata Login provides the following fields on profile retrieval:
- registered_date
- authorized_date
These give the date on which the user created his/her user profile, and the date on which the application was authorized.
Which user profile fields are mandatory?
The mandatory user profile fields are:
- uid
- first_name
- last_name
- email_address
- country
- affiliation
API
What is the API?
The Application Programming Interface (API) is an HTTP based interface that allows applications to query the URS user profile database and to retrieve user profile information. Basic query functions provide the ability to query for users based on a wide range of parameters - first name, last name, email address, etc. Note that an application can only 'see' profiles of users that have granted that application access to their user profiles. Additionally, an application must authenticate with URS to obtain a security token before it can use the API.
How does my application authenticate itself?
Your application only needs to authenticate with URS if it plans on making use of the application programming interface (API). This is done with a simple HTTP post request, e.g.
curl -H "Authorization: Basic YXBwbGljYXRpb24gaWQ6cGFzc3dvcmQK" -d "grant_type=client_credentials" "https://uat.urs.earthdata.nasa.gov/oauth/token"
where the authorization code (in bold) is your registered application's username and password, separated by a colon, in base64 encoding. The result of a successful authentication is a token. This token can be used to make API calls.
How does my application retrieve a user profile?
Your application can only retrieve the profiles of users that have granted your application permission to access his or her user profile. Assuming this is the case, then your application can retrieve a user profile using an HTTP get request, e.g.
curl -H "Authorization: Bearer ed8494e19a4a1e842aa6aeeec0bd51579ed84658502600b26d8d09fc1565850" "https://uat.urs.earthdata.nasa.gov/api/users/peterlsmith"
where the token (in bold) is an authorization token that has been obtained either through application authentication, or user authentication. If the token was obtained via user authentication, then it will only allow your application to retrieve the user profile of the uesr that authenticated.
Applications
Is my favorite website/application using Earthdata Login?
If you are already using URS to log in to a website or application, and want to know if that site is using Earthdata Login, there are two easy ways to find out:
- Click the site's "Login" link or button. If you are taken to a site that says "URS" and the address in your web browser starts with "https://urs.earthdata.nasa.gov" then you're using a Earthdata Login system. This isn't foolproof, though, so if you don't see the URS header and URL, you can also...
- Contact the administrators of the site or application. This is the surest way to understand what version of URS is being used. Because URS does lots of things to make itself invisible to you–staying out of your way as much as possible–you may be using a Earthdata Login site and not see the URS login page often. That's why it's always good to ask.
The following are a few of the websites, tools, and applications that are currently using URS:
- Earthdata Website
- Earthdata Collaboration Environment
- Earthdata Code Collaborative and associated tools
- Alaska Science Facility
- LANCE Near Real-Time Data
Can I change the ownership of an application that I registered?
Yes - as the administrator of the application you registered, you can add other users to act as administrators of the application. They can, in turn, remove you as an administrator, and hey-presto! the ownership has been transferred - just as though he or she had registered the application in the firt place. Just log in to the URS, click on 'My Applications', and select the admin link (the one that looks like a person) for the appropriate application. This page will provide all the tools you need.
What is a redirection URL?
The redirection URL is the URL of a resource on your application web server that a user will be redirected to after authenticating with the URS. This resource is the one that will perform the token exchange needed to complete the user authentication, so it is usually a script (e.g. php/perl/python/etc). All redirect URLs MUST be registered with URS (a registered application can have more than one), and must be exact (no partial URLs allowed).
How do I delete an application?
To delete an application that you will no longer use:
- Login to your URS profile and navigate to your My Applications tab.
- Scroll down and beneath the Application Administration section on the My Applications page you will see all of the applications that you have created.
- Click the Circled "X" icon all the way to the right hand side next to the application that you would like to delete.
- You will be prompted "Are you sure you want to delete application?"
- Click OK.
- You will then see the page refresh and see a message at the top of the My Applications page stating "Application '' has been deleted". The application will also be removed from the list.
Integration
How do I disable the URS 'splash screen'?
The URS splash screen is the one that displays the 'Authenticating' message and has the rotating circle. This is displayed briefly after the user has authenticated, or if an application requests a user authentication while the user is already logged in to URS. This can be disabled using a 'splash=false' query parameter in the initial authentication redirect, e.g.:
https://urs.earthdata.nasa.gov/oauth/authorize?splash=false&response_type=code&client_id=<my-client-app-uid>&redirect_uri=<my-client-app-redirect-uri>
The splash screen may also be disabled by clearing the 'Redirect Time for URS Splash page' value on the application configuration page in URS.
How do I encode a username and password for HTTP basic authentication?
HTTP Basic authentication uses a base64 encoded string consisting of a username and password, separated by a colon. This can be done using Perl:
> perl -e 'use MIME::Base64; print encode_base64("<uid>:<pw>");'
where <uid> is the variable for your username and is your variable for your password.
If your username is "ABC" and your password is "abc123!" then your command should be like:
> perl -e 'use MIME::Base64; print encode_base64("ABC:abc123!");'
This follows in the other examples below.
or PHP:
> php -r 'echo base64_encode("<uid>:<pw>");'
or shell (if you have the base64 command installed):
> echo -n "<uid>:<pw>" | base64
Be careful if your password contains certain characters, such as $, @, or \ - these may need to be escaped when using these base64 encoding functions! You can verify the encoding using the same approach, but with the equivalent decode function - 'decode_base64', 'base64_decode', or 'base64 -d' for Perl, PHP, and shell respectively. If the output is not the same as the input - check for those special characters that need escaping!
How do I log a user out of URS?
There may be a situation where you wish to offer a user the opportunity to log out of both your application and URS at the same time. This cannot be done using an API call, but it can be done by issuing a redirection back to the user's browser (this is so that it requires an explicit action by the user, for example, clicking on a button or link). To do this, return a 302 status code with a location as follows:
https://urs.earthdata.nasa.gov/logout?redirect_uri=http://myserver.com/myapp/home
The redirect_uri query parameter is optional, and if provided, URS will send the user back to that location after logging them out of URS - for example, your application landing/home page. It is up to you as to whether your application terminates its own user session before redirecting the user to URS, or after the user is redirected back from URS. Note that when using the redirection feature, the user will not see any URS pages in their browser. For this reason, we recommend that any button or link that uses this feature makes it clear to the user that he or she will also be logged out of URS.
Single Sign-On
What is single sign-on?
We understand your confusion! This phrase is looking at the process from the user's perspective, and means that the user only has to enter their user name and password once, to gain access to multiple (different) applications.
In a typical web application scenario, a user would authenticate with the application he or she wishes to access by providing a username and password. Every time the user switches to using another application, he or she has to authenticate again (assuming any previous session has expired). Each web application needs it's own user database for storing usernames and passwords, and each user potentially needs to remember multiple username and password combinations.
With single sign-on, a third party authentication service (in this case the User Registration System) is used to perform the user authentication. The authentication service is responsible for making sure that the user is valid, and for providing credentials to the web application as a guarantee that the user is who they say they are. When the user switches to another application, that application also uses the authentication service. However, the authentication service already knows that the user is valid, and can provide the necessary credentials back to the application without the user needing to enter his or her username or password again.
One benefit of all of this is that the user never needs to provide their username and password to the web applications, only the authenticatiin service - the URS.
How does it work?
The overall OAuth2 process is beautifully described in the specification document. However, for mere mortals, we'd suggest our version that includes pictures!
Security
Is the information I give to URS really safe?
Yes, absolutely! First, URS is only available through an HTTPS connection. HTTPS is the secure version of HTTP, the protocol that web browsers use to talk to applications and websites. That alone makes it much harder for malicious users to try and steal your password or other private information.
Additionally, once your password is handed over to URS, we encrypt it immediately. That means that even URS administrators can't see your password; it just looks like a sequence of random numbers, letters, and symbols, even on the back end. And while the rest of your information is stored normally–as text that can be read by an administrator–it's never used without your permission, and it's never given out to other sites or applications without your explicit permission.
Finally, with Earthdata Login, only the URS system itself gets your password. That means that you'll never enter your password into a site that passes it over the network to Earthdata Login. This ensures that even in trusted communications between EOSDIS systems, your password is never exposed. If you're not sure if you're on a site that uses Earthdata Login, and gives you these advantages, you might want to read .
Apache URS Authentication Module
What is the Apache URS Authentication Module?
The Apache URS Authentication Module is an installable module for Apache httpd version 2.2 and later. It provides the ability to apply URS authentication to URLs handled by the web server, whether they are individual files, directories, or complete applications.
Where can I get the Apache URS Authentication Module?
The module can be downloaded from ECC using git:
git clone https://<username>@git.earthdata.nasa.gov/scm/aam/apache-urs-authentication-module.git urs
This will download the module source code into a directory 'urs'.
How do I build/install/configure the Apache URS Authentication Module?
A comprehensive guide to building, installing, and configuring the module can be found here (Note: this link in only accessible to app owners or administrators).