Skip to content

Commit

Permalink
Reorder well known providers and fix a few additional things
Browse files Browse the repository at this point in the history
gsmet committed Jun 4, 2024
1 parent aa298ca commit bc0655b
Showing 1 changed file with 235 additions and 235 deletions.
470 changes: 235 additions & 235 deletions docs/src/main/asciidoc/security-openid-connect-providers.adoc
Original file line number Diff line number Diff line change
@@ -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 `<host>/_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_<KEYID>.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=<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 <<provider-scope>> 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=<Client ID>
quarkus.oidc.credentials.client-secret=<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 `<host>/_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=<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 <<provider-scope>> 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=<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 <<provider-scope>> 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 <<provider-scope>> 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=<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 <<provider-scope>> 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 <<provider-scope>> 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=<Client ID>
quarkus.oidc.credentials.client-secret=<Client Secret>
----

[[mastodon]]
=== Mastodon
@@ -192,9 +387,9 @@ 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 <<provider-scope>> 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 <<provider-scope>> 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 `<host>/_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_<KEYID>.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=<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=spotify
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Client 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 <<provider-scope>> 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 <<provider-scope>> 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 <<redirect_url>> for more information.

image::oidc-facebook-4.png[role="thumb"]
You can now configure your `application.properties`:

Enter your `Redirect URIs` (set to `<host>/_renarde/security/oidc-success`) and press `Save changes`:
[source,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 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 <<exact_redirect_uri_match>> 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=<App ID>
quarkus.oidc.credentials.secret=<App secret>
quarkus.oidc.provider=twitch
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret.value=<Client 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 <<provider-scope>> 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=<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 <<provider-scope>> 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=<Client ID>
quarkus.oidc.credentials.client-secret.value=<Client Secret>
----

[[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=<Client ID>
quarkus.oidc.credentials.client-secret=<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=<Client ID>
quarkus.oidc.credentials.client-secret=<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 <<redirect_url>> for more information.

You can now configure your `application.properties`:

[source,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 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 <<exact_redirect_uri_match>> for more information.

[[provider-scope]]
== Provider scopes

0 comments on commit bc0655b

Please sign in to comment.