C# - JIRA REST API 사용 정리 (2) JIRA OAuth 토큰으로 API 사용하는 방법

예전 글에서는 JIRA에 대해 Basic 인증을 사용했는데요,

C# - JIRA REST API 사용 정리
; https://www.sysnet.pe.kr/2/0/11566

OAuth 인증을 사용하려면 어떻게 해야 할까요? 이를 위해 필요한 값은 다음의 4가지 값입니다.

• Access Token
• Access Token Secret
• Consumer Key
• Consumer Secret

문제는, 이 값들을 구하는 방법이 좀 어렵다는 점입니다. 가령 Github 등의 서비스들은 관리 화면에 가서 Access Token을 바로 구해 간편하게 사용할 수 있는데요, JIRA는 관리 화면에서 직접적으로 저 값들을 구하는 방식이 아닙니다.

여기서 Consumer Secret은 개인키이고, 그것의 공개키를 이용해 JIRA 서비스와 연동하며 남은 3가지 값을 구할 수 있는데요, 뭐랄까 마치 Linux 세계에서 SSH 통신을 위해 서버 측에 공개키를 보관해 두는 방식과 유사하면서 복잡도는 더 증가한 방식입니다.

어쨌든, 이에 대한 방법은 다음의 공식 문서에서 살펴볼 수 있습니다.

Jira Server Developer - OAuth
; https://developer.atlassian.com/server/jira/platform/oauth/

문서를 따라 해 볼까요? ^^

우선, openssl 도구를 이용해 다음의 절차로 자신의 개인키/공개키를 만들어 둡니다.

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.pkcs8
openssl x509 -pubkey -noout -in jira_publickey.cer  > jira_publickey.pem

또는, 기존에 ssh-keygen으로 만들어 둔 키가 있다면 출력된 개인키 파일과 공개키 파일을 pem 형식으로 변환해 둡니다.

ssh-keygen으로 생성한 개인키/공개키 파일을 각각 PKCS8/PEM 형식으로 변환하는 방법
; https://www.sysnet.pe.kr/2/0/12560

저렇게 개인키/공개키 파일을 구했으면 이제 JIRA에 로그인을 하고 Jira settings > Add-ons -> Application links로 들어가,



위의 화면에서 "Application" 항목에 아무 URL 형식이나 입력하고 "Create new link" 버튼을 누릅니다. 그럼, 다음과 같은 경고와 함께 다시 한번 확인을 요하는 창이 뜨는데요,



상관없습니다. 해당 URL은 실제로 JIRA 측에서 접속해야만 하는 외부 서비스인 경우에만 유효하고, 반대로 JIRA 측으로 접속해야 하는 경우에는 단순히 식별자 정도로 여기고 그냥 진행해도 됩니다.

그럼, 다시 아래와 같은 창을 띄우는데요,



아래의 3가지 설정만 하고 "Continue"를 누릅니다.

Application Name: mytest
Application Type: Generic Application
Create incoming link: (Checked)

이후 대화창에서는 다음과 같이 구성해 마무리를 하면 됩니다.

Consumer key = (원하는 임의의 문자열: 이후의 작업에서 식별자로 사용)
Consumer name = (원하는 임의의 문자열)
Public key = ...[공개키 pem 파일의 내용]...

예)
Consumer key = myOauthKey
Consumer name = Example Jira app
Public key = ...[공개키 pem 파일의 내용]...

그다음, 아래의 repo를 clone 해서,

git clone https://bitbucket.org/atlassianlabs/atlassian-oauth-examples.git

.\atlassian-oauth-examples\java\src\main\java\com\atlassian\oauth\client\example\PropertiesClient.java 파일의 DEFAULT_PROPERTY_VALUES 코드를 다음과 같이 변경합니다.

private final static Map<String, String> DEFAULT_PROPERTY_VALUES = ImmutableMap.<String, String>builder()
        .put(JIRA_HOME, "http://...jira 서비스 기본 주소...")
        .put(CONSUMER_KEY, "myOauthKey") // 이전 단계에서 등록했던 Consumer key
        .put(PRIVATE_KEY, "...[jira_privatekey.pcks8 파일의 내용 또는 ssh-keygen의 경우 개인키 파일 내용]...")
        .build();

이후 .\atlassian-oauth-examples\java 디렉터리에서 mvn을 이용해 빌드해 주면,

c:\temp\atlassian-oauth-examples\java> mvn clean compile assembly:single

.\atlassian-oauth-examples\java\target 디렉터리에 OAuthTutorialClient-1.0.jar 파일이 생성되고, 이것을 실행해 새롭게 Token 정보를 요구할 수 있습니다.

c:\temp\atlassian-oauth-examples\java> cd target

c:\temp\atlassian-oauth-examples\java\target> java -jar OAuthTutorialClient-1.0.jar requestToken
Creating default properties file: config.properties
Token:                  U2cfGjfM6ELmU7iCw1j1iUJreWNfBZqB
Token secret:   83sOm6FQ1AWhjv7JZL5WU93hQy48xLYG
Retrieve request token. Go to http://...jira 서비스 기본 주소.../plugins/servlet/oauth/authorize?oauth_token=U2cf...[생략]...BZqB to authorize it.

출력 정보에 따라, (10분 내에) "Go to http..."에 해당하는 URL을 방문해서 "Allow" 버튼을 눌러 줍니다. 그럼, 다음과 같은 식의 메시지가 출력됩니다.

Access Approved
You have successfully authorized 'Example Jira app'. Your verification code is 'cSMF9F'. You will need to enter this exact text when prompted. You should write this value down before closing the browser window.

그리고 위에서 출력된 "verification code"를 입력으로 다시 한번 다음의 명령어를 실행하면,

c:\temp\atlassian-oauth-examples\java\target> java -jar OAuthTutorialClient-1.0.jar accessToken cSMF9F
Access token:                   m88BvFRz7AQ0HoY42r3qeDV0iHfsP82a

이제서야 Access token 값을 얻게 됩니다. 그리고, 위와 같은 정보들은 OAuthTutorialClient-1.0.jar 파일이 있는 디렉터리에 config.properties로도 저장되어 있으니,

c:\temp\atlassian-oauth-examples\java\target> type config.properties
#Thu Mar 11 19:36:38 KST 2021
consumer_key=myOauthKey
access_token=m88BvFRz7AQ0HoY42r3qeDV0iHfsP82a
request_token=U2cfGjfM6ELmU7iCw1j1iUJreWNfBZqB
jira_home=http\://...jira 서비스 기본 주소...
private_key=MIICeAIBADA...[생략]...tw2r33z
secret=cSMF9F

이후 필요할때 저 파일을 참고하시면 됩니다. 실제로 저 설정으로 OAuth 인증이 잘 동작하는지, 다음과 같이 request를 날리고 그 응답이 잘 오는지 확인할 수 있습니다.

c:\temp\atlassian-oauth-examples\java\target> java -jar OAuthTutorialClient-1.0.jar request http://...jira 서비스 기본 주소.../rest/api/2/issue/...issue_number...

---

이렇게 발행한 Access token은 JIRA의 사용자 프로파일 정보로 들어가,



Tools / "View OAuth Access Tokens" 메뉴로,



다음과 같이 확인할 수 있고 "Revoke Access"를 통해 사용을 해제하는 것도 가능합니다.



(참고로, 저 메뉴에 "View OAuth Access Tokens"가 있길래 처음에는 어딘가 Access Tokens를 쉽게 만들 수 있는 메뉴가 있지 않을까 싶어 헤매며 돌아다녔는데 결국 생성 메뉴는 애당초 없었던 것입니다.)

---

자, 그럼 이제 이것을 가지고 (최소 .NET 4.5.2 이상의) .NET 클라이언트에서 어떻게 사용하는지 보겠습니다. 이에 대해서는 다음의 글에서 방법을 찾을 수 있는데요,

Connect to Jira with a Private Key (OAuth) using .NET
; https://keestalkstech.com/2019/06/connect-to-jira-with-a-private-key-using-net/

현재 OAuth 인증을 위해 Access Token, Access Token Secret, Consumer Key 3가지 값은 구한 상태이고 이제 4번째 값을 구하는데 이를 위해 필요한 패키지가 OpenSSL.PrivateKeyDecoder입니다. 이것은 PKCS8 포맷의 개인키로부터 Consumer Secret에 사용할 수 있는 값으로 변환할 수 있는데요, 간단하게 .NET 5 console 프로젝트를 만들어 패키지 참조 추가 후,

Install-Package OpenSSL.PrivateKeyDecoder

다음과 같이 코드를 작성할 수 있습니다.

using System;

class Program
{
    static void Main(string[] args)
    {
        var privateKey = "-----BEGIN PRIVATE KEY-----MIICeA...[생략]...w2r33z-----END PRIVATE KEY-----"; // <- get your private key in here
        var decoder = new OpenSSL.PrivateKeyDecoder.OpenSSLPrivateKeyDecoder();
        var keyInfo = decoder.Decode(privateKey);
        var consumerSecret = OpenSSL.PrivateKeyDecoder.RSAExtensions.ToXmlString(keyInfo, true);

        Console.WriteLine(consumerSecret);
    }
}

/* 출력 결과
<RSAKeyValue><Modulus>z849b+...[생략]...U02BE=</D></RSAKeyValue>
*/

이제 저 값만 복사해 두고 (또는 매번 저 코드를 실행해 consumerSecret을 구해) "Atlassian.SDK" 패키지를 참조 추가한,

Install-Package Atlassian.SDK

C# 프로젝트에서 JIRA REST API를 OAuth 인증을 통해 호출할 수 있습니다.

using System;

namespace ConsoleApp1
{
    class Program
    {
        static async Task Main(string[] args)
        {
            var consumerSecret = "<RSAKeyValue><Modulus>z849b+...[생략]...U02BE=</D></RSAKeyValue>";
            string consumerKey = "myOauthKey"; // config.properties 파일의 consumer_key 값
            string accessToken = "m88BvFRz7AQ0HoY42r3qeDV0iHfsP82a"; // config.properties 파일의 access_token 값
            string accessTokenSecret = "cSMF9F"; // config.properties 파일의 secret 값

            var client = Atlassian.Jira.Jira.CreateOAuthRestClient("http://...jira 서비스 기본 주소...",
                consumerKey,     
                consumerSecret,  
                accessToken,     
                accessTokenSecret
                );

            var issue = await client.Issues.GetIssueAsync("...issue_number...");

            Console.WriteLine(issue.Summary);
        }
    }
}

(참고로, 저렇게 개인키를 응용 프로그램에 포함시켜 배포하기 때문에 중요하게 사용하는 개인키를 재사용해서는 안 됩니다. 즉, 저것은 단일 응용 프로그램에만 사용하는 용도의 RSA 키를 만들어서 사용하는 것이 바람직합니다.)

여기까지 아주 복잡하게 OAuth 인증 테스트를 해봤는데요, 일단 이 글에서 설명한 방식은 "Jira Server Developer - OAuth" 문서를 기반으로 했기에 복잡한 것이지, 현재는 더 좋은 접근 방식이 .NET 도구로 제공되므로 이 글의 내용보다는 쉽게 OAuth 키 구성을 할 수 있습니다. 이에 대해서는 다음에 ^^ 자세하게 설명하겠습니다.

(첨부 파일은 이 글의 예제 코드를 포함합니다.)

---

개인키를 변환해 consumerSecret을 구하는 OpenSSL.PrivateKeyDecoder는 요구 사항이 .NET Standard 1.3이므로 .NET Framework 프로젝트의 경우 최소 4.6 대상으로 만들어야 한다는 건데요, 하지만 실제로 해보면 OpenSSL.PrivateKeyDecoder.RSAExtensions을 사용하는 코드에서,

var consumerSecret = OpenSSL.PrivateKeyDecoder.RSAExtensions.ToXmlString(keyInfo, true);

RSAExtensions 타입이 없어 컴파일 에러가 발생합니다.

error CS0234: The type or namespace name 'RSAExtensions' does not exist in the namespace 'OpenSSL.PrivateKeyDecoder' (are you missing an assembly reference?)

OpenSSL.PrivateKeyDecoder 패키지는 .NET Framework에 대해 (4.8까지도) RSAExtensions 타입은 제공하지 않는 듯합니다. 따라서, 어쩔 수 없이 consumerSecret을 구하는 것은 .NET 5 프로젝트로 만들어 구해둔 다음 그 문자열을 복사해와서 .NET Framework 프로젝트에서 사용하는 식으로 해야 합니다.

---

만약 OpenSSLPrivateKeyDecoder.Decode 메서드 호출 시 다음과 같은 오류가 발생한다면?

Unhandled exception. System.NotSupportedException: Specified method is not supported.
   at OpenSSL.PrivateKeyDecoder.OpenSSLPrivateKeyDecoder.DecodeParameters(String privateText, SecureString password)
   at OpenSSL.PrivateKeyDecoder.OpenSSLPrivateKeyDecoder.Decode(String privateText, SecureString password)
   at ConsoleApp1.Program.Main(String[] args) in c:\temp\jira_oauth\ConsoleApp1\ConsoleApp1\Program.cs:line 14

개인키 문자열을 이런 식으로,

var privateKey = "MIICe..[생략]...gAtw2r33z";

잘못 전달해서 그런 것입니다. 반드시 "BEGIN PRIVATE KEY" / "END PRIVATE KEY" 쌍으로 감싸야만 정상적으로 동작합니다.

var privateKey = "-----BEGIN PRIVATE KEY-----MIICe..[생략]...gAtw2r33z-----END PRIVATE KEY-----";

---

만약 Atlassian.Jira.Jira 개체로 REST API 호출이 발생했을 때 다음과 같은 오류가 발생한다면?

Unhandled exception. System.ApplicationException: Using query parameters in the base URL is not supported for OAuth calls. Consider using AddDefaultQueryParameter instead.
   at RestSharp.Authenticators.OAuth1Authenticator.AddOAuthData(IRestClient client, IRestRequest request, OAuthWorkflow workflow)
   at RestSharp.Authenticators.OAuth1Authenticator.Authenticate(IRestClient client, IRestRequest request)
   at RestSharp.RestClient.AuthenticateIfNeeded(IRestRequest request)
   at RestSharp.RestClient.ExecuteAsync(IRestRequest request, Action`2 callback, String httpMethod, Func`4 getWebRequest)
   at RestSharp.RestClient.ExecuteAsync(IRestRequest request, Action`2 callback, Method httpMethod)
   at RestSharp.RestClient.ExecuteAsync(IRestRequest request, Action`2 callback)
   at RestSharp.RestClient.ExecuteAsync(IRestRequest request, CancellationToken token)
--- End of stack trace from previous location ---
   at Atlassian.Jira.Remote.JiraRestClient.ExecuteRequestAsync(Method method, String resource, Object requestBody, CancellationToken token)
   at Atlassian.Jira.Remote.IssueService.GetIssueAsync(String issueKey, CancellationToken token)
   at ConsoleApp1.Program.TestCode() in c:\temp\jira_oauth\ConsoleApp1\ConsoleApp1\Program.cs:line 61
   at ConsoleApp1.Program.Main(String[] args) in c:\temp\jira_oauth\ConsoleApp1\ConsoleApp1\Program.cs:line 14
   at ConsoleApp1.Program.<Main>(String[] args)

아마도 "Connect to Jira with a Private Key (OAuth) using .NET" 문서의 내용을 따라 Jira 개체를 다음과 같은 식으로 초기화한 것일 텐데요,

var client = Atlassian.Jira.Jira.CreateRestClient("http://...jira 서비스 기본 주소...");
client.RestClient.RestSharpClient.Authenticator =
    RestSharp.Authenticators.OAuth1Authenticator.ForProtectedResource(
        consumerKey,        
        consumerSecret,     
        accessToken,        
        accessTokenSecret,  
        RestSharp.Authenticators.OAuth.OAuthSignatureMethod.RsaSha1
    );

정확한 원인은 알 수 없지만, Authenticator를 저렇게 Jira 인스턴스가 생성된 이후 초기화하면 (저 글을 쓰는 당시에는 가능했겠지만 현재는) 정상적으로 구성이 되지 않는 듯합니다. 따라서, 명시적으로 Authenticator 설정과 함께 개체 초기화를 수행하는 생성자를 사용하는 것으로 바꿔야 합니다.

var client = Atlassian.Jira.Jira.CreateOAuthRestClient("http://...jira 서비스 기본 주소...",
        consumerKey,     
        consumerSecret,  
        accessToken,     
        accessTokenSecret
    );

---

[이 글에 대해서 여러분들과 의견을 공유하고 싶습니다. 틀리거나 미흡한 부분 또는 의문 사항이 있으시면 언제든 댓글 남겨주십시오.]

[최초 등록일: 3/15/2021]
[최종 수정일: 3/16/2021]


이 저작물은 크리에이티브 커먼즈 코리아 저작자표시-비영리-변경금지 2.0 대한민국 라이센스에 따라 이용하실 수 있습니다.

by SeongTae Jeong, mailto:techsharer at outlook.com