TOC

Spring BootでKeycloakを使用するためのクイックガイド

Spring BootでKeycloakを使用するためのクイックガイド

1. 概要

この記事では、Keycloakサーバーのセットアップの基本、サーバーへのconnect a Spring Boot applicationの実行方法、およびSpringSecurityでの使用方法について説明します。

2. Keycloakとは何ですか？

Keycloakは、最新のアプリケーションとサービスを対象としたオープンソースのIDおよびアクセス管理ソリューションです。

Keycloakは、シングルサインオン（SSO）、IDブローカリングとソーシャルログイン、ユーザーフェデレーション、クライアントアダプター、管理コンソール、アカウント管理コンソールなどの機能を提供します。 Keycloakの詳細については、official pageにアクセスしてください。

このチュートリアルでは、Keycloakの管理コンソールを使用してセットアップし、Keycloakクライアントアダプターを使用してSpringBootに接続します。

3. Keycloakサーバーのセットアップ

3.1. Keycloakのダウンロードとインストール

選択できるディストリビューションはいくつかあります。

ただし、このチュートリアルでは、スタンドアロンバージョンを使用します。

公式ソースからKeycloak-3.3.0.Final Standalone server distributionをダウンロードします。

スタンドアロンサーバーディストリビューションをダウンロードしたら、ターミナルからKeycloakを解凍して起動できます。 

unzip keycloak-3.3.0.Final.zip
cd keycloak-3.3.0.Final/bin
./standalone.sh -Djboss.socket.binding.port-offset=100

./standalone.shを実行した後、Keycloakはサービスを開始します。 Keycloak 3.3.0.Final (WildFly Core 3.0.1.Final)を含む行が開始されていることを確認すると、その起動が完了したことがわかります。

ブラウザを開き、http://localhost:8180.にアクセスします。http://localhost:8180/authにリダイレクトされ、管理ログインが作成されます。

image

パスワード「zaq1!QAZ」で「initial1」という名前のユーザーを作成しましょう。

「Welcome to Keycloak”：

image

これで管理コンソールに進むことができます。

3.2. レルムの作成

マウスを左上隅に移動して、“Create a Realm”ボタンを見つけましょう。

image

「SpringBootKeycloak」という名前を付けています。

image

3.3. クライアントの作成

次に、[クライアント]ページに移動します。 下の画像でわかるように、Keycloak comes with Clients that are already built in：

image

ただし、アプリケーションにクライアントを追加する必要があるため、[作成]をクリックします。 新しいクライアントを「login-app」:と呼びます

image

次の画面では、このチュートリアルでは、「有効なリダイレクトURIフィールド」を除くすべてのデフォルトを残します。 ポート8081にリダイレクトされます。

image

3.4. ロールとユーザーの作成

Keycloakはロールベースアクセスを使用します。 したがって、各ユーザーには役割が必要です。

「ロール」ページに移動する必要があります。

image

次に、「user」ロールを追加します。

image

これで、ユーザーに割り当てることができる役割ができましたが、まだユーザーがいません。 それでは、「ユーザー」ページに移動して、次のページを追加しましょう。

image

ユーザー“user1”:を追加します

image

ユーザーが作成されると、次のページが表示されます。

image

これで、「資格情報」タブに移動できます。 パスワードを「[email protected]”：」に設定します。

image

「ロールマッピング」タブに移動します。 ユーザーロールを割り当てます。

image

3.5. カスタムログインページの作成

Keycloakは、アクセストークンを生成および更新するためのREST APIを提供します。 このAPIを使用して、独自のログインページを簡単に作成できます。

まず、次のURLにPOSTリクエストを送信して、Keycloakからアクセストークンを取得する必要があります。 

http://localhost:8180/auth/realms/master/protocol/openid-connect/token

リクエストには次のJSONボディが必要です。 

{
    'client_id': 'your_client_id',
    'username': 'your_username',
    'password': 'your_password',
    'grant_type': 'password'
}

それに応じて、access_tokenとrefresh_tokenを取得します。

アクセストークンは、Keycloakで保護されたリソースへのすべてのリクエストで、Authorizationヘッダーに配置するだけで使用する必要があります。 

headers: {
    'Authorization': 'Bearer' + access_token
}

アクセストークンの有効期限が切れると、上記と同じURLにPOSTリクエストを送信することで更新できますが、ユーザー名とパスワードの代わりに更新トークンが含まれます。 

{
    'client_id': 'your_client_id',
    'refresh_token': refresh_token_from_previous_request,
    'grant_type': 'refresh_token'
}

これは、新しいaccess_tokenとrefresh_token.で応答します

4. Spring Bootアプリケーションの作成

4.1. 依存関係

最新のSpringBoot Keycloak Starterの依存関係はon Maven Centralにあります。

The Keycloak Spring Boot adaptercapitalizes on Spring Boot’s auto-configurationなので、必要なのはKeycloak SpringBootスターターをプロジェクトに追加することだけです。

依存関係XML要素内で、Spring BootでKeycloakを実行するには、次のものが必要です。 


    org.keycloak
    keycloak-spring-boot-starter

依存関係のXML要素の後に、KeycloakにdependencyManagementを指定する必要があります。 


    
        
            org.keycloak.bom
            keycloak-adapter-bom
            3.3.0.Final
            pom
            import

次の埋め込みコンテナが現在サポートされており、Spring Boot KeycloakStarterを使用している場合は追加の依存関係は必要ありません。

  • トムキャット

  • 引き綱

  • 桟橋

4.2. ThymeleafWebページ

WebページにはThymeleafを使用しています。

3つのページがあります。

  • external.html –は、一般向けの外部向けWebページです。

  • customers.html –アクセスが「user」の役割を持つ認証済みユーザーのみに制限される内部向けページ。

  • layout.html – 2つのフラグメントで構成される単純なレイアウトで、外向きのページと内向きのページの両方に使用されます

Thymeleafテンプレートのコードはavailable on Githubです。

4.3. コントローラ

Webコントローラーは、内部および外部URLを適切なThymeleafテンプレートにマップします。 

@GetMapping(path = "/")
public String index() {
    return "external";
}

@GetMapping(path = "/customers")
public String customers(Model model) {
    addCustomers();
    model.addAttribute("customers", customerDAO.findAll());
    return "customers";
}

パス/customersの場合、リポジトリからすべての顧客を取得し、その結果を属性としてModelに追加します。 後で、Thymeleafで結果を繰り返し処理します。

4.4. Keycloakの構成

基本的な必須の構成は次のとおりです。 

keycloak.auth-server-url=http://localhost:8180/auth
keycloak.realm=SpringBootKeycloak
keycloak.resource=login-app
keycloak.public-client=true

思い出したように、ポート8180でKeycloakを開始したため、パスはkeycloak.auth-server-urlで指定されています。 Keycloak管理コンソールで作成したレルム名を入力します。

keycloak.resourceで指定する値は、管理コンソールで指定したクライアントと一致します。

使用するセキュリティの制約は次のとおりです。 

keycloak.security-constraints[0].authRoles[0]=user
keycloak.security-constraints[0].securityCollections[0].patterns[0]=/customers/*

上記のセキュリティ制限状態により、/customers/*へのすべてのリクエストは、リクエストしたユーザーが「user」の役割を持つ認証済みユーザーである場合にのみ許可されます。

4.5. デモンストレーション

これで、アプリケーションをテストする準備が整いました。 Spring Bootアプリケーションを実行するには、Spring Tool Suite（STS）などのIDEから簡単に起動するか、ターミナルで次のコマンドを実行します。 

mvn clean spring-boot:run

localhost:8081:にアクセスします

image

次に、「customers」をクリックして、機密情報の場所であるイントラネットに入ります。

Keycloakを介して認証するようにリダイレクトされ、このコンテンツの表示が許可されているかどうかを確認できます。

image

認証され、Keycloakによって承認が確認されると、制限された顧客のページにリダイレクトされます。

image

これで、Spring BootをKeycloakに接続し、それがどのように機能するかを示すセットアップが完了しました。

次に、SpringSecurityを既存のアプリケーションと組み合わせて使用​​する方法を確認します。

5. 春のセキュリティ

Keycloak Spring Security Adapterがあり、それはalready included in our Spring Boot Keycloak Starter dependencyです。 次に、SpringSecurityをKeycloakと統合する方法を説明します。

5.1. 依存

Spring BootでSpring Securityを使用するには、次の依存関係を追加する必要があります。 


    org.springframework.boot
    spring-boot-starter-security
    1.5.3

最新のSpringBoot Starter Securityリリースはon Maven Centralにあります。

5.2. 構成クラス

Keycloakは、WebSecurityConfigurerインスタンスを作成するための便利な基本クラスとしてKeycloakWebSecurityConfigurerAdapterを提供します。これは、Spring Securityによって保護されたアプリケーションにはWebSecurityConfigurerAdapterを拡張する構成クラスが必要なため便利です。 

@Configuration
@EnableWebSecurity
@ComponentScan(basePackageClasses = KeycloakSecurityComponents.class)
class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {

    @Autowired
    public void configureGlobal(
      AuthenticationManagerBuilder auth) throws Exception {

        KeycloakAuthenticationProvider keycloakAuthenticationProvider
         = keycloakAuthenticationProvider();
        keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(
          new SimpleAuthorityMapper());
        auth.authenticationProvider(keycloakAuthenticationProvider);
    }

    @Bean
    public KeycloakSpringBootConfigResolver KeycloakConfigResolver() {
        return new KeycloakSpringBootConfigResolver();
    }

    @Bean
    @Override
    protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
        return new RegisterSessionAuthenticationStrategy(
          new SessionRegistryImpl());
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        super.configure(http);
        http.authorizeRequests()
          .antMatchers("/customers*")
          .hasRole("user")
          .anyRequest()
          .permitAll();
    }
}

上記のコードに注意してください：

  • configureGlobal：SimpleAuthorityMapperにタスクを実行して、役割の前にROLE_が付いていないことを確認します

  • keycloakConfigResolver：これは、デフォルトのkeycloak.jsonの代わりにSpringBootプロパティファイルのサポートを使用することを定義します

5.3. application.properties

Spring Securityを使用してセキュリティ制約を設定したため、application.propertiesに設定した以前のセキュリティ制約を削除できます。

次に、これをapplication.propertiesに追加します。 

keycloak.principal-attribute=preferred_username

5.4. コントローラ

ユーザーのユーザー名を利用するために、コントローラーを更新してPrincipalを挿入します。 

@GetMapping(path = "/customers")
public String customers(Principal principal, Model model){
    addCustomers();
    model.addAttribute("customers", customerDAO.findAll());
    model.addAttribute("username", principal.getName());
    return "customers";
}

5.5. タイムリーフ

divコンテナの下に、ユーザーに挨拶するために次の1行を追加します。 

Hello, --name--.

5.6. Demo

これで、認証して内部の顧客のページに移動すると、次のように表示されます。

image

6結論

このチュートリアルでは、Keycloakサーバーを構成し、Spring Boot Applicationで使用しました。

また、Spring Securityを設定し、Keycloakと組み合わせて使用​​する方法も確認しました。 この記事に示されているコードの作業バージョンは、over on Githubで入手できます。

Related