JDBC Driver for Jira Service Management

Build 23.0.8839

接続の確立

JDBC データソースの作成

Java アプリケーションから接続するJDBC データソースを作成できます。CData JDBC Driver for Jira Service Management に基づくJDBC データソースの作成は、3つの基本ステップで構成されます。

  • ドライバーのJAR ファイルをクラスパスに追加します。JAR ファイルはインストールディレクトリの［lib］サブフォルダ内にあります。.lic ファイルはJAR ファイルと同じフォルダ内に配置される必要があることに注意してください。
  • ドライバークラスを入力します。次に例を示します。 
    cdata.jdbc.jiraservicedesk.JiraServiceDeskDriver
  • JDBC URL を入力します。次に例を示します。 
    jdbc:jiraservicedesk:ApiKey=myApiKey;User=MyUser;InitiateOAuth=GETANDREFRESH;

or

jdbc:cdata:jiraservicedesk:ApiKey=myApiKey;User=MyUser;InitiateOAuth=GETANDREFRESH;

    上記の2つ目の形式は、同じURL 形式を使用しているドライバー間でアプリケーションに競合がある場合は、CData ドライバーを使用していることを確認するために常に使用できます。URL は "jdbc:jiraservicedesk:" または"jdbc:cdata:jiraservicedesk:" のいずれかから始まり、任意の接続プロパティの名前と値のペアをセミコロン区切りで入力します。

Jira Service Management への接続

任意のJira Service Management Cloud またはJira Service Management Server インスタンスへの接続を確立できます。接続するには次のプロパティを設定します。

  • URL（例：https://yoursitename.atlassian.net）

カスタムフィールドへのアクセス

デフォルトでは、本製品 はシステムフィールドのみ表示します。Issues のカスタムフィールドにアクセスするには、IncludeCustomFields を設定します。

Jira Service Management への認証

Basic

ローカルサーバーアカウントで認証するためには、次の接続プロパティを指定します。

  • AuthScheme：Basic に設定。
  • User：認証ユーザーのユーザー名に設定。
  • Password：認証ユーザーのパスワードに設定。

API トークン

Cloud アカウントに接続するには、APIToken を取得する必要があります。API トークンを生成するには、Atlassian アカウントにログインしてAPI トークン -> API トークンの作成をクリックします。生成されたトークンが表示されます。

データに接続するには以下を設定します。

  • AuthScheme：APIToken に設定。
  • User：認証ユーザーのユーザー名に設定。
  • APIToken：作成したAPI トークンに設定。

Note： パスワードはCloud アカウントへの接続には非推奨となり、Server インスタンスへの接続にのみ使用されるようになりました。

OAuth 2.0

Jira Service Management の"3本足の" OAuth 2.0 サポート（3LO）を活用して、ログインクレデンシャルを提供せずにデータに接続できます。

AuthScheme は、すべてのOAuth フローでOAuth に設定する必要があります。また、すべてのシナリオでカスタムOAuth アプリケーションを作成して構成する必要があります。詳しくは、カスタムOAuth アプリの作成 を参照してください。

デスクトップアプリケーション

下記の手順に従って、カスタムOAuth アプリケーションの資格情報を使用して認証します。

  • InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
  • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
  • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
  • CallbackURL：アプリケーションの登録時に定義されたリダイレクトURI に設定。
  • Url：Jira Service Management エンドポイントへのURL に設定。例えば、https://yoursitename.atlassian.net です。
  • OAuthVersion：2.0 に設定。
接続すると、本製品 はデフォルトブラウザでJira Service Management のOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。本製品 はこれでOAuth プロセスを完了します。

  • 本製品 はJira Service Management からアクセストークンを取得し、それを使ってデータをリクエストします。
  • コールバックURL からアクセストークンを取得し、リクエストを認証します。
  • OAuth 値をOAuthSettingsLocation で指定された場所に保存します。これらの値は接続間で永続化されます。
本製品 はアクセストークンの期限が切れると自動的にリフレッシュします。

Web アプリケーション

Web アプリケーション経由で接続する場合は、Jira Service Management にカスタムOAuth アプリケーションを登録する必要があります。それから本製品 を使用してOAuth トークンの値を取得および管理します。詳しくは、カスタムOAuth アプリの作成 を参照してください。

OAuth アクセストークンの取得

次の接続プロパティを設定し、OAuthAccessToken を取得します。

  • OAuthClientId：アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
  • Url：JIRA エンドポイントへのURL に設定。例えば、https://yoursitename.atlassian.net です。
  • OAuthVersion：2.0 に設定。

続いてストアドプロシージャを呼び出し、OAuth 交換を完了します。

  1. GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。AuthMode インプットをWEB に、CallbackURL をアプリケーション設定で指定したリダイレクトURI に設定します。 ストアドプロシージャがOAuth エンドポイントのURL を返します。
  2. ステップ1でストアドプロシージャが返したURL に移動します。ログインしてWeb アプリケーションを認可します。コールバックURL にリダイレクトされます。
  3. GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に、Verifier インプットをリダイレクトURI のクエリ文字列のcode パラメータに設定します。

OAuthAccessToken 接続プロパティをストアドプロシージャで返されたアクセストークンに設定し、データに接続します。ExpiresIn 秒後にアクセストークンの期限が切れたときは、GetOAuthAccessToken ストアドプロシージャを呼び出し、新しいアクセストークンを取得します。

ヘッドレスマシン

ヘッドレスマシンのユーザーアカウントでOAuth を使用するようにドライバーを設定するには、インターネットブラウザに対応した別の端末で認証する必要があります。

  1. 以下のオプションから選択します。
    • オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
    • オプション2：インターネットブラウザに対応したマシンに本製品 をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。
  2. 次に、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品 を設定します。

オプション1：Verifier code を取得および交換

Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。

インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得する方法は次のとおりです。

  1. 次のプロパティを設定します。
    • InitiateOAuth：OFF に設定。
    • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
    • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
    • OAuthVersion：2.0 に設定。
    次に、適切なCallbackURL を指定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。
  2. ログインして、本製品 にアクセス許可を与えます。すると、リダイレクトURI に遷移します。リダイレクトURI にはcode というパラメータが付加されます。このパラメータの値を控えておきます。後でOAuthVerifier 接続プロパティを設定するために必要です。
次に、OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換する必要があります。

ヘッドレスマシンでは、次の接続プロパティを設定してOAuth 認証値を取得します。

  • InitiateOAuth：REFRESH に設定。
  • OAuthVerifier：控えておいたverifier code（リダイレクトURI のcode パラメータの値）に設定。
  • OAuthClientId：カスタムOAuth アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：カスタムOAuth アプリケーション設定のクライアントシークレットに設定。
  • OAuthSettingsLocation：これを設定すると、暗号化されたOAuth 認証値が指定された場所に永続化されます。

接続をテストしてOAuth 設定ファイルを生成し、以下のプロパティを再設定して接続します。

  • InitiateOAuth：REFRESH に設定。
  • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
  • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
  • OAuthSettingsLocation：暗号化されたOAuth 認証値が保存される場所に設定。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。

オプション2：OAuth 設定を転送

ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバーとの接続をインストールし、作成する必要があります。上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。

「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定された場所に暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。

接続をテストしてOAuth 設定ファイルを生成し、OAuth 設定ファイルをヘッドレスマシンにコピーします。

ヘッドレスマシンで、次の接続プロパティを設定し、データに接続します。

  • InitiateOAuth：REFRESH に設定。
  • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
  • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
  • OAuthSettingsLocation：ブラウザでマシンからコピーしたOAuth 設定ファイルの場所に設定。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。

OAuth1.0

Jira Service Management に接続するには、次の手順に従ってください。

  1. はじめにRSA 公開 / 秘密キーのペアを生成します。ターミナルで次のコマンドを実行します。

    -openssl genrsa -out jira_privatekey.pem 1024
    
-openssl req -newkey rsa:1024 -x509 -key jira_privatekey.pem -out jira_publickey.cer -days 365
    
-openssl pkcs8 -topk8 -nocrypt -in jira_privatekey.pem -out jira_privatekey.pcks8
    
-openssl x509 -pubkey -noout -in jira_publickey.cer  -out jira_publickey.pem
  2. アカウントにアプリケーションリンクを作成します。設定 -> アプリケーション -> アプリケーションのリンクに進みます。
  3. URL フィールドにテストURL を入力し、新しいリンクを作成をクリックします。
  4. エラーを無視して続行をクリックします。必要なのはアプリケーションからJira Service Management への着信コールの設定だけです。
  5. 'Link applications' ウィンドウでは、関連性がないため好きなようにフィールドを埋めます。ただし、'受信リンクの作成' にはチェックを入れてください。続行をクリックして次のページに進みます。
  6. 必須フィールドを埋めます。
    • コンシューマーキー：任意の文字列に設定。のちにOAuthClientId として使用します。
    • コンシューマー名：任意の文字列に設定。
    • パブリックキー：先に生成したjira_publickey.pem ファイルのキーを入力。
  7. 続行をクリックします。
接続するには次のプロパティを設定します。

  • URL：Jira Service Management エンドポイントに設定。例えば、https://yoursitename.atlassian.net です。
  • OAuthClientId：アプリケーションのコンシューマーキーに設定。
  • OAuthClientSecret：任意の値（"testClientSecret" など）に設定。
  • OAuthJWTCert：秘密キーファイルの場所に設定。
  • OAuthJWTCertType：使用している秘密キーファイルに基づいて適切なオプションに設定。生成されたPEM キーファイルを使用する場合は、OAuthJWTCertType をPEMKEY_FILE に設定します。
  • InitiateOAuth：GETANDREFRESH に設定。

Crowd

AuthScheme をCrowd に設定します。Crowd への接続には、次の接続プロパティを使用します。

  • User：Crowd ユーザーアカウント。
  • Password：Crowd アカウントに関連付けられたパスワード。
  • SSOLoginURL：Crowd アカウントに関連付けられたログインURL。IDP URL は、自身のアプリケーション->［SSO］->［SSO information］->［Identity provider single sign-on URL］にあります。
  • SSOAppName：SSO を有効にするアプリケーションの名前。
  • SSOAppPassword：SSO を有効にするアプリケーションのパスワード。
  • SSOExchangeUrl: The URL used used to exchange the SAML token for JiraServiceDesk cookies. This URL may have the following formats:
    • https://<authority of JiraServiceDesk instance>/plugins/servlet/samlconsumer
    • https://<authority of JiraServiceDesk instance>/plugins/servlet/samlsso

次は接続文字列の例です。 

AuthScheme=Crowd;Url=https://yoursitename.atlassian.net;SSOLoginURL='https://<authority>/crowd/console/secure/saml/sso.action';User=crowdUserName;Password=crowdPassword;SSOExchangeUrl=https://<authority of JiraServiceDesk instance>/plugins/servlet/samlconsumer;SSOAppName=CrowdAppName;SSOAppPassword=CrowdAppPassword;

Okta

Okta に接続するには、AuthScheme をOkta に設定し、次のプロパティを設定します。

  • User：Okta ユーザー。
  • Password：Okta ユーザーのパスワード。
  • SSOLoginURL：SSO プロバイダーのログインURL。
  • SSOExchangeUrl: The URL used used to exchange the SAML token for JiraServiceDesk cookies. This URL may have the following formats:
    • https://<authority of JiraServiceDesk instance>/plugins/servlet/samlconsumer
    • https://<authority of JiraServiceDesk instance>/plugins/servlet/samlsso

Okta クライアントリクエストコンテキストをオーバーライドする信頼されたアプリケーションまたはプロキシを使用する場合、またはMFA を設定している場合は、Okta を使用して認証するためにSSOProperties を組み合わせて使用する必要があります。必要に応じて、以下のいずれかを設定します。

  • APIToken：Okta クライアントリクエストコンテキストをオーバーライドする、信頼されたアプリケーションまたはプロキシ経由でユーザーを認証する場合、これを顧客がOkta 組織で作成したAPI Token に設定します。
  • MFAType：MFA フローを設定した場合、次の対応するタイプのいずれかに設定します：OktaVerify、Email、またはSMS。
  • MFAPassCode：MFA フローを設定した場合は、有効なパスコードに設定します。
    これを空欄または無効な値に設定した場合、本製品 はユーザーのデバイスまたはE メールにワンタイムパスワードチャレンジを発行します。パスコードを受信後、取得したワンタイムパスワードをMFAPassCode 接続プロパティに設定する接続を再度開きます。
  • MFARememberDevice：デフォルトはTrue です。Okta は、MFA が必要な場合にデバイスを記憶させることをサポートします。設定された認証ポリシーに従ってデバイスの記憶が許可されている場合、本製品 はMFA 認証の有効期間を延長するデバイストークンを送信します。MFA を記憶させない場合は、この 変数をFalse に設定してください。

接続文字列の例： 

AuthScheme=Okta;Url=https://yoursitename.atlassian.net;SSOLoginURL='https://example.okta.com/home/appType/0bg4ivz6cJRZgCz5d6/46';User=oktaUserName;Password=oktaPassword;SSOExchangeUrl=https://<authority of JiraServiceDesk instance>/plugins/servlet/samlconsumer;

Copyright (c) 2024 CData Software, Inc. - All rights reserved.
Build 23.0.8839