不要な問題なしにJavaでESIAとの統合を実装する方法

長い間、市民を特定する主な方法は通常のパスポートでした。 2011年に、電気通信マス通信省の命令により、統一識別認証システム（ESIA）が導入されたとき、状況は変化しました。これにより、個人の身元を認識し、オンラインでデータを受信できるようになりました。



ESIAの実装のおかげで、政府および商業組織、オンラインサービスの開発者および所有者は、ユーザーデータの入力および検証に関連する操作を高速化し、より安全にすることができました。 Rusfinance Bankはまた、システムの可能性を利用することを決定し、オンラインローン処理サービス（銀行は自動車ローンを専門としています）を完成させる際に、プラットフォームとの統合を実装しました。



これはそれほど簡単ではありませんでした。技術的な問題を解決するには、いくつかの要件と手順を満たす必要がありました。



この記事では、ESIAとの統合を独立して実装したい人にとって知っておくべき重要なポイントと方法論のガイドラインについて説明し、開発中の問題を克服するのに役立つJava言語のコードフラグメントを提供します（実装の一部は省略されていますが、一般的な一連のアクション）明確です）。



私たちの経験が、Java開発者が（だけでなく）テレコムおよびマスコミュニケーション省の方法論的推奨事項を開発して理解する際に多くの時間を節約するのに役立つことを願っています。

ESIAとの統合が必要なのはなぜですか？

コロナウイルスの大流行に関連して、貸付の多くの分野でのオフライン取引の数は減少し始めました。クライアントは「オンライン化」し始め、自動車ローン市場でのオンラインプレゼンスを強化することが不可欠でした。 Autocreditサービスを完成させる過程で（Habréはすでにその開発に関する記事を持っています）、銀行のWebサイトにローン申請を配置するためのインターフェイスをできるだけ便利でシンプルにすることにしました。 ESIAとの統合は、クライアントの個人データを自動的に取得することを可能にしたため、この問題を解決する上で重要な瞬間になりました。







クライアントにとっても、このソリューションは、1回のログインとパスワードを使用して、クレジットで車を購入するためのオンライン承認サービスに登録して入力することができたため、便利であることがわかりました。



さらに、ESIAとの統合により、RusfinanceBankは次のことが可能になりました。

• オンライン質問票に記入する時間を短縮します。
• 多数のフィールドに手動で入力しようとするときのユーザーバウンスの数を減らします。
• 「高品質」の検証済みクライアントのストリームを提供します。

私たちが銀行の経験について話しているという事実にもかかわらず、その情報は金融機関だけでなく役立つ可能性があります。政府は、他のタイプのオンラインサービスにESIAプラットフォームを使用することを推奨しています（詳細はこちら）。

何をどのように行うか？

最初は、技術的な観点からESIAとの統合に特別なことは何もないように見えました。これは、RESTAPIを介したデータの取得に関連する標準的なタスクです。しかし、詳しく調べてみると、すべてがそれほど単純ではないことが明らかになりました。たとえば、いくつかのパラメータに署名するために必要な証明書をどのように処理するかがわからないことが判明しました。私は時間を無駄にしてそれを理解しなければなりませんでした。しかし、まず最初に。



まず、行動計画の概要を説明することが重要でした。私たちの計画には、次の主なステップが含まれていました。

1. ESIAテクノロジーポータルに登録します。
2. テストおよび産業環境でESIAソフトウェアインターフェースを使用するための申請書を提出する。
3. ESIAとの相互作用のメカニズムを独自に開発します（現在の文書「ESIAの使用に関する方法論的推奨事項」に従って）。
4. ESIAのテストおよび産業環境でメカニズムの動作をテストします。

私たちは通常、Javaでプロジェクトを開発します。したがって、ソフトウェアの実装には次のものを選択しました。

• IntelliJ IDEA;
• CryptoPro JCP（またはCryptoPro Java CSP）;
• Java 8;
• Apache HttpClient;
• ロンボク;
• FasterXML /ジャクソン。

リダイレクトURLの取得

最初のステップは、認証コードを取得することです。私たちの場合、これは、State Servicesポータルの承認ページへのリダイレクトを伴う別のサービスによって行われます（これについて詳しく説明します）。



まず、変数ESIA_AUTH_URL（ESIAアドレス）とAPI_URL（認証が成功した場合にリダイレクトが発生するアドレス）を初期化します。その後、ESIAへのリクエストのパラメータをフィールドに含むEsiaRequestParamsオブジェクトを作成し、esiaAuthUriリンクを形成します。

public Response loginByEsia() throws Exception {
  final String ESIA_AUTH_URL = dao.getEsiaAuthUrl(); //  
  final String API_URL = dao.getApiUrl(); // ,        
  EsiaRequestParams requestDto = new EsiaRequestParams(API_URL);
  URI esiaAuthUri = new URIBuilder(ESIA_AUTH_URL)
          .addParameters(Arrays.asList(
            new BasicNameValuePair(RequestEnum.CLIENT_ID.getParam(), requestDto.getClientId()),
            new BasicNameValuePair(RequestEnum.SCOPE.getParam(), requestDto.getScope()),
            new BasicNameValuePair(RequestEnum.RESPONSE_TYPE.getParam(), requestDto.getResponseType()),
            new BasicNameValuePair(RequestEnum.STATE.getParam(), requestDto.getState()),
            new BasicNameValuePair(RequestEnum.TIMESTAMP.getParam(), requestDto.getTimestamp()),
            new BasicNameValuePair(RequestEnum.ACCESS_TYPE.getParam(), requestDto.getAccessType()),
            new BasicNameValuePair(RequestEnum.REDIRECT_URI.getParam(), requestDto.getRedirectUri()),
            new BasicNameValuePair(RequestEnum.CLIENT_SECRET.getParam(), requestDto.getClientSecret())
          ))
          .build();
  return Response.temporaryRedirect(esiaAuthUri).build();
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

わかりやすくするために、EsiaRequestParamsクラスがどのように見えるかを示しましょう。

public class EsiaRequestParams {

  String clientId;
  String scope;
  String responseType;
  String state;
  String timestamp;
  String accessType;
  String redirectUri;
  String clientSecret;
  String code;
  String error;
  String grantType;
  String tokenType;

  public EsiaRequestParams(String apiUrl) throws Exception {
    this.clientId = CLIENT_ID;
    this.scope = Arrays.stream(ScopeEnum.values())
            .map(ScopeEnum::getName)
            .collect(Collectors.joining(" "));
    responseType = RESPONSE_TYPE;
    state = EsiaUtil.getState();
    timestamp = EsiaUtil.getUrlTimestamp();
    accessType = ACCESS_TYPE;
    redirectUri = apiUrl + RESOURCE_URL + "/" + AUTH_REQUEST_ESIA;
    clientSecret = EsiaUtil.generateClientSecret(String.join("", scope, timestamp, clientId, state));
    grantType = GRANT_TYPE;
    tokenType = TOKEN_TYPE;
  }
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

その後、ユーザーをESIA認証サービスにリダイレクトする必要があります。ユーザーはユーザー名とパスワードを入力し、システムのデータへのアクセスを確認します。次に、ESIAは、認証コードを含む応答をオンラインサービスに送信します。このコードは、ESIAへのさらなる問い合わせに必要になります。



ESIAへの各要求には、PKCS7形式（Public Key Cryptography Standard）の分離された電子署名であるclient_secretパラメーターがあります。この場合、署名には証明書が使用されます。この証明書は、ESIAとの統合作業を開始する前に認証センターによって受信されました。キーストアの操作方法は、この一連の記事で詳しく説明されています。



例として、CryptoProによって提供されるキーストアがどのように見えるかを示しましょう。







この場合、秘密鍵と公開鍵の呼び出しは次のようになります。

KeyStore keyStore = KeyStore.getInstance("HDImageStore"); //   
keyStore.load(null, null);
PrivateKey privateKey = (PrivateKey) keyStore.getKey(esiaKeyStoreParams.getName(), esiaKeyStoreParams.getValue().toCharArray()); //   
X509Certificate certificate = (X509Certificate) keyStore.getCertificate(esiaKeyStoreParams.getName()); //  ,   –  .
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

JCP.HD_STORE_NAMEがCryptoProのストレージ名であるのに対し、esiaKeyStoreParams.getName（）はコンテナー名、esiaKeyStoreParams.getValue（）です。ToCharArray（）はコンテナーパスワードです。

この場合、このストレージの名前を指定するときにキーがすでに存在するため、load（）メソッドを使用してストレージにデータをロードする必要はありません。



ここで、フォームで署名を取得することを覚えておくことが重要です。

final Signature signature = Signature.getInstance(SIGN_ALGORITHM, PROVIDER_NAME);
signature.initSign(privateKey);
signature.update(data);
final byte[] sign = signature.sign();
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

ESIAはPKCS7形式の分離された署名を必要とするため、それだけでは十分ではありません。したがって、PKCS7形式の署名を生成する必要があります。



デタッチされた署名を返すメソッドの例は次のようになります。

public String generateClientSecret(String rawClientSecret) throws Exception {
    if (this.localCertificate == null || this.esiaCertificate == null) throw new RuntimeException("Signature creation is unavailable");
    return CMS.cmsSign(rawClientSecret.getBytes(), localPrivateKey, localCertificate, true);
  }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

ここでは、公開鍵とESIA公開鍵を確認します。cmsSign（）メソッドには機密情報が含まれている可能性があるため、開示しません。



詳細は次のとおりです。

• rawClientSecret.getBytes（）-スコープ、タイムスタンプ、clientId、および状態のバイト配列。
• localPrivateKey-コンテナからの秘密鍵。
• localCertificate-コンテナからの公開鍵。
• true-署名パラメーターのブール値-チェックアウトするかどうか。

署名の作成例は、PKCS7標準がCMSと呼ばれるCryptoProjavaライブラリにあります。また、ダウンロードしたバージョンのCryptoProのソースコードに含まれているプログラマーズマニュアルにも記載されています。

トークンの取得

次のステップは、認証コードと引き換えにアクセストークン（別名トークン）を受信することです。認証コードは、StateServicesポータルでのユーザー認証が成功したときにパラメーターとして受信されました。



統合識別システムでデータを受信するには、アクセストークンを取得する必要があります。これを行うために、統合された識別および認証システムに要求を作成します。ここでの主なリクエストフィールドは同じ方法で形成され、コードは次のようになります。

URI getTokenUri = new URIBuilder(ESIA_TOKEN_API_URL)
        .addParameters(Arrays.asList(
          new BasicNameValuePair(RequestEnum.CLIENT_ID.getParam(), requestDto.getClientId()),
          new BasicNameValuePair(RequestEnum.CODE.getParam(), code),
          new BasicNameValuePair(RequestEnum.GRANT_TYPE.getParam(), requestDto.getGrantType()),
          new BasicNameValuePair(RequestEnum.CLIENT_SECRET.getParam(), requestDto.getClientSecret()),
          new BasicNameValuePair(RequestEnum.STATE.getParam(), requestDto.getState()),
          new BasicNameValuePair(RequestEnum.REDIRECT_URI.getParam(), requestDto.getRedirectUri()),
          new BasicNameValuePair(RequestEnum.SCOPE.getParam(), requestDto.getScope()),
          new BasicNameValuePair(RequestEnum.TIMESTAMP.getParam(), requestDto.getTimestamp()),
          new BasicNameValuePair(RequestEnum.TOKEN_TYPE.getParam(), requestDto.getTokenType())
        ))
        .build();
HttpUriRequest getTokenPostRequest = RequestBuilder.post()
        .setUri(getTokenUri)
        .setHeader(HttpHeaders.CONTENT_TYPE, "application/x-www-form-urlencoded")
        .build();

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

答えを受け取ったら、それを解析してトークンを取得します。

try (CloseableHttpResponse response = httpClient.execute(getTokenPostRequest)) {
  HttpEntity tokenEntity = response.getEntity();
  String tokenEntityString = EntityUtils.toString(tokenEntity);
  tokenResponseDto = extractEsiaGetResponseTokenDto(tokenEntityString);
}

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

トークンは、ピリオドで区切られた3つの部分からなる文字列です：HEADER.PAYLOAD.SIGNATURE、ここで：

• HEADERは、署名アルゴリズムを含むトークンのプロパティを持つヘッダーです。
• PAYLOADは、トークンとサブジェクトに関する情報であり、州のサービスに要求します。
• 署名はHEADER.PAYLOADの署名です。

トークンの検証

ステートサービスからの応答を確実に受信するには、ステートサービスのWebサイトからダウンロードできる証明書（公開キー）へのパスを指定してトークンを検証する必要があります。受信した文字列（data）と署名（dataSignature）をisEsiaSignatureValid（）メソッドに渡すことにより、検証結果をブール値として取得できます。

public static boolean isEsiaSignatureValid(String data, String dataSignature) throws Exception {
  InputStream inputStream = EsiaUtil.class.getClassLoader().getResourceAsStream(CERTIFICATE); //   ,   
  CertificateFactory certFactory = CertificateFactory.getInstance("X.509"); //         X.509
  X509Certificate certificate = (X509Certificate) certFactory.generateCertificate(inputStream);
  Signature signature = Signature.getInstance(certificate.getSigAlgName(), new JCP()); //    Signature       JCP  
  signature.initVerify(certificate.getPublicKey()); //     
  signature.update(data.getBytes()); //    ,    
  return signature.verify(Base64.getUrlDecoder().decode(dataSignature));
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

ガイドラインに従い、トークンの有効期間を確認する必要があります。有効期間が終了した場合は、追加のパラメーターを使用して新しいリンクを作成し、httpクライアントを使用して要求を行う必要があります。

URI refreshTokenUri = new URIBuilder(ESIA_TOKEN_API_URL)
        .addParameters(Arrays.asList(
                new BasicNameValuePair(RequestEnum.CLIENT_ID.getParam(), requestDto.getClientId()),
                new BasicNameValuePair(RequestEnum.REFRESH_TOKEN.getParam(), tokenResponseDto.getRefreshToken()),
                new BasicNameValuePair(RequestEnum.CODE.getParam(), code),
                new BasicNameValuePair(RequestEnum.GRANT_TYPE.getParam(), EsiaConstants.REFRESH_GRANT_TYPE),
                new BasicNameValuePair(RequestEnum.STATE.getParam(), requestDto.getState()),
                new BasicNameValuePair(RequestEnum.SCOPE.getParam(), requestDto.getScope()),
                new BasicNameValuePair(RequestEnum.TIMESTAMP.getParam(), requestDto.getTimestamp()),
                new BasicNameValuePair(RequestEnum.TOKEN_TYPE.getParam(), requestDto.getTokenType()),
                new BasicNameValuePair(RequestEnum.CLIENT_SECRET.getParam(), requestDto.getClientSecret()),
                new BasicNameValuePair(RequestEnum.REDIRECT_URI.getParam(), requestDto.getRedirectUri())
        ))
        .build();
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

ユーザーデータの取得

私たちの場合、あなたはあなたのフルネーム、生年月日、パスポートの詳細と連絡先を取得する必要があります。

ユーザーデータの受信に役立つ機能インターフェイスを使用します。

Function<String, String> esiaPersonDataFetcher = (fetchingUri) -> {
  try {
    URI getDataUri = new URIBuilder(fetchingUri).build();
    HttpGet dataHttpGet = new HttpGet(getDataUri);
       dataHttpGet.addHeader("Authorization", requestDto.getTokenType() + " " + tokenResponseDto.getAccessToken());
    try (CloseableHttpResponse dataResponse = httpClient.execute(dataHttpGet)) {
      HttpEntity dataEntity = dataResponse.getEntity();
      return EntityUtils.toString(dataEntity);
    }
  } catch (Exception e) {
    throw new UndeclaredThrowableException(e);
  }
};
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

ユーザーデータの取得：

String personDataEntityString = esiaPersonDataFetcher.apply(ESIA_REST_API_URL + "/prns/" + esiaAccountId);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

連絡先の取得は、ユーザーデータの取得ほど明白ではなくなりました。まず、連絡先へのリンクのリストを取得する必要があります。

String contactsListEntityString = esiaPersonDataFetcher.apply(ESIA_REST_API_URL + "/prns/" + esiaAccountId + "/ctts");
EsiaListDto esiaListDto = objectMapper.readValue(contactsListEntityString, EsiaListDto.class);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

このリストを逆シリアル化し、esiaListDtoオブジェクトを取得します。ESIAマニュアルのフィールドは異なる場合があるため、経験的に確認する価値があります。



次に、リストの各リンクをたどって、各ユーザーの連絡先を取得する必要があります。次のようになります。

for (String contactUrl : esiaListDto.getElementUrls()) {
  String contactEntityString = esiaPersonDataFetcher.apply(contactUrl);
  EsiaContactDto esiaContactDto = objectMapper.readValue(contactEntityString, EsiaContactDto.class);
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

状況は、ドキュメントのリストを取得する場合と同じです。まず、ドキュメントへのリンクのリストを取得します。

String documentsListEntityString = esiaPersonDataFetcher.apply(ESIA_REST_API_URL + "/prns/" + esiaAccountId + "/docs");

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

次に、それを逆シリアル化します。

EsiaListDto esiaDocumentsListDto = objectMapper.readValue(documentsListEntityString, EsiaListDto.class);
      :
for (String documentUrl : esiaDocumentsListDto.getElementUrls()) {
  String documentEntityString = esiaPersonDataFetcher.apply(documentUrl);
  EsiaDocumentDto esiaDocumentDto = objectMapper.readValue(documentEntityString, EsiaDocumentDto.class);
}

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

では、このすべてのデータをどうするのでしょうか。

データを解析して、必要なフィールドを持つオブジェクトを取得できます。ここでは、各開発者は、参照条件に従って、必要に応じてクラスを設計できます。



必須フィールドを持つオブジェクトを取得する例：

final ObjectMapper objectMapper = new ObjectMapper()
	.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

String personDataEntityString = esiaPersonDataFetcher
	.apply(ESIA_REST_API_URL + "/prns/" + esiaAccountId);

EsiaPersonDto esiaPersonDto = objectMapper
	.readValue(personDataEntityString, EsiaPersonDto.class);

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

esiaPersonDtoオブジェクトに、連絡先などの必要なデータを入力します。

for (String contactUrl : esiaListDto.getElementUrls()) {
  String contactEntityString = esiaPersonDataFetcher.apply(contactUrl);
  EsiaContactDto esiaContactDto = objectMapper.readValue(contactEntityString, EsiaContactDto.class); //  
  if (esiaContactDto.getType() == null) continue;
  switch (esiaContactDto.getType().toUpperCase()) {
    case EsiaContactDto.MBT: //     ,    mobilePhone
      esiaPersonDto.setMobilePhone(esiaContactDto.getValue());
      break;
    case EsiaContactDto.EML: //     ,    email
      esiaPersonDto.setEmail(esiaContactDto.getValue());
  }
}

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

EsiaPersonDtoクラスは次のようになります。

@Data
@FieldNameConstants(prefix = "")
public class EsiaPersonDto {

  private String firstName;
  private String lastName;
  private String middleName;
  private String birthDate;
  private String birthPlace;
  private Boolean trusted;  //    -  (“true”) /   (“false”)
  private String status;    //   - Registered () /Deleted ()
  //   ,      /prns/{oid}
  private List<String> stateFacts;
  private String citizenship;
  private Long updatedOn;
  private Boolean verifying;
  @JsonProperty("rIdDoc")
  private Integer documentId;
  private Boolean containsUpCfmCode;
  @JsonProperty("eTag")
  private String tag;
  // ----------------------------------------
  private String mobilePhone;
  private String email;

  @javax.validation.constraints.Pattern(regexp = "(\\d{2})\\s(\\d{2})")
  private String docSerial;

  @javax.validation.constraints.Pattern(regexp = "(\\d{6})")
  private String docNumber;

  private String docIssueDate;

  @javax.validation.constraints.Pattern(regexp = "([0-9]{3})\\-([0-9]{3})")
  private String docDepartmentCode;

  private String docDepartment;

  @javax.validation.constraints.Pattern(regexp = "\\d{14}")
  @JsonProperty("snils")
  private String pensionFundCertificateNumber;

  @javax.validation.constraints.Pattern(regexp = "\\d{12}")
  @JsonProperty("inn")
  private String taxPayerNumber;

  @JsonIgnore
  @javax.validation.constraints.Pattern(regexp = "\\d{2}")
  private String taxPayerCertificateSeries;

  @JsonIgnore
  @javax.validation.constraints.Pattern(regexp = "\\d{10}")
  private String taxPayerCertificateNumber;
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

ESIAは静止していないため、サービスの改善作業は継続されます。