OAuth Overview

Application Authentication

Application Authentication

In order to access any protected Rally APIs, the application developer needs to authenticate to Rally with the username and password that was used to create the developer account on the rally.io site.

Application Register

The App is responsible for securely storing and handling these tokens.

The access token can then be used to access the Rally secure APIs and has a lifetime of one hour.

After this hour, a new access token must be obtained either by submitting the credentials again or using the refresh token. The refresh token has a much longer lifetime than the access token.

Both tokens must be handled with care and should be considered sensitive data. If persisted, they must be persisted in a secure way.

The Rally endpoint for the register call is /v1/oauth/register

Refreshing token

The Application submits its refresh token to the Rally server. The server validates the refresh token and returns a new access token.

The Rally endpoint for refreshing the access token is /v1/oauth/refresh

User Authorizes Application

Authorization Flow

The authorize flow requires the App to be registered and it requires the App to present a valid access token.

  1. The user initiates the authorization flow from the App UI

  2. The App BE POST an authorize request to the Rally

  3. The Rally sends a login-form URL as response to the authorize call to the App. It validates that the App presented a valid access token.

  4. The App sends a redirect to this login-URL to its UI

  5. The user enters their credentials and submit the form to Rally

  6. Upon successful authentication, Rally sends a redirect to continue the authorization flow to the authorization step

  7. The user authorizes the Application and submits the authorize form to Rally

  8. Rally process the authorization and redirects the user to the App redirect URL. That URL will have a query parameter “code”

  9. The App BE, in the callback handler, uses that code to invoke the userinfo endpoint of the Rally BE

  10. The Rally BE validates the provided code and returns userinfo of the authenticated user to the App

  11. The callback handler can return a response to the user

Sample App

This is a Sample App (NodeJs) showing how to register, refresh token and initiate an Authorization flow with the Rally IO OAuth service.

https://github.com/starcard-org/rally-io-oauth-sample-app