Rally WSAPI: Api Key and Oauth Client FAQ ( APIKey)
search cancel

Rally WSAPI: Api Key and Oauth Client FAQ ( APIKey)

book

Article ID: 11568

calendar_today

Updated On:

Products

Rally On-Premise Rally SaaS

Issue/Introduction

 

Frequently Asked Questions about authentication methods.

Environment

 

 

Resolution

  • API KEY FAQ:
    • When was API Key functionality introduced?
      • The week of April 14, 2014.
    • Does API Key work on-premises?
      • Api Keys are not supported on-premises. Only basic authentication (username/password) is supported. In addition to basic authentication, WS API POST/PUT/DELETErequests  also require security token that is valid per session.
    • Does API Key work on Sandbox?
      • Api Keys are not supported on sandbox.rallydev.com.
    • Can I use API Key instead of LoginKey?
      • API Keys cannot be used with legacy AppSDK1 apps.  AppSDK2 supports API Keys.
        However if you use the LoginKey to display Rally Standard Reports inside AppSDK2 apps it will not work.
    • Can certain users be blocked from generating API Key?
      • No. There is an "API Keys enabled" flag under "Admin Capabilities" section on Subscription tab. It can be toggled by a subscription administrator. This flag disables or enables API Key functionality for the entire subscription. There is no finer granularity that allows a selective enabling and disabling of access to API Key generation by users, roles or permissions. Any user with valid permissions can create an API Key. An editor can create a read-only API Key, but a viewer cannot create an API Key that allows writing.
    • How are revisions authenticated with API Key reflected in Revision History?
      • If a work item is modified via a script that is authenticated with ApiKey the Author of the Revision will point to the user whose ApiKey is used in the code. Revision History makes not distinction between revisions created by a user authenticated with username/password and revisions created by a user authenticated with API Key - both point to the same user account.
    • Do I  have to use a security token for POST and DELETE requests in addition to API Key?
      • No. Security token predates API Keys.  API Keys are easier to use and is not limited to one HTTP session.
      • Here are examples of curl commands that use API Key:
        • create example:
          curl --header "zsessionid:<API Key - include the underscore before the key>" -H"Content-Type: application/json" -d"{\"Defect\":{\"Name\":\"bad defect\",\"ScheduleState\":\"Custom 1\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/Defect/create
        • update example:
          curl --header "zsessionid:<API Key - include the underscore before the key>" -H "Content-Type: application/json" -d"{\"Defect\":{\"Resolution\":\"Not a Defect\",\"State\":\"Fixed\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/Defect/777
        • delete example:
          curl --header "zsessionid:<API Key - include the underscore before the key>" -H "Content-Type: application/json" -X delete https://rally1.rallydev.com/slm/webservice/v2.0/Defect/<Defect OID>
    • Should I use ApiKey or security token?
      • On-premises instances of Rally and sandbox.rallydev.com have no choice but to use security token (in combination with username/password). ApiKey is not supported in those environments.
      • On rally1.rallydev.com we recommend using ApiKey. ApiKey is more reliable and easier to use. It has been designed to overcome the challenges the security token often presents.
    • If using basic authentication (username/password) it will be necessary to use a Security Token for all POST(PUT,DELETE) requests require not only basic authentication (username/password) but also a security token.
      • In other words, a combination of username/password and a security token is required. Those security tokens expire with each HTTP session.
      • Obviously the browser maintains a session for you, so this is not an issue when using a browser REST client. But if you are hitting WS API create, update or delete endpoints outside of the browser, e.g. using CURL command you need to maintain the session yourself via a cookie. Otherwise the GET request to this endpoint: https://rally1.rallydev.com/slm/webservice/v2.0/security/authorize and a POST request to create or update an artifact constitute two separate requests. Appending a token generated by the first request to the second request will result in "Invalid key" when HTTP session is not maintained by the user.
      • ApiKey is designed to remove those difficulties:
        • ApiKey does not expire when HTTP session expires.
        • ApiKey is used on its own. It is not used in combination with username/password or in combination with security token. There is no need to hit /security/authorize endpoint prior to making POST requests.
    • Does API Key continue working when the associated user's password expires?
            • When SSO is enabled the password policy in the subscription settings will be ignored (except for those users on the exceptions list as expected)
            • ***If SSO is not enabled in the Rally Subscription, then the APIKey will not work if the password is expired for the associated user.  The password will need to be reset in order for the APIKey to work again.
              • Note:  if the user gets disabled in Active Directory but their Rally account is still set to active - while they won’t be able to login via the UI their API key will continue to function.  The admins will need to make sure the Rally account is also disabled or explicitly remove the API key from the subscription
    • What Rally API toolkits support API Keys?
    • Can I use ApiKey with a custom code where Rally API toolkits are not used?
      • Yes. For example, a java programmer may decide not to use a Rally toolkit and build a custom integration using org.apache.http.client. ApiKey may still be used for authentication by setting zsessionid header to it.
    • Does API Key work with SSO?
      • As of April 16, 2015 ApiKey works for users who exclusively authenticate via SSO. There is no longer a requirement to add api users to the exceptions list.
    • Here is an example that is using ApiKey in the environment that uses SSO.
      • The user whose ApiKey is used is NOT on the SSO exceptions list.
      • To make sure that credentials are not cashed we log out entirely and start an incognito session in the browser.
      • To confirm that credentials are not cached this WS API endpoint is pasted in the address bar of the browser: https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement.
        • A prompt to login comes up as expected:

    • We cancel. Error 401 appears as expected. So far we confirmed that credentials are not cached.
    • Next we start a browser REST client. In this example it is Firefox Poster. The same endpoint is used in URL box, and zsessionid header is set to ApiKey. The screenshot below shows success. TotalResultCount of this query happened to be 45960:




 

AUTHORIZED APPLICATION FAQ:

  • How is an authorized applications created (I don't see a create new option)?
    • The Authorized Applications section is referring to any Rally integrated application that has a 'Log in Using Rally' button. The best way to answer this question is with an example. The authorized application entry is created when you use the 'Login with Rally' button on any of the supported applications such as Salesforce.
    • Once you click on the 'Log in Using Rally' button it will create the entry under the Authorized Application tab under the Rally Application Manager (https://rally1.rallydev.com/login).
    • This functionality allows you to login to these integrated external applications in a more simplified way (no need to input a separate username/password). The Rally data that is being accessed is the session tokens used to login
  • Do I need to have an API Key first to create an authorized application? 
    • No, API keys are not needed and are not related to authorized applications. API keys that are created by a Rally user just impersonates that user to have access to the Rally WSAPI without the need to enter username and password. API keys are used in custom apps that need access to the Rally WSAPI. Only an active Rally user can create an API key. Once the user is inactivated in Rally this will also revoke the API key.
  • Can inactive user authorize application?
    • Only an active user in Rally can give authorization to applications using Rally to login. Once the user is inactivated and no longer has access to their Rally account then this will also revoke the access to the authorized application immediately.


Powered by Wolken Software