# Configuring Well-Known OpenID Connect Providers

## Introduction

If you use 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, and so on.

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

## Well Known Providers

### GitHub

In order to set up OIDC for GitHub you need to create a new OAuth application in your GitHub developer settings:

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:

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

Now add the following configuration to your `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 Provider scopes section.

| You can also send access tokens issued by `GitHub` to `quarkus.oidc.application-type=service` or `quarkus.oidc.application-type=hybrid` Quarkus applications.

### Google

In order to set up OIDC for Google you need to create a new project in your Google Cloud Platform console:

Pick a project name and click on `CREATE`.

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`:

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

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

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

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

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

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

Copy your Client ID and Client Secret:

You can now configure your `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 Provider scopes section.

| You can also send access tokens issued by `Google` to `quarkus.oidc.application-type=service` or `quarkus.oidc.application-type=hybrid` Quarkus applications.

### Microsoft

In order to set up OIDC for Microsoft you need to go to your Microsoft Azure Portal, and search for `Azure Active Directory`, then click on it:

Once there, on the left side under `Manage`, click on `App registrations` then click on `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/_renarde/security/oidc-success`, then click on `Register`:

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

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

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

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

You can now configure your `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 Provider scopes 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 `nonce` header is reset with its SHA-256 digest value. If your application has to deal with such tokens then please enable an Azure token customizer:
    quarkus.oidc.provider=microsoft
    quarkus.oidc.client-id=<Client ID>
    quarkus.oidc.credentials.secret=<Secret>
    quarkus.oidc.token.customizer-name=azure-access-token-customizer

### 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 Create a new identifier and press `+`

Don’t touch anything, keep `App IDs` selected, and press `Continue`:

Don’t touch anything, keep `App` selected, and press `Continue`:

Enter a description and a Bundle ID (use your application package name):

Then scroll down to find the `Sign in with Apple` Capability, select it, and press `Continue`:

Write down your App ID Prefix, then press `Register`:

Back on the `Identifiers` page, press `+`:

Select `Service IDs` and press `Continue`:

Enter a description and Bundle ID (use your application package name), then press `Continue`:

Now press `Register`:

Back on the service list, click on your newly created service:

Enable `Sign in with Apple` and press `Configure`:

Add your domain and return URL (set to `<host>/_renarde/security/oidc-success`) and press `Next`:

Now press `Done`:

Now press `Continue`:

And now press `Save`:

Go to the Keys page on the left menu, and press `+`:

Fill in a key name, enable `Sign in with Apple`, and press `Configure`:

Select your Primary App ID and press `Save`:

Back on the key page, press `Continue`:

Now press `Register`:

Write down your `Key ID`, download your key and save it to your Quarkus application in `src/main/resources/AuthKey_<KEYID>.p8`:

You can now configure your `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 Provider scopes section.

### 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 Creating an application, select `None` as an app type, and press `Next`:

Now enter an application name, and contact email, and press `Create app`:

On the app page, click `Set up` on the `Facebook login` product:

Quick the `Quickstarts` page and click on `Facebook login > Settings` on the left menu:

Enter your `Redirect URIs` (set to `<host>/_renarde/security/oidc-success`) and press `Save changes`:

Now go to `Settings > Basic` on the left-hand menu, and write down your `App ID` and `App secret`:

You can now configure your `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 Provider scopes section.

### Twitter

You can use 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 Twitter start by Creating a project, enter a project name, and press `Next`:

Enter a use case, and press `Next`:

Enter a project description, and press `Next`:

Now enter an application name, and press `Next`:

Write down your keys, because they will not be displayed again, and press `App Settings`:

Navigate down to the `User authentication settings` section and press `Set up`:

Check the `OAuth 2.0` check box:

Select `Web App` as application type, then fill in your application details (use `<host>/_renarde/security/twitter-success` for the `Callback URI`).

| Twitter doesn’t require https usage in practice, but won’t accept your `Website URL` without it, so you can still use ngrok for it.

Now press `Save`:

You can now copy your `Client ID` and `Client Secret` and press `Done`:

You can now configure your `application.properties`:

    quarkus.oidc.provider=twitter
    quarkus.oidc.client-id=<Client ID>
    quarkus.oidc.credentials.secret=<Client Secret>

`quarkus.oidc.provider=twitter` will request `Twitter` 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 Provider scopes section.

| Twitter provider requires Proof Key for Code Exchange (PKCE) which is supported by the `quarkus.oidc.provider=twitter` declaration. Quarkus has to encrypt the current PKCE code verifier in a state cookie while the authorization code flow with Twitter is in progress and it will generate a secure random secret key for encrypting it. You can provide your own secret key for encrypting the PKCE code verifier if you prefer with the `quarkus.oidc.authentication.state-secret` property but note that this secret should be 32 characters long, and an error will be reported if it is less than 16 characters long.

### Spotify

Create a Spotify application:

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:

You can now configure your `application.properties`:

    quarkus.oidc.provider=spotify
    quarkus.oidc.client-id=<Client ID>
    quarkus.oidc.credentials.secret=<Client Secret>

`quarkus.oidc.provider=spotiify` 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 scopes section.

### Twitch

Create a Twitch application:

You can now configure your `application.properties`:

    quarkus.oidc.provider=twitch
    quarkus.oidc.client-id=<Client ID>
    quarkus.oidc.credentials.client-secret.value=<Client Secret>

## Provider scopes

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

## Support for multiple providers

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.

## Access provider services with token propagation

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 | The `@AccessToken` annotation enables an access token propagation to the target service.

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.authentication.extra-params.scope=https://www.googleapis.com/auth/calendar
    quarkus.rest-client.google-calendar-api.url=https://www.googleapis.com/calendar/v3

## HTTPS Redirect URL

Some providers will only accept HTTPS-based redirect URLs. Tools such as ngrok can be set up to help testing such providers with Quarkus endpoints running on localhost in devmode.

## References

- OIDC code flow mechanism for protecting web applications

- Quarkus Security overview