From bc0655bbdee1fe1f005359ba685ecc1d1bc94f0b Mon Sep 17 00:00:00 2001 From: Guillaume Smet Date: Tue, 4 Jun 2024 13:32:32 +0200 Subject: [PATCH] Reorder well known providers and fix a few additional things --- .../security-openid-connect-providers.adoc | 470 +++++++++--------- 1 file changed, 235 insertions(+), 235 deletions(-) diff --git a/docs/src/main/asciidoc/security-openid-connect-providers.adoc b/docs/src/main/asciidoc/security-openid-connect-providers.adoc index 97dd18dbe5d86..2015d1160f206 100644 --- a/docs/src/main/asciidoc/security-openid-connect-providers.adoc +++ b/docs/src/main/asciidoc/security-openid-connect-providers.adoc @@ -29,6 +29,177 @@ This property can be used in `application.properties`, in xref:security-openid-c == Well Known Providers +[[apple]] +=== 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. + +Go to https://developer.apple.com/account/resources/identifiers/list[Create a new identifier] and press `+` + +image::oidc-apple-1.png[role="thumb"] + +Don't touch anything, keep `App IDs` selected, and press `Continue`: + +image::oidc-apple-2.png[role="thumb"] + +Don't touch anything, keep `App` selected, and press `Continue`: + +image::oidc-apple-3.png[role="thumb"] + +Enter a description and a Bundle ID (use your application package name): + +image::oidc-apple-4.png[role="thumb"] + +Then scroll down to find the `Sign in with Apple` Capability, select it, and press `Continue`: + +image::oidc-apple-5.png[role="thumb"] + +Write down your App ID Prefix, then press `Register`: + +image::oidc-apple-6.png[role="thumb"] + +Back on the `Identifiers` page, press `+`: + +image::oidc-apple-7.png[role="thumb"] + +Select `Service IDs` and press `Continue`: + +image::oidc-apple-8.png[role="thumb"] + +Enter a description and Bundle ID (use your application package name), then press `Continue`: + +image::oidc-apple-9.png[role="thumb"] + +Now press `Register`: + +image::oidc-apple-10.png[role="thumb"] + +Back on the service list, click on your newly created service: + +image::oidc-apple-11.png[role="thumb"] + +Enable `Sign in with Apple` and press `Configure`: + +image::oidc-apple-12.png[role="thumb"] + +Add your domain and return URL (set to `/_renarde/security/oidc-success`) and press `Next`: + +image::oidc-apple-13.png[role="thumb"] + +Now press `Done`: + +image::oidc-apple-14.png[role="thumb"] + +Now press `Continue`: + +image::oidc-apple-15.png[role="thumb"] + +And now press `Save`: + +image::oidc-apple-16.png[role="thumb"] + +Go to the https://developer.apple.com/account/resources/authkeys/list[Keys] page on the left menu, and press `+`: + +image::oidc-apple-17.png[role="thumb"] + +Fill in a key name, enable `Sign in with Apple`, and press `Configure`: + +image::oidc-apple-18.png[role="thumb"] + +Select your Primary App ID and press `Save`: + +image::oidc-apple-19.png[role="thumb"] + +Back on the key page, press `Continue`: + +image::oidc-apple-20.png[role="thumb"] + +Now press `Register`: + +image::oidc-apple-21.png[role="thumb"] + +Write down your `Key ID`, download your key and save it to your Quarkus application in `src/main/resources/AuthKey_.p8`: + +image::oidc-apple-22.png[role="thumb"] + +You can now configure your `application.properties`: + +[source,properties] +---- +quarkus.oidc.provider=apple +quarkus.oidc.client-id= +quarkus.oidc.credentials.jwt.key-file=AuthKey_.p8 +quarkus.oidc.credentials.jwt.token-key-id= +quarkus.oidc.credentials.jwt.issuer= +quarkus.oidc.credentials.jwt.subject=> section. + +[[discord]] +=== Discord + +Create a https://discord.com/developers/applications[Discord application]: + +image::oidc-discord-1.png[role="thumb"] + +You now can get your client id and secret: + +image::oidc-discord-2.png[role="thumb"] + +You can now configure your `application.properties`: + +[source,properties] +---- +quarkus.oidc.provider=discord +quarkus.oidc.client-id= +quarkus.oidc.credentials.client-secret= +---- + +[[facebook]] +=== Facebook + +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 https://developers.facebook.com/apps/create/[Creating an application], select `None` as an app type, and press `Next`: + +image::oidc-facebook-1.png[role="thumb"] + +Now enter an application name, and contact email, and press `Create app`: + +image::oidc-facebook-2.png[role="thumb"] + +On the app page, click `Set up` on the `Facebook login` product: + +image::oidc-facebook-3.png[role="thumb"] + +Quick the `Quickstarts` page and click on `Facebook login > Settings` on the left menu: + +image::oidc-facebook-4.png[role="thumb"] + +Enter your `Redirect URIs` (set to `/_renarde/security/oidc-success`) and press `Save changes`: + +image::oidc-facebook-5.png[role="thumb"] + +Now go to `Settings > Basic` on the left-hand menu, and write down your `App ID` and `App secret`: + +image::oidc-facebook-6.png[role="thumb"] + +You can now configure your `application.properties`: + +[source,properties] +---- +quarkus.oidc.provider=facebook +quarkus.oidc.client-id= +quarkus.oidc.credentials.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 @@ -37,7 +208,7 @@ In order to set up OIDC for GitHub you need to create a new OAuth application in image::oidc-github-1.png[role="thumb"] Make sure to fill in the appropriate details, but more importantly the Authorization Callback URL, set to `http://localhost:8080/_renarde/security/github-success` -(if you intend to test this using the Quarkus DEV mode). +(if you intend to test this using the Quarkus dev mode). Now click on `Register application` and you'll be shown your application page: @@ -58,9 +229,9 @@ quarkus.oidc.client-id= quarkus.oidc.credentials.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. +`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. -TIP: You can also send access tokens issued by `GitHub` to `quarkus.oidc.application-type=service` or `quarkus.oidc.application-type=hybrid` Quarkus applications. +TIP: You can also send access tokens issued by GitHub to `quarkus.oidc.application-type=service` or `quarkus.oidc.application-type=hybrid` Quarkus applications. [[google]] === Google @@ -113,9 +284,33 @@ quarkus.oidc.client-id= quarkus.oidc.credentials.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. +`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. -TIP: You can also send access tokens issued by `Google` to `quarkus.oidc.application-type=service` or `quarkus.oidc.application-type=hybrid` Quarkus applications. +TIP: You can also send access tokens issued by Google to `quarkus.oidc.application-type=service` or `quarkus.oidc.application-type=hybrid` Quarkus applications. + +[[linkedin]] +=== LinkedIn + +Create a https://developer.linkedin.com/[LinkedIn application]: + +image::oidc-linkedin-1.png[role="thumb"] + +Add the `Sign In with LinkedIn using OpenId Connect` product: + +image::oidc-linkedin-2.png[role="thumb"] + +You now can get your client id and secret. Don't forget to also add the authorized redirect URLs for your application: + +image::oidc-linkedin-3.png[role="thumb"] + +You can now configure your `application.properties`: + +[source,properties] +---- +quarkus.oidc.provider=linkedin +quarkus.oidc.client-id= +quarkus.oidc.credentials.client-secret= +---- [[mastodon]] === Mastodon @@ -192,9 +387,9 @@ quarkus.oidc.client-id= quarkus.oidc.credentials.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. +`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. -TIP: 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. +TIP: 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. [NOTE] ==== @@ -211,157 +406,66 @@ quarkus.oidc.token.customizer-name=azure-access-token-customizer ==== -[[apple]] -=== 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. - -Go to https://developer.apple.com/account/resources/identifiers/list[Create a new identifier] and press `+` - -image::oidc-apple-1.png[role="thumb"] - -Don't touch anything, keep `App IDs` selected, and press `Continue`: - -image::oidc-apple-2.png[role="thumb"] - -Don't touch anything, keep `App` selected, and press `Continue`: - -image::oidc-apple-3.png[role="thumb"] - -Enter a description and a Bundle ID (use your application package name): - -image::oidc-apple-4.png[role="thumb"] - -Then scroll down to find the `Sign in with Apple` Capability, select it, and press `Continue`: - -image::oidc-apple-5.png[role="thumb"] - -Write down your App ID Prefix, then press `Register`: - -image::oidc-apple-6.png[role="thumb"] - -Back on the `Identifiers` page, press `+`: - -image::oidc-apple-7.png[role="thumb"] - -Select `Service IDs` and press `Continue`: - -image::oidc-apple-8.png[role="thumb"] - -Enter a description and Bundle ID (use your application package name), then press `Continue`: - -image::oidc-apple-9.png[role="thumb"] - -Now press `Register`: - -image::oidc-apple-10.png[role="thumb"] - -Back on the service list, click on your newly created service: - -image::oidc-apple-11.png[role="thumb"] - -Enable `Sign in with Apple` and press `Configure`: - -image::oidc-apple-12.png[role="thumb"] - -Add your domain and return URL (set to `/_renarde/security/oidc-success`) and press `Next`: - -image::oidc-apple-13.png[role="thumb"] - -Now press `Done`: - -image::oidc-apple-14.png[role="thumb"] - -Now press `Continue`: - -image::oidc-apple-15.png[role="thumb"] - -And now press `Save`: - -image::oidc-apple-16.png[role="thumb"] - -Go to the https://developer.apple.com/account/resources/authkeys/list[Keys] page on the left menu, and press `+`: - -image::oidc-apple-17.png[role="thumb"] - -Fill in a key name, enable `Sign in with Apple`, and press `Configure`: - -image::oidc-apple-18.png[role="thumb"] - -Select your Primary App ID and press `Save`: - -image::oidc-apple-19.png[role="thumb"] - -Back on the key page, press `Continue`: - -image::oidc-apple-20.png[role="thumb"] +[[spotify]] +=== Spotify -Now press `Register`: +Create a https://developer.spotify.com/documentation/general/guides/authorization/app-settings/[Spotify application]: -image::oidc-apple-21.png[role="thumb"] +image::oidc-spotify-1.png[role="thumb"] -Write down your `Key ID`, download your key and save it to your Quarkus application in `src/main/resources/AuthKey_.p8`: +Don't forget to add `http://localhost:8080` as a redirect URI for testing during development purposes. You should get a client id and secret generated once a Spotify application setup has been complete, for example: -image::oidc-apple-22.png[role="thumb"] +image::oidc-spotify-2.png[role="thumb"] You can now configure your `application.properties`: [source,properties] ---- -quarkus.oidc.provider=apple -quarkus.oidc.client-id= -quarkus.oidc.credentials.jwt.key-file=AuthKey_.p8 -quarkus.oidc.credentials.jwt.token-key-id= -quarkus.oidc.credentials.jwt.issuer= -quarkus.oidc.credentials.jwt.subject= +quarkus.oidc.credentials.secret= ---- -`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. - -[[facebook]] -=== Facebook - -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 https://developers.facebook.com/apps/create/[Creating an application], select `None` as an app type, and press `Next`: - -image::oidc-facebook-1.png[role="thumb"] - -Now enter an application name, and contact email, and press `Create app`: +`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. -image::oidc-facebook-2.png[role="thumb"] +[[strava]] +=== Strava -On the app page, click `Set up` on the `Facebook login` product: +Create a https://www.strava.com/settings/api[Strava application]: -image::oidc-facebook-3.png[role="thumb"] +image::oidc-strava-1.png[role="thumb"] -Quick the `Quickstarts` page and click on `Facebook login > Settings` on the left menu: +For example, set `Category` to `SocialMotivation`, and set `ApplicationCallbackDomain` to either `localhost` or the domain name provided by Ngrok, see the <> for more information. -image::oidc-facebook-4.png[role="thumb"] +You can now configure your `application.properties`: -Enter your `Redirect URIs` (set to `/_renarde/security/oidc-success`) and press `Save changes`: +[source,properties] +---- +quarkus.oidc.provider=strava +quarkus.oidc.client-id= +quarkus.oidc.credentials.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 link:https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#name-insufficient-redirect-uri-v[Insufficent 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 authotization code flow. See the <> for more information. -image::oidc-facebook-5.png[role="thumb"] +[[twitch]] +=== Twitch -Now go to `Settings > Basic` on the left-hand menu, and write down your `App ID` and `App secret`: +Create a https://dev.twitch.tv/console/apps[Twitch application]: -image::oidc-facebook-6.png[role="thumb"] +image::oidc-twitch-1.png[role="thumb"] You can now configure your `application.properties`: [source,properties] ---- -quarkus.oidc.provider=facebook -quarkus.oidc.client-id= -quarkus.oidc.credentials.secret= +quarkus.oidc.provider=twitch +quarkus.oidc.client-id= +quarkus.oidc.credentials.client-secret.value= ---- -`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. - [[x]] === [[twitter]] X (formerly Twitter) @@ -436,110 +540,6 @@ note that this secret should be 32 characters long, and an error will be reporte X is the new name of Twitter. You can continue using `quarkus.oidc.provider=twitter` for the time being but it might become deprecated in the future. ==== -[[spotify]] -=== Spotify - -Create a https://developer.spotify.com/documentation/general/guides/authorization/app-settings/[Spotify application]: - -image::oidc-spotify-1.png[role="thumb"] - -Don't forget to add `http://localhost:8080` as a redirect URI for testing during development purposes. You should get a client id and secret generated once a Spotify application setup has been complete, for example: - -image::oidc-spotify-2.png[role="thumb"] - -You can now configure your `application.properties`: - -[source,properties] ----- -quarkus.oidc.provider=spotify -quarkus.oidc.client-id= -quarkus.oidc.credentials.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. - -[[twitch]] -=== Twitch - -Create a https://dev.twitch.tv/console/apps[Twitch application]: - -image::oidc-twitch-1.png[role="thumb"] - -You can now configure your `application.properties`: - -[source,properties] ----- -quarkus.oidc.provider=twitch -quarkus.oidc.client-id= -quarkus.oidc.credentials.client-secret.value= ----- - -[[discord]] -=== Discord - -Create a https://discord.com/developers/applications[Discord application]: - -image::oidc-discord-1.png[role="thumb"] - -You now can get your client id and secret: - -image::oidc-discord-2.png[role="thumb"] - -You can now configure your `application.properties`: - -[source,properties] ----- -quarkus.oidc.provider=discord -quarkus.oidc.client-id= -quarkus.oidc.credentials.client-secret= ----- - -[[linkedin]] -=== LinkedIn - -Create a https://developer.linkedin.com/[LinkedIn application]: - -image::oidc-linkedin-1.png[role="thumb"] - -Add the `Sign In with LinkedIn using OpenId Connect` product: - -image::oidc-linkedin-2.png[role="thumb"] - -You now can get your client id and secret. Don't forget to also add the authorized redirect URLs for your application: - -image::oidc-linkedin-3.png[role="thumb"] - -You can now configure your `application.properties`: - -[source,properties] ----- -quarkus.oidc.provider=linkedin -quarkus.oidc.client-id= -quarkus.oidc.credentials.client-secret= ----- - -[[strava]] -=== Strava - -Create a https://www.strava.com/settings/api[Strava application]: - -image::oidc-strava-1.png[role="thumb"] - -For example, set `Category` to `SocialMotivation`, and set `ApplicationCallbackDomain` to either `localhost` or the domain name provided by Ngrok, see the <> for more information. - -You can now configure your `application.properties`: - -[source,properties] ----- -quarkus.oidc.provider=strava -quarkus.oidc.client-id= -quarkus.oidc.credentials.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 link:https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#name-insufficient-redirect-uri-v[Insufficent 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 authotization code flow. See the <> for more information. - [[provider-scope]] == Provider scopes