Crowd provides APIs that allow external services to access resources on a user's behalf using the OAuth 2.0 protocol.

On this page:

• サポート対象の OAuth 2.0 フロー
• セキュリティに関する推奨事項
• Proof Key for Code Exchange (PKCE) を含む認可コード
• 認可コード
• Access Crowd API with access token

サポート対象の OAuth 2.0 フロー

次の OAuth 2.0 フローがサポート対象です。

• Authorization code with Proof Key for Code Exchange (PKCE)

• 認可コード

We don’t support Implicit Grant and Resource Owner Password Credentials flows, as they'll be deprecated in the next OAuth 2.0 specification version. For more information on how these flows work, see the OAuth 2.0 RFC. This should help you understand the flows and choose the right one for you.

セキュリティに関する推奨事項

Here are some recommendations to improve security:

• Prevent CSRF attacks: to protect redirect-based flows, the OAuth 2.0 specification recommends using “One-time use CSRF tokens carried in the state parameter, which are securely bound to the user agent” using the state query parameter with each request to the /rest/oauth2/latest/authorize endpoint. This can prevent CSRF attacks.

• Use HTTPS in production: For production environments, use HTTPS for the redirect uri. This is important because OAuth 2.0 bases its security on the transport layer. For more information, see the OAuth 2.0 RFC and the OAuth 2.0 Threat Model RFC. For the same reason, we also enforce HTTPS for the base URL of production environments. You can use insecure URIs and base URLs for staging or development environments by enabling the relevant system properties.

Proof Key for Code Exchange (PKCE) を含む認可コード

このフローによって、公開クライアント上でアクセス トークンに対するクライアント認証情報の OAuth 交換を安全に実行できます。次のステップとパラメーターでは、このフローの実装について説明しています。

はじめる前に

• Register your application in Crowd by creating an incoming link in application links. During registration, you can enable proper scopes to limit the range of resources that the application can access. After creating the link, you should receive the OAuth 2.0 credentials: Client ID and Client secret - keep them secure. For more information, see Configure an incoming link.

• フローを開始する前に、state (オプション)、code_verifier、code_challenge、code_challenge_method を生成します。

パラメーター

Here are the parameters you’ll use in this flow.

Making requests to the API with the access token

1. Request an authorization code by redirecting the user to the /rest/oauth2/latest/authorize page with the following query parameters:

   curl https://atlassian.example.com/rest/oauth2/latest/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=SCOPE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

   This is the consent screen that asks the user to approve the application’s request to access their account with the scopes specified in scope. The user is then redirected to the URL specified in redirect_uri. The redirect includes the authorization code, like in the following example:
   

   https://atlassian.example.com/plugins/servlet/oauth2/consent?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE&code_challenge_method=CODE_CHALLENGE_METHOD&code_challenge=CODE_CHALLENGE

2. With the authorization code returned from the previous request, you can request an access_token, with any HTTP client. The following example uses curl:
   

   curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&code=CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER

   Example response is:

   {
   
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjNmMTQ3NTUzYjg3OTQ2Y2FhMWJhYWJkZWQ0MzgwYTM4In0.EDnpBl0hd1BQzIRP--xEvyW1F6gDuiFranQCvi98b2c",
   
    "token_type": "bearer",
   
    "expires_in": 7200,
   
    "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImMwZTMxYmZjYTI2NWI0YTkwMzBiOGM2OTJjNWIyMTYwIn0.grHOsso3B3kaSxNd0QJfj1H3ayjRUuA75SiEt0usmiM",
   
    "created_at": 1607635748
   
   }

   
   

3. To retrieve a new access_token, use the refresh_token parameter. Refresh tokens may be used even after the access_token itself expires. The following request:

   • Invalidates the existing access_token and refresh_token.

   • レスポンスで新しいトークンを送信します。

curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI

Example response is:

{

  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImJmZjg4MzU5YTVkNGUyZmQ3ZmYwOTEwOGIxNjg4MDA0In0.BocpI91mpUzWskyjxHp57hnyl8ZcHehGJwmaBsGJEMg",

  "token_type": "bearer",

  "expires_in": 7200,

  "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Ijg1NjQ1YjA1NGJiYmZkNjVmMDNkMzliYzM0YzQ4MzZjIn0.4MSMIG46zjB9QCV-qCCglgojM5dL7_E2kcqmiV46YQ4",

  "created_at": 1628711391

}

You can now make requests to the API with the access token. For more info, see Access Crowd API with access token below.

認可コード

This flow lets you securely perform the OAuth 2.0 exchange of client credentials for access tokens on public clients.

パラメーター

このフローで使用するパラメーターは次のとおりです。

Access Crowd API with access token

アクセス トークンによって、ユーザーに代わって API にリクエストできます。認証ヘッダーにトークンを次のように入れられます。

curl --header "Authorization: Bearer OAUTH2-TOKEN" "https://atlassian.example.com//rest/admin/1.0/server-info"