Configuring OAuth

This page provides a brief introduction to the OAuth protocol and Atlassian's implementation of this protocol. It also shows you how to use your Atlassian application's 'OAuth Administration' page.

On this page:

Introduction to OAuth

OAuth is a protocol that allows a web application such as JIRA, to share a finite set of its private resources and data (through JIRA dashboard gadgets, for example) with any other OAuth-compliant external application. These external applications could be another web application (such as a different JIRA installation or an iGoogle home page), a desktop application or a mobile device application and they must be accessible within your network or available on the Internet.

Using OAuth, you can access your JIRA site's data through a JIRA dashboard gadget on an iGoogle page.

The key advantage of OAuth is that a web application's resources can be shared without the web application having to hand out other important, confidential information, such as user authentication details. Instead, access to the web application's resources is handled via an 'access token'. Access tokens typically define what web application resources can be accessed by an external application and the duration of this access. Access tokens are also dissociated from a user's account and password details.

In OAuth terminology, an application that shares its resources is known as a service provider and an application that accesses a service provider's resources is known as a consumer.

The OAuth protocol has the following typical workflow:

Full Size

1. Establish an OAuth relationship between a consumer and a service provider. A relationship is typically 'unidirectional', in which one application is the consumer and the other is the service provider. However, it could be established on either the consumer or service provider application's OAuth configuration areas. This step only needs to be performed once, but it must be conducted so that your consumer and service provider can communicate via OAuth.
2. When the consumer needs to access the service provider's resources, the consumer asks the service provider for a 'request token', which is the initial step in the consumer's request to access the service provider's resources. Like access tokens, request tokens are also dissociated from a user's authentication details.
3. The service provider first validates that this request came from one of its registered consumers (established in step 1), then creates a request token and gives it to the consumer.
4. Once the consumer receives the request token, the consumer asks the user to approve the request token by sending the user to the service provider. If the user is required to log in to the service provider, they will be prompted to do so.
5. The user is then prompted to either approve or deny the consumer's access to the request token.
6. Once the user approves access, the service provider exchanges the consumer's approved request token for an access token.
7. The consumer then uses the access token to access the service provider's permitted resources. The consumer can continue to access the service provider's resources until either the access token expires, or the user revokes the access token on the service provider. If the consumer needs to access the service provider's resources after either of these events occurs, then the OAuth workflow would start again from step 2 (above).
   Access tokens issued by Atlassian applications expire after seven days.

Atlassian applications establish OAuth consumer and service provider relationships (step 1 of the workflow above) via their OAuth Administration page, which is described below. These relationships can be established using two approaches:

1. Applications that can add others as a consumer of their resources — Atlassian applications fit this category and any other application can be added as a consumer of its resources. Hence, if you are the administrator of an application (either an Atlassian or non-Atlassian one) and wish to access a different Atlassian application's resources, you can request the administrator of that Atlassian application to add your application as a consumer. The administrator of that Atlassian application can do this via the OAuth consumers configuration page.
2. Applications that require you (the consumer) to initiate the OAuth consumer-service provider relationship — Unlike Atlassian's applications, many 3rd-party applications may not provide the ability to add your application (either an Atlassian or non-Atlassian one), as a consumer of their application's resources. Instead, they will provide you with a 'consumer key' and 'shared secret', with which you can configure the OAuth consumer-service provider relationship. If you administer an Atlassian application and want it to consume the resources of such a 3rd-party application, you can establish this relationship via your Atlassian application's OAuth Service Providers configuration page.

Using Your Atlassian Application's OAuth Administration Page