<commit_before>////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= Configuring Well-Known OpenID Connect Providers

include::./attributes.adoc[]

== Introduction

If you use xref:security-openid-connect-web-authentication.adoc[OpenID Connect Authorization Code Flow] to protect Quarkus endpoints then you need to configure Quarkus to tell it how to connect to OpenID Connect providers, how to authenticate to such providers, which scopes to use, etc.

Sometimes you need to use the configuration to work around the fact that some providers do not implement OpenID Connect completely or when they are in fact xref:security-openid-connect-web-authentication.adoc#oauth2[OAuth2 providers only].

The configuration of such providers can become complex, very technical and difficult to understand.

`quarkus.oidc.provider` configuration property has been introduced to refer to well-known OpenID Connect and OAuth2 providers. This property can be used to refer to a provider such as `github` with only a minimum number of customizations required, typically, an account specific `client id`, `client secret` and some properties have to be set to complete the configuration.

This property can be used in `application.properties`, in xref:security-openid-connect-multitenancy.adoc[multi-tenant] set-ups if more than one provider has to be configured (for example, see https://quarkiverse.github.io/quarkiverse-docs/quarkus-renarde/dev/security.html#_using_oidc_for_login[Quarkus Renarde security documentation]), in custom xref:security-openid-connect-multitenancy.adoc#tenant-config-resolver[TenantConfigResolvers] if the tenant configurations are created dynamically.

== Well Known Providers

=== GitHub

In order to set up OIDC for GitHub you need to create a new OAuth application in your https://github.com/settings/applications/new[GitHub developer settings]:

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).

Now click on `Register application` and you'll be shown your application page:

image::oidc-github-2.png[role="thumb"]

You need to click on `Generate a new client secret`, confirm your credentials, and write down
your Client ID and Client secret (especially that one, because you will not be able to see it again
later from that page, but you can always recreate one, do don't worry too much):

image::oidc-github-3.png[role="thumb"]

Now add the following configuration to your `application.properties`:

[source,properties]
----
quarkus.oidc.provider=github
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
----

=== Google

In order to set up OIDC for Google you need to create a new project in your https://console.cloud.google.com/projectcreate[Google Cloud Platform console]:

Pick a project name and click on `CREATE`.

image::oidc-google-1.png[role="thumb"]

Now make sure you select your project in the top selector, and click on the left-hand bar menu on `APIs and Services > OAuth consent screen`:

image::oidc-google-2.png[role="thumb"]

Select `External` to authorise any Google user to log in to your application and press `CREATE`:

image::oidc-google-3.png[role="thumb"]

Now you can fill in your application name, your support email, your developer contact information and press `SAVE AND CONTINUE`:

image::oidc-google-4.png[role="thumb"]

Do not add any scopes on the next page, and press `SAVE AND CONTINUE`:

image::oidc-google-5.png[role="thumb"]

Do not add any test user on the next page, and press `SAVE AND CONTINUE`:

image::oidc-google-6.png[role="thumb"]

Click on the top menu `CREATE CREDENTIALS` > `OAuth client ID`:

image::oidc-google-7.png[role="thumb"]

Select `Web application` as `Application type`, and add `http://localhost:8080/_renarde/security/oidc-success` in
the `Authorised redirect URIs` list, then press `CREATE`:

image::oidc-google-8.png[role="thumb"]

Copy your Client ID and Client Secret:

image::oidc-google-9.png[role="thumb"]

You can now configure your `application.properties`:

[source,properties]
----
quarkus.oidc.provider=google
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
----

=== Microsoft

In order to set up OIDC for Microsoft you need to go to your https://portal.azure.com[Microsoft Azure Portal],
and search for `Azure Active Directory`, then click on it:

image::oidc-microsoft-1.png[role="thumb"]

Once there, on the left side under `Manage`, click on `App registrations` then click on `New registration`:

image::oidc-microsoft-2.png[role="thumb"]

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/_renarde/security/oidc-success`,
then click on `Register`:

image::oidc-microsoft-3.png[role="thumb"]

On that resulting page, copy the `Client Id` (under `Application (client) ID`, then click on `Add a certificate or secret`:

image::oidc-microsoft-4.png[role="thumb"]

Now, under `Client secrets (0)`, click on `New client secret`:

image::oidc-microsoft-5.png[role="thumb"]

Click on `Add` in that dialog without changing anything:

image::oidc-microsoft-6.png[role="thumb"]

On the resulting page, copy your `Secret ID`:

image::oidc-microsoft-7.png[role="thumb"]

You can now configure your `application.properties`:

[source,properties]
----
quarkus.oidc.provider=microsoft
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
----

=== 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"]
<commit_msg> security-openid-connect-prociders: Secret Value instead of Secret ID<commit_after>////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= Configuring Well-Known OpenID Connect Providers

include::./attributes.adoc[]

== Introduction

If you use xref:security-openid-connect-web-authentication.adoc[OpenID Connect Authorization Code Flow] to protect Quarkus endpoints then you need to configure Quarkus to tell it how to connect to OpenID Connect providers, how to authenticate to such providers, which scopes to use, etc.

Sometimes you need to use the configuration to work around the fact that some providers do not implement OpenID Connect completely or when they are in fact xref:security-openid-connect-web-authentication.adoc#oauth2[OAuth2 providers only].

The configuration of such providers can become complex, very technical and difficult to understand.

`quarkus.oidc.provider` configuration property has been introduced to refer to well-known OpenID Connect and OAuth2 providers. This property can be used to refer to a provider such as `github` with only a minimum number of customizations required, typically, an account specific `client id`, `client secret` and some properties have to be set to complete the configuration.

This property can be used in `application.properties`, in xref:security-openid-connect-multitenancy.adoc[multi-tenant] set-ups if more than one provider has to be configured (for example, see https://quarkiverse.github.io/quarkiverse-docs/quarkus-renarde/dev/security.html#_using_oidc_for_login[Quarkus Renarde security documentation]), in custom xref:security-openid-connect-multitenancy.adoc#tenant-config-resolver[TenantConfigResolvers] if the tenant configurations are created dynamically.

== Well Known Providers

=== GitHub

In order to set up OIDC for GitHub you need to create a new OAuth application in your https://github.com/settings/applications/new[GitHub developer settings]:

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).

Now click on `Register application` and you'll be shown your application page:

image::oidc-github-2.png[role="thumb"]

You need to click on `Generate a new client secret`, confirm your credentials, and write down
your Client ID and Client secret (especially that one, because you will not be able to see it again
later from that page, but you can always recreate one, do don't worry too much):

image::oidc-github-3.png[role="thumb"]

Now add the following configuration to your `application.properties`:

[source,properties]
----
quarkus.oidc.provider=github
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
----

=== Google

In order to set up OIDC for Google you need to create a new project in your https://console.cloud.google.com/projectcreate[Google Cloud Platform console]:

Pick a project name and click on `CREATE`.

image::oidc-google-1.png[role="thumb"]

Now make sure you select your project in the top selector, and click on the left-hand bar menu on `APIs and Services > OAuth consent screen`:

image::oidc-google-2.png[role="thumb"]

Select `External` to authorise any Google user to log in to your application and press `CREATE`:

image::oidc-google-3.png[role="thumb"]

Now you can fill in your application name, your support email, your developer contact information and press `SAVE AND CONTINUE`:

image::oidc-google-4.png[role="thumb"]

Do not add any scopes on the next page, and press `SAVE AND CONTINUE`:

image::oidc-google-5.png[role="thumb"]

Do not add any test user on the next page, and press `SAVE AND CONTINUE`:

image::oidc-google-6.png[role="thumb"]

Click on the top menu `CREATE CREDENTIALS` > `OAuth client ID`:

image::oidc-google-7.png[role="thumb"]

Select `Web application` as `Application type`, and add `http://localhost:8080/_renarde/security/oidc-success` in
the `Authorised redirect URIs` list, then press `CREATE`:

image::oidc-google-8.png[role="thumb"]

Copy your Client ID and Client Secret:

image::oidc-google-9.png[role="thumb"]

You can now configure your `application.properties`:

[source,properties]
----
quarkus.oidc.provider=google
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
----

=== Microsoft

In order to set up OIDC for Microsoft you need to go to your https://portal.azure.com[Microsoft Azure Portal],
and search for `Azure Active Directory`, then click on it:

image::oidc-microsoft-1.png[role="thumb"]

Once there, on the left side under `Manage`, click on `App registrations` then click on `New registration`:

image::oidc-microsoft-2.png[role="thumb"]

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/_renarde/security/oidc-success`,
then click on `Register`:

image::oidc-microsoft-3.png[role="thumb"]

On that resulting page, copy the `Client Id` (under `Application (client) ID`, then click on `Add a certificate or secret`:

image::oidc-microsoft-4.png[role="thumb"]

Now, under `Client secrets (0)`, click on `New client secret`:

image::oidc-microsoft-5.png[role="thumb"]

Click on `Add` in that dialog without changing anything:

image::oidc-microsoft-6.png[role="thumb"]

On the resulting page, copy your `Secret Value`:

image::oidc-microsoft-7.png[role="thumb"]

You can now configure your `application.properties`:

[source,properties]
----
quarkus.oidc.provider=microsoft
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
----

=== 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"]

{'fraction_non_alphanumeric': 0.10141313383208644, 'fraction_numerical': 0.006045492329781607, 'mean_word_length': 5.152487215248722, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 19, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3226134', 'n_tokens_mistral': 3910, 'n_tokens_neox': 3751, 'n_words': 1509}