よく知られたOpenID Connect プロバイダーの設定
このドキュメントでは、よく知られているソーシャル OIDC および OAuth2 プロバイダの設定方法について説明します。
はじめに
OpenID Connect認可コードフロー を使用してQuarkusのエンドポイントを保護する場合は、OpenID Connectプロバイダーへの接続方法、そのようなプロバイダーへの認証方法、使用するスコープなどをQuarkusに伝えるように設定する必要があります。
プロバイダによってはOpenID Connectを完全に実装していなかったり、実際には OAuth2プロバイダのみ であったりするため、設定を使用して回避する必要がある場合があります。
このようなプロバイダーの設定は、複雑で非常に技術的になり、理解が困難になる可能性があります。
よく知られた OpenID Connect および OAuth2 プロバイダーを参照するために、quarkus.oidc.provider
設定プロパティーが導入されました。このプロパティーを使用して、最小限のカスタマイズのみが必要な github
などのプロバイダーを参照することができます。通常、アカウント固有の client id
、client secret
およびいくつかのプロパティーを設定して設定を完了する必要があります。
This property can be used in application.properties
, in multi-tenant set-ups if more than one provider has to be configured (for example, see Quarkus Renarde security documentation), in custom TenantConfigResolvers if the tenant configurations are created dynamically.
よく知られたプロバイダー
Apple
In order to set up OIDC for Apple you need to create a developer account, and sign up for the 99€/year program, but you cannot test your application on localhost
like most other OIDC providers:
you will need to run it over HTTPS and make it publicly accessible, so for development purposes
you may want to use a service such as https://ngrok.com.
Create a new identifier にアクセスして +
を押します
何も触れないで、App IDs
を選択したまま Continue
を押します。
何も触れないで、App
を選択したまま Continue
を押します。
説明とバンドル ID を入力します (アプリケーションパッケージ名を使用します)。
次に、下にスクロールして Sign in with Apple
機能を見つけ、それを選択して、Continue
を押します。
アプリ ID 接頭辞を書き留めてから、Register
を押します。
Identifiers
ページに戻り、 +
を押します。
Service IDs
を選択し、Continue
を押します。
説明とバンドル ID を入力 (アプリケーションパッケージ名を使用) し、Continue
を押します。
次に、Register
を押します。
サービスリストに戻り、新しく作成したサービスをクリックします。
Sign in with Apple
を有効にして、Configure
を押します。
ドメインを追加して URL (<host>/_renarde/security/oidc-success
に設定) を返し、Next
を押します。
次に Done
を押します。
続いて Continue
を押します。
そして、Save
を押します。
左側のメニューの Keys ページに移動し、+
を押します。
キー名を入力し、Sign in with Apple
を有効にして、Configure
を押します。
Primary App ID を選択し、Save
を押します。
キーページに戻り、Continue
を押します。
次に、Register
を押します。
Key ID
を書き留めてキーをダウンロードし、src/main/resources/AuthKey_<KEYID>.p8
の Quarkus アプリケーションに保存します。
これで、application.properties
を設定できます。
quarkus.oidc.provider=apple
quarkus.oidc.client-id=<Bundle ID>
quarkus.oidc.credentials.jwt.key-file=AuthKey_<Key ID>.p8
quarkus.oidc.credentials.jwt.token-key-id=<Key ID>
quarkus.oidc.credentials.jwt.issuer=<App ID Prefix>
quarkus.oidc.credentials.jwt.subject=<Bundle ID}
quarkus.oidc.provider=apple
will request Apple to add openid
, email
and name
scopes to issued access tokens. For information about overriding these scopes or requesting more scopes, see the プロバイダーのスコープ section.
Discord
Create a Discord application:
You now can get your client id and secret:
これで、application.properties
を設定できます。
quarkus.oidc.provider=discord
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret=<Client Secret>
Facebook you will not be let you test your application on localhost
like most other OIDC providers:
you will need to run it over HTTPS and make it publicly accessible, so for development purposes
you may want to use a service such as https://ngrok.com.
In order to set up OIDC for Facebook start by Creating an application, select Other
as an app type, and click Next
.
Now choose your application type. For this guide choose Consumer
and click Next
until you reach the screen below. Now enter an application name, and contact email, and press Create app
:
アプリページで、Facebook login
製品の Set up
をクリックします。
On the Quickstart
page click on Facebook login > Settings
on the left menu:
First click on Get Advanced Access
to switch public_profile
to advanced access.
Then enter your Redirect URIs
(set to <host>/facebook
) and press Save changes
:
次に、左側のメニューの Settings > Basic
に移動し、App ID
と App secret
を書き留めます。
これで、application.properties
を設定できます。
quarkus.oidc.provider=facebook
quarkus.oidc.client-id=<App ID>
quarkus.oidc.credentials.secret=<App secret>
quarkus.oidc.provider=facebook
will request Facebook to add email
and public_profile
scopes to issued access tokens. For information about overriding these scopes or requesting more scopes, see the プロバイダーのスコープ section.
GitHub
GitHub の OIDC を設定するには、 GitHub developer settings で新しい OAuth アプリケーションを作成する必要があります。
Make sure to fill in the appropriate details, but more importantly the Authorization Callback URL, set to http://localhost:8080/github
(if you intend to test this using the Quarkus dev mode).
次に、Register application
をクリックすると、アプリケーションページが表示されます。
Generate a new client secret
をクリックし、クレデンシャルを確認して、Client ID と Client Secret を書き留める必要があります (特に Client Secret は、後でこのページで再度見ることができないため、書き留めてください。ただし、いつでも再作成できますので、心配しすぎる必要はありません)。
次に、以下の設定を application.properties
に追加します。
quarkus.oidc.provider=github
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
quarkus.oidc.provider=github
will request GitHub to add a user:email
scope to issued access tokens. For information about overriding this scope or requesting more scopes, see the プロバイダーのスコープ section.
You can also send access tokens issued by GitHub to quarkus.oidc.application-type=service or quarkus.oidc.application-type=hybrid Quarkus applications.
|
OIDC for Google を設定するには、 Google Cloud Platform console で新しいプロジェクトを作成する必要があります。
プロジェクト名を選択し、CREATE
をクリックします。
次に、トップセレクターでプロジェクトを選択し、左側のメニューバーから APIs and Services > OAuth consent screen
をクリックします。
External
を選択して、Google ユーザーがアプリケーションにログインすることを許可し、CREATE
を押します。
これで、アプリケーション名、サポートメール、開発者の連絡先情報を入力して、SAVE AND CONTINUE
を押すことができます。
次のページにスコープを追加せずに、SAVE AND CONTINUE
を押します。
次のページにテストユーザーを追加せずに、SAVE AND CONTINUE
を押します。
トップメニューの CREATE CREDENTIALS
> OAuth client ID
をクリックします。
Select Web application
as Application type
, and add http://localhost:8080/google
in
the Authorised redirect URIs
list, then press CREATE
:
Client ID と Client Secret をコピーします。
これで、application.properties
を設定できます。
quarkus.oidc.provider=google
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
quarkus.oidc.provider=google
will request Google to add openid
, email
and profile
scopes to issued access tokens. For information about overriding these scopes or requesting more scopes, see the プロバイダーのスコープ section.
You can also send access tokens issued by Google to quarkus.oidc.application-type=service or quarkus.oidc.application-type=hybrid Quarkus applications.
|
Create a LinkedIn application:
Add the Sign In with LinkedIn using OpenId Connect
product:
You now can get your client id and secret. Don’t forget to also add the authorized redirect URLs for your application:
これで、application.properties
を設定できます。
quarkus.oidc.provider=linkedin
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret=<Client Secret>
Mastodon
マストドンアカウント を作成します。 サーバーを選択 する必要があります。例えば、 mastodon.social
。
アカウントで Development
オプションを選択し、アプリケーションを登録します。例:
登録されているアプリケーションを選択します:
クライアントIDとクライアント・シークレットのプロパティをメモしておき、 application.properties
の設定に使用する:
quarkus.oidc.provider=mastodon
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret.value=<Client Secret>
デフォルトでは、 quarkus.oidc.provider=mastodon
は quarkus.oidc.auth-server-url
を https://mastodon.social
に設定されます。
他のマストドンサーバーでアカウントを作成した場合など、 quarkus.oidc.auth-server-url
を上書きすることができます:
quarkus.oidc.provider=mastodon
quarkus.oidc.auth-server-url=https://infosec.exchange
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret.value=<Client Secret>
Microsoft
In order to set up OIDC for Microsoft you need to go to your Microsoft Azure Portal,
and search for Microsoft Entra ID
formerly known as Azure Active Directory
, then click on it:
そこで、左側の Manage
の下にある App registrations
をクリックしてから、New registration
をクリックします。
Fill in your application name, select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)
to allow anyone to log in, and add a Web
Redirect URI as http://localhost:8080/microsoft
,
then click on Register
:
その結果のページで、Client Id
(Application (client) ID
の下) をコピーしてから、Add a certificate or secret
をクリックします。
次に、Client secrets (0)
の下にある New client secret
をクリックします。
何も変更せずに、そのダイアログで Add
をクリックします。
結果のページで、Secret ID
をコピーします。
これで、application.properties
を設定できます。
quarkus.oidc.provider=microsoft
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
quarkus.oidc.provider=microsoft
will request Microsoft to add openid
, email
and profile
scopes to issued access tokens. For information about overriding these scopes or requesting more scopes, see the プロバイダーのスコープ section.
You can also send access tokens issued by Microsoft to quarkus.oidc.application-type=service or quarkus.oidc.application-type=hybrid Quarkus applications but you may need to set quarkus.oidc.verify-access-token-with-user-info configuration property to true if access tokens issued by Microsoft are not in JWT format.
|
Some Microsoft services may issue tokens whose signatures can only be verified if the current token’s
|
Slack
Create a Slack application:
Select application name, workspace, and remember it, you will need it later:
Please save client id and secret displayed on the next page, you will need them later:
Configure redirect URLs. Slack provider requires HTTPS protocol, for development purposes, you can use ngrok:
これで、application.properties
を設定できます。
quarkus.oidc.provider=slack
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Client Secret>
quarkus.oidc.authentication.extra-params.team=quarkus-slack (1)
1 | Use the team parameter to refer to the workspace you chose during the Slack OIDC application registration. |
Open your browser and navigate to your application https://<your ngrok instance>.ngrok-free.app/
.
Quarkus will redirect you to Slack provider on the first request where you can grant required permissions:
Spotify
Spotify application を作成します。
開発目的のテスト用に、リダイレクト URI として http://localhost:8080
を追加することを忘れないでください。Spotify アプリケーションのセットアップが完了すると、クライアント ID とシークレットが生成されます。以下に例を示します。
これで、application.properties
を設定できます。
quarkus.oidc.provider=spotify
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Client Secret>
quarkus.oidc.provider=spotify
will request Spotify to add user-read-private
and user-read-email
scopes to issued access tokens. For information about overriding these scopes or requesting more scopes, see the プロバイダーのスコープ section.
Strava
Create a Strava application:
For example, set Category
to SocialMotivation
, and set ApplicationCallbackDomain
to either localhost
or the domain name provided by Ngrok, see the HTTPS Redirect URI for more information.
これで、application.properties
を設定できます。
quarkus.oidc.provider=strava
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret=<Client Secret>
# default value is '/strava'
quarkus.oidc.authentication.redirect-path=/fitness/welcome (1)
1 | Strava does not enforce that the redirect (callback) URI which is provided as an authorization code flow parameter is equal to the URI registered in the Strava application because it only requires configuring ApplicationCallbackDomain . For example, if ApplicationCallbackDomain is set to www.my-strava-example.com , Strava will accept redirect URIs such as www.my-strava-example.com/a , www.my-strava-example.com/path/a , which is not recommended by OAuth2 best security practices, see Insufficient redirect_uri validation for more information.
Therefore you must configure a redirect path when working with the Strava provider and Quarkus will enforce that the current request path matches the configured quarkus.oidc.authentication.redirect-path value before completing the authorization code flow. See the Exact redirect URI match for more information. |
Twitch
Twitchアプリケーション を作成する:
これで、application.properties
を設定できます。
quarkus.oidc.provider=twitch
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret.value=<Client Secret>
X (formerly Twitter)
You can use X (formerly Twitter) for OIDC login, but at the moment, it restricts access to the user’s email, which means you will have to obtain it and verify it yourself.
In order to set up OIDC for X, start by Creating a project, enter a project name, and press Next
:
ユースケースを入力し、Next
を押します。
プロジェクトの説明を入力し、Next
を押します。
次に、アプリケーション名を入力して、Next
を押します。
キーは再び表示されないので書き留めて、App Settings
を押します。
User authentication settings
セクションに移動し、Set up
を押します。
OAuth 2.0
チェックボックスをオンにします。
アプリケーションタイプとして Web App
を選択し、アプリケーションの詳細を入力します (Callback URI
の場合は <host>/_renarde/security/twitter-success
を使用)。
X doesn’t require https usage in practice, but won’t accept your Website URL without it, so
you can still use ngrok for it.
|
次に、Save
を押します。
これで、Client ID
および Client Secret
をコピーして Done
を押すことができます。
これで、application.properties
を設定できます。
quarkus.oidc.provider=x
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Client Secret>
quarkus.oidc.provider=x
will request X to add offline.access
, tweet.read
and users.read
scopes to issued access tokens. For information about overriding these scopes or requesting more scopes, see the プロバイダーのスコープ section.
X provider requires Proof Key for Code Exchange (PKCE) which is supported by the You can provide your own secret key for encrypting the PKCE code verifier if you prefer with the |
X is the new name of Twitter. You can continue using |
プロバイダーのスコープ
Each provider declaration will request one or more token scopes added to access tokens issued by a given provider. For example, quarkus.oidc.provider=google
will request Google
to add openid
, email
and profile
scopes.
You can override these scopes with quarkus.oidc.authentication.scopes
property, for example, if you work with Google
and would not like to have an email
scope added to access tokens:
quarkus.oidc.provider=google
quarkus.oidc.authentication.scopes=oidc,profile
You may also want to add one or more scopes in addition to the scopes requested by default. For example, if you would like to use an access token issued by Google
to access Google Calendar
service, you can do it like this:
quarkus.oidc.provider=google
quarkus.oidc.authentication.extra-params.scope=https://www.googleapis.com/auth/calendar
It is simpler than using quarkus.oidc.authentication.scopes
to add a new scope, because quarkus.oidc.authentication.scopes
overrides the scopes already set by the provider declaration, which is why you need to list all the required scopes in this case:
quarkus.oidc.provider=google
quarkus.oidc.authentication.scopes=oidc,email,profile,https://www.googleapis.com/auth/calendar
複数プロバイダーのサポート
If you would like to support authenticating users with more than one provider then a provider-specific tenant configuration resolution must be supported.
For more information, see the Quarkus Using OpenID Connect (OIDC) Multi-Tenancy guide.
トークン伝搬によるプロバイダーサービスへのアクセス
Sometimes, only authenticating users with a social provider is not enough.
A provider-specific service also needs to be accessed for the Quarkus OIDC web-app
application to fetch or update data from the provider service on behalf of the currently authenticated user.
As mentioned in the OIDC code flow mechanism for protecting web applications guide, ID and access tokens are returned after the authorization code flow has been completed, with some providers like GitHub
returning an access token only.
It is this access token that has to be propagated to services such as Google Calendar
, or Spotify Playlists
for the currently authenticated user to be able to use such services.
You do not have to bring provider-specific libraries in order to achieve this, but instead you can use a reactive Token Propagation
filter, which can be bound to a given REST client with a simple annotation.
For more information, see the Quarkus Access token propagation guide.
For example, after you have configured the Google provider, you can have events added to the user’s Google Calendar by using a REST client as shown in the following example:
package org.acme.calendar;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.AccessToken;
import io.smallrye.mutiny.Uni;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
@RegisterRestClient(configKey="google-calendar-api")
@AccessToken (1)
@Path("/calendars/primary")
public interface GoogleCalendarClient {
@POST
@Path("events")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
Uni<String> addEvent(Event event);
public static class Event {
public String summary;
public String kind = "calendar#event";
public Time start;
public Time end
}
public static class Time {
public String dateTime;
public String timeZone = "Europe/CET";
public Time() {
}
public Time(String value) {
dateTime = value;
}
}
}
1 | @AccessToken アノテーションは、ターゲットサービスへのアクセストークンの伝播を可能にします。 |
Finally, you need to configure the Google Calendar address and request the Google Calendar scope for an access token, as outlined in the following example:
quarkus.oidc.provider=google
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
# Add a required calendar scope
quarkus.oidc.authentication.extra-params.scope=https://www.googleapis.com/auth/calendar
# Point REST client to Google Calendar endpoint
quarkus.rest-client.google-calendar-api.url=https://www.googleapis.com/calendar/v3
これで、ユーザーをGoogleで認証させ、例えば彼らの代わりに Google
カレンダーの更新をサポートする準備が整いました:
package org.acme.calendar;
import org.eclipse.microprofile.jwt.JsonWebToken;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import io.quarkus.oidc.IdToken;
import io.quarkus.security.Authenticated;
import io.smallrye.mutiny.Uni;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
@Path("/calendar")
@Authenticated
public class CalendarService {
@Inject
@IdToken
JsonWebToken jwt;
@Inject
@RestClient
GoogleCalendarClient calendarClient;
@GET
@Path("/event")
@Produces("text/plain")
public Uni<String> get() {
return calendarClient.addEvent(new Event()).onItem()
.transform(c -> ("Hello " + jwt.getName() + ", new event: " + c));
}
}
You must update the application registered with the Google provider to list http://localhost:8080/calendar/event
as one of the authorized redirect URIs if you would like to test this endpoint on the local host, for example:
また、1人以上のテストユーザーを登録する必要があるかもしれません:
エンドポイントが他のGoogleサービスにアクセスする必要がある場合も、同じ方法でアクセスする。
エンドポイントは、IDトークンかUserInfo(特に GitHub
のようなOAuth2のみのプロバイダが使用されている場合)を使用して、現在認証されているユーザーに関する情報を取得し、アクセストークンを使用して、このユーザーに代わって下流のサービス(プロバイダまたはアプリケーション固有のもの)にアクセスするという、所定のプロバイダで認証を行うパターンは、アプリケーションの安全性を確保するためにどのプロバイダが使用されているかに関係なく、普遍的に適用できます。
Exact redirect URI match
Most OIDC and OAuth2 providers with the exception of Strava will enforce that the authorization code flow can be completed only if the redirect URI matches precisely the redirect URI configured in a given provider’s dashboard.
From the practical point of view, your Quarkus endpoint will most likely need to have the quarkus.oidc.authentication.redirect-path
relative path property set to an initial entry path for all the authenticated users, for example, quarkus.oidc.authentication.redirect-path=/authenticated
, which means that newly authenticated users will land on the /authenticated
page, irrespectively of how many secured entry points your application has and which secured resource they initially accessed.
It is a typical flow for many OIDC web-app
applications. Once the user lands on the initial secured page, your application can return an HTML page which uses links to guide users to other parts of the application or users can be immediately redirected to other application resources with the help of JAX-RS API.
If necessary, you can configure Quarkus to restore the original request URI after the authentication has been completed. For example:
quarkus.oidc.provider=strava (1)
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
quarkus.oidc.authentication.restore-path-after-redirect=true (2)
1 | strava provider configuration is the only supported configuration which enforces the quarkus.oidc.authentication.redirect-path property with the /strava path which you can override with another path such as /fitness . |
2 | If the users access the /run endpoint before the authentication, then, once they have authenticated and been redirected to the configured redirect path such as /strava , they will land on the original request /run path. |
You do not have to set quarkus.oidc.authentication.redirect-path
immediately because Quarkus assumes the current request URL is an authorization code flow redirect URL if no quarkus.oidc.authentication.redirect-path
is configured. For example, to test that a Google authentication is working, you can have a Quarkus endpoint listening on /google
and update the Google dashboard that http://localhost:8080/google
redirect URI is supported. Setting quarkus.oidc.authentication.redirect-path
property will be required once your secured application URL space grows.
HTTPS Redirect URI
Some providers will only accept HTTPS-based redirect URIs. Tools such as ngrok can be set up to help testing such providers with Quarkus endpoints running on localhost in dev mode.
レート制限
Depending on your developer API subscription level, some providers may enforce a rather strict request rate limiting policy.
It may not be a problem when Quarkus fetches public verification keys from OIDC-compliant providers like the Google provider and keeps verifying the user session with these keys locally. However, for pure OAuth2 providers where only an access token is available and which has to be verified indirectly by requesting UserInfo from the provider endpoint on every request done by an already authenticated user, it can become a problem.
Therefore, UserInfo is embedded in an internally generated ID token and is encrypted in the session cookie. You can disable it with quarkus.oidc.cache-user-info-in-idtoken=false
.
Alternatively, use a default or custom UserInfo cache provider, please see the Token Introspection and UserInfo cache section of the "OpenID Connect (OIDC) Bearer token authentication" guide.