SwaggerでBearer Token認証を行う方法

Bearer Tokenはごく一般的な認証方式として、APIのアクセス認証に利用されることがよくあります。SwaggerでBearer Token認証情報を追加することで、APIのセキュリティを確保することができます。それでは、SwaggerでBearer Token認証を行うには、どうしたらいいですか？本文では、SwaggerでBearer Token認証を行う方法を詳しく解説していきます。

Swaggerとは

Swaggerとは、RESTful APIを構築するためのオープンソースのフレームワークのことです。Swaggerは最初にSmartBear Softwareによって作成されたOSSのフレームワークで、APIの定義やインタラクティブなドキュメントを自動生成できます。OpenAPIはSwagger 2.0仕様をベースにした業界標準の仕様です。

最近のバージョンとしてはOpenAPI 3.0があり、JSON/YAMLファイルでAPIを定義できるほか、豊富な機能が追加されています。多くの場合このOpenAPI 3.0仕様に準拠したSwaggerツールを利用するのが一般的です。

SwaggerでBearer Tokenを利用

一般的には、SwaggerでBearer Tokenが利用されるシーンがよくあります。SwaggerでBearer Tokenを利用するシーンは主に以下のようなケースが考えられます。

APIの認証と認可
Swaggerを使ってAPIを設計する際、Bearer Tokenを使うことで、APIへのアクセスを制御することができます。APIコンシューマーはBearer Tokenを取得し、APIリクエストヘッダーにトークンを設定することで、APIにアクセスできるようになります。

セキュアなAPIドキュメント
SwaggerにはAPIドキュメントを保護するための機能があり、Bearer Tokenを利用することで、ドキュメントへのアクセスを制限できます。これにより、APIドキュメントを内部関係者のみに公開することができます。

認証フローのドキュメント化
Swaggerでは、Bearer Tokenの取得方法や、トークンの利用方法などの認証フローを記述できます。これにより、APIコンシューマーが認証方式を把握しやすくなります。

OpenAPI Specificationへの準拠
OpenAPI SpecificationではBearer認証をサポートしており、Swaggerを使えばこの規格に沿ったAPIドキュメントを作成できます。

SwaggerでBearer Tokenを利用する流れ

それでは、SwaggerでBearer Tokenをどのような流れで利用できますか？一般的には、SwaggerにBearer Token認証を追加するために、次の手順が必要です。

1. Swagger仕様（OpenAPI仕様）が正確であることを確認して、必要なパスや操作がすべて含まれることも確認します。
2. Swagger仕様では、認証情報が必要なパスや操作にsecurity 定義を追加して、認証方式をBearer tokenに指定します。
3. Swagger UIで実装する時に、リクエストヘッダーで Authorizationフィールドを追加して、Bearer tokenの方式で有効なトークンを渡します。

SwaggerでBearer Token認証を行う操作手順

それでは、SwaggerでBearer Token認証を行いたい場合は、どうしたらいいですか？次は、具体的な実装例を使って、認証を行う操作手順を皆さんに紹介します。

Swagger EditorでYAMLファイルを開く

まず、Swagger EditorでYAMLファイルを開いて、次のコードをこのファイルに入れます：

swagger: "2.0"
info:
  title: Your API
  version: 1.0.0

securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header

security:
  - Bearer: []

paths:
  /example:
    get:
      security:
        - Bearer: []
      responses:
        200:
          description: OK

このコードでは、BearerというsecurityDefinitionsを定義しました。この定義のデータタイプを API Keyに設定し、名前を Authorization に設定して、リクエストheaderに置きます。

そして、 security を利用して、認証情報をパスに適用します。こうして、/exampleというパスにアクセスする時にBearer tokenが必要になります。

最後に、簡単なGETリクエストを定義し、Bearer tokenの利用を指定します。

Swagger Editorでリクエストを行う

Swagger Editorでこのコードを実装すると、/exampleというエンドポイントにリクエストを送信する場合、"Authorization" というリクエストヘッダーがあります。ここでBearer tokenを入力する必要があります。

Spring Bootのプロジェクトで設定

Spring BootでSwaggerを利用して、Bearer Token認証を行うために、Spring Securityを利用して認証機能を実現することできます。具体的な操作手順は次のようになります：

Spring Bootプロジェクトで Bearer トークンを使った認証を行う場合、以下の手順に従うことができます。

1. 関連する依存関係を導入する: プロジェクトの pom.xml ファイルに、Spring Security と JWT トークンの依存関係を追加します。例:

<dependencies>
    <!-- Spring Security -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <!-- JWT Token -->
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt</artifactId>
        <version>0.9.1</version>
    </dependency>
</dependencies>

1. Spring Securityを設定する: プロジェクトの設定クラスで、Spring Securityの関連するセキュリティルールと認証方式を設定します。例:

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    // アクセス可能なURLパスを設定
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/api/public").permitAll()
            .anyRequest().authenticated();
    }

    // Bearer トークンを使った認証を設定
    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.authenticationProvider(jwtAuthenticationProvider());
    }

    @Bean
    public JwtAuthenticationFilter jwtAuthenticationFilter() throws Exception {
        return new JwtAuthenticationFilter();
    }

    @Bean
    public JwtAuthenticationProvider jwtAuthenticationProvider() {
        return new JwtAuthenticationProvider();
    }

    // PasswordEncoderなどその他の関連設定
    // ...
}

1. JwtAuthenticationFilterを実装する: JWT トークンを解析し、認証を行うカスタムの JwtAuthenticationFilter を作成します。例:

public class JwtAuthenticationFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        String token = extractTokenFromRequest(request);
        
        if (token != null) {
            try {
                if (isValidToken(token)) {
                    Authentication authentication = getAuthentication(token);
                    SecurityContextHolder.getContext().setAuthentication(authentication);
                }
            } catch (Exception e) {
                // 認証失敗時の処理
            }
        }
        
        filterChain.doFilter(request, response);
    }

    private String extractTokenFromRequest(HttpServletRequest request) {
        // リクエストヘッダーまたは他の場所から Bearer トークンを抽出
        // ...
    }

    private boolean isValidToken(String token) {
        // Bearer トークンが有効かどうかを検証
        // ...
    }

    private Authentication getAuthentication(String token) {
        // Bearer トークンから認証情報を取得し、Authentication オブジェクトを返す
        // ...
    }
}

1. JwtAuthenticationProviderを実装する: JWT トークンの有効性を検証するカスタムの JwtAuthenticationProvider を作成します。例:

public class JwtAuthenticationProvider implements AuthenticationProvider {

    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {
        // JWT トークンの有効性を検証
        // ...
    }

    @Override
    public boolean supports(Class<?> authentication) {
        return JwtAuthenticationToken.class.isAssignableFrom(authentication);
    }
}

上記の例では、JwtAuthenticationFilter と JwtAuthenticationProvider は JWT トークンに基づく認証のカスタム実装で、具体的なビジネスロジックと要件に応じてさらにカスタマイズと調整が可能です。

設定時の注意事項

Swaggerの Bearer トークン認証機能を使用する際、設定ミスにより認証が有効にならない場合があります。

• Swaggerの仕様と Spring Security の設定が正しく対応していることを確認してください。
• Bearer トークンを使った認証では、トークンの有効期限管理を考慮する必要があり、期限切れによるアクセス問題を避けるため。
• Bearer トークンを使った認証では、トークンの送信時の保護など、適切なセキュリティ対策が必要です。HTTPSの使用などでトークン送信を保護することが推奨されます。

Apidogでより便利にSwaggerでBearer Token認証を行う

Apidogは、APIの設計、ドキュメンテーションやテストなどをも簡単に行えるAPI管理ツールです。SwaggerのYAMLかJSONデータをApidogにインポートすると、簡単にBearer Tokenを追加して認証を行うことができます。

SwaggerデータをApidogにインポート

Apidogは、SwaggerやOpenAPI仕様のJSONかYAMLデータに完璧に互換できますので、Apidogを開き、プロジェクトで「設定」→「データのインポート」の順にクリックすると、「OpenAPI/Swagger」を選択して、JSONかYAMLデータを簡単にApidogにインポートできます。

Bearer Tokenを簡単に追加してリクエストを送信

ここで、すべてのエンドポイントの情報がApidogにインポートしました。特定のエンドポイントを選択して、「Auth」の順に選択し、タイプを「Bearer Token」と指定し、Tokenを下側の入力ボックスに記入して送信することができます。

まとめ

この記事では、SwaggerでBearer Token認証を行う方法について詳しく解説しました。SwaggerでBearer Token認証を行う場合、Swagger仕様の編集やSwagger UIでの操作が必要になりますが、Apidogを使えばより簡単に実装できます。

Apidogは、APIの設計、ドキュメント化、テストなどを一元的に行えるAPI管理ツールです。Swaggerの仕様データをApidogにインポートすると、GUIで直感的にBearer Token認証を設定できます。また、Apidogではモックサーバー機能があるため、実装前からBearer Tokenを使ったリクエストをテストできます。本番環境に近い状態でAPIのテストが可能です。

このようにApidogを活用すれば、SwaggerでのBearer Token認証の実装がよりスムーズになり、開発効率の向上が期待できます。