Skip to content

Commit

Permalink
feat(oidc): client authentication modes (#5150)
Browse files Browse the repository at this point in the history 
This adds a feature to OpenID Connect 1.0 where clients can be restricted to a specific client authentication mode, as well as implements some backend requirements for the private_key_jwt client authentication mode (and potentially the tls_client_auth / self_signed_tls_client_auth client authentication modes). It also adds some improvements to configuration defaults and validations which will for now be warnings but likely be made into errors.

Signed-off-by: James Elliott <james-d-elliott@users.noreply.github.com>
  • Loading branch information
@james-d-elliott
james-d-elliott committed Apr 13, 2023
1 parent db130da commit 3d2da0b
Show file tree
Hide file tree
Showing 64 changed files with 2,971 additions and 935 deletions.
15 changes: 8 additions & 7 deletions config.template.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1480,12 +1480,6 @@ notifier:
# - email
# - profile

## Grant Types configures which grants this client can obtain.
## It's not recommended to define this unless you know what you're doing.
# grant_types:
# - refresh_token
# - authorization_code

## Response Types configures which responses this client can be sent.
## It's not recommended to define this unless you know what you're doing.
# response_types:
Expand All @@ -1495,7 +1489,14 @@ notifier:
# response_modes:
# - form_post
# - query
# - fragment

## Grant Types configures which grants this client can obtain.
## It's not recommended to define this unless you know what you're doing.
# grant_types:
# - authorization_code

## The permitted client authentication method for the Token Endpoint for this client.
# token_endpoint_auth_method: client_secret_basic

## The policy to require for this client; one_factor or two_factor.
# authorization_policy: two_factor
Expand Down
54 changes: 38 additions & 16 deletions docs/content/en/configuration/identity-providers/open-id-connect.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -451,38 +451,47 @@ A list of scopes to allow this client to consume. See
documentation for the application you are trying to configure [OpenID Connect 1.0] for will likely have a list of scopes
or claims required which can be matched with the above guide.

#### grant_types

{{< confkey type="list(string)" default="refresh_token, authorization_code" required="no" >}}

*__Important Note:__ It is recommended that this isn't configured at this time unless you know what you're doing.*

The list of grant types this client is permitted to use in order to obtain access to the relevant tokens.

See the [Grant Types](../../integration/openid-connect/introduction.md#grant-types) section of the
[OpenID Connect 1.0 Integration Guide](../../integration/openid-connect/introduction.md#grant-types) for more information.

#### response_types

{{< confkey type="list(string)" default="code" required="no" >}}

*__Important Note:__ It is recommended that this isn't configured at this time unless you know what you're doing.*
*__Security Note:__ It is recommended that only the `code` response type (i.e. the default) is used. The other response
types are not as secure as this response type.*

A list of response types this client supports.
A list of response types this client supports. If a response type not in this list is requested by a client then an
error will be returned to the client. The response type indicates the types of values that are returned to the client.

See the [Response Types](../../integration/openid-connect/introduction.md#response-types) section of the
[OpenID Connect 1.0 Integration Guide](../../integration/openid-connect/introduction.md#response-types) for more information.

#### response_modes

{{< confkey type="list(string)" default="form_post, query, fragment" required="no" >}}
{{< confkey type="list(string)" default="form_post, query" required="no" >}}

*__Important Note:__ It is recommended that this isn't configured at this time unless you know what you're doing.*

A list of response modes this client supports.
A list of response modes this client supports. If a response mode not in this list is requested by a client then an
error will be returned to the client. The response mode controls how the response type is returned to the client.

See the [Response Modes](../../integration/openid-connect/introduction.md#response-modes) section of the
[OpenID Connect 1.0 Integration Guide](../../integration/openid-connect/introduction.md#response-modes) for more information.
[OpenID Connect 1.0 Integration Guide](../../integration/openid-connect/introduction.md#response-modes) for more
information.

The default values are based on the [response_types](#responsetypes) values. When the [response_types](#responsetypes)
values include the `code` type then the `query` response mode will be included. When any other type is included the
`fragment` response mode will be included. It's important to note at this time we do not support the `none` response
type, but when it is supported it will include the `query` response mode.

#### grant_types

{{< confkey type="list(string)" default="authorization_code" required="no" >}}

*__Important Note:__ It is recommended that this isn't configured at this time unless you know what you're doing.*

The list of grant types this client is permitted to use in order to obtain access to the relevant tokens.

See the [Grant Types](../../integration/openid-connect/introduction.md#grant-types) section of the
[OpenID Connect 1.0 Integration Guide](../../integration/openid-connect/introduction.md#grant-types) for more information.

#### authorization_policy

Expand Down Expand Up @@ -522,6 +531,18 @@ The algorithm used to sign the userinfo endpoint responses. This can either be `
See the [integration guide](../../integration/openid-connect/introduction.md#user-information-signing-algorithm) for
more information.

#### token_endpoint_auth_method

{{< confkey type="string" default="" required="no" >}}

The registered client authentication mechanism used by this client for the [Token Endpoint]. If no method is defined
the confidential client type will accept any supported method. The public client type defaults to `none` as this
is required by the specification. This may be required as a breaking change in future versions.
Supported values are `client_secret_basic`, `client_secret_post`, and `none`.

See the [integration guide](../../integration/openid-connect/introduction.md#client-authentication-method) for
more information.

#### consent_mode

{{< confkey type="string" default="auto" required="no" >}}
Expand Down Expand Up @@ -565,6 +586,7 @@ To integrate Authelia's [OpenID Connect 1.0] implementation with a relying party

[token lifespan]: https://docs.apigee.com/api-platform/antipatterns/oauth-long-expiration
[OpenID Connect 1.0]: https://openid.net/connect/
[Token Endpoint]: https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint
[JWT]: https://datatracker.ietf.org/doc/html/rfc7519
[RFC6234]: https://datatracker.ietf.org/doc/html/rfc6234
[RFC4648]: https://datatracker.ietf.org/doc/html/rfc4648
Expand Down
2 changes: 1 addition & 1 deletion docs/content/en/integration/kubernetes/istio.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ toc: true
---

Istio uses [Envoy](../proxies/envoy.md) as an Ingress. This means it has a relatively comprehensive integration option.
Istio is supported with Authelia v4.37.0 and higher via [Envoy]'s [external authorization] filter.
Istio is supported with Authelia v4.37.0 and higher via the [Envoy] proxy [external authorization] filter.

[external authorization]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-extauthz

Expand Down
113 changes: 76 additions & 37 deletions docs/content/en/integration/openid-connect/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,15 @@ documentation for some [OpenID Connect 1.0] Relying Party implementations.
See the [configuration documentation](../../configuration/identity-providers/open-id-connect.md) for information on how
to configure the Authelia [OpenID Connect 1.0] Provider.

This page is intended as an integration reference point for any implementers who wish to integrate an
[OpenID Connect 1.0] Relying Party (client application) either as a developer or user of the third party Reyling Party.

## Scope Definitions

The following scope definitions describe each scope supported and the associated effects including the individual claims
returned by granting this scope. By default we do not issue any claims which reveal the users identity which allows
administrators semi-granular control over which claims the client is entitled to.

### openid

This is the default scope for [OpenID Connect 1.0]. This field is forced on every client by the configuration validation
Expand Down Expand Up @@ -54,9 +61,16 @@ This scope is a special scope designed to allow applications to obtain a [Refres
an application on behalf of a user. A [Refresh Token] is a special [Access Token] that allows refreshing previously
issued token credentials, effectively it allows the relying party to obtain new tokens periodically.

As per [OpenID Connect 1.0] Section 11 [Offline Access] can only be granted during the [Authorization Code Flow] or a
[Hybrid Flow]. The [Refresh Token] will only ever be returned at the [Token Endpoint] when the client is exchanging
their [OAuth 2.0 Authorization Code].

Generally unless an application supports this and actively requests this scope they should not be granted this scope via
the client configuration.

It is also important to note that we treat a [Refresh Token] as single use and reissue a new [Refresh Token] during the
refresh flow.

### groups

This scope includes the groups the authentication backend reports the user is a member of in the [Claims] of the
Expand Down Expand Up @@ -92,43 +106,21 @@ This scope includes the profile information the authentication backend reports a
The following section describes advanced parameters which can be used in various endpoints as well as their related
configuration options.

### Grant Types

The following describes the various [OAuth 2.0] and [OpenID Connect 1.0] grant types and their support level. The value
field is both the required value for the `grant_type` parameter in the authorization request and the `grant_types`
configuration option.

| Grant Type | Supported | Value | Notes |
|:-----------------------------------------------:|:---------:|:----------------------------------------------:|:-------------------------------------------------------------------:|
| [OAuth 2.0 Authorization Code] | Yes | `authorization_code` | |
| [OAuth 2.0 Resource Owner Password Credentials] | No | `password` | This Grant Type has been deprecated and should not normally be used |
| [OAuth 2.0 Client Credentials] | Yes | `client_credentials` | |
| [OAuth 2.0 Implicit] | Yes | `implicit` | This Grant Type has been deprecated and should not normally be used |
| [OAuth 2.0 Refresh Token] | Yes | `refresh_token` | |
| [OAuth 2.0 Device Code] | No | `urn:ietf:params:oauth:grant-type:device_code` | |
|

[OAuth 2.0 Authorization Code]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1
[OAuth 2.0 Implicit]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.2
[OAuth 2.0 Resource Owner Password Credentials]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.3
[OAuth 2.0 Client Credentials]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4
[OAuth 2.0 Refresh Token]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.5
[OAuth 2.0 Device Code]: https://datatracker.ietf.org/doc/html/rfc8628#section-3.4

### Response Types

The following describes the supported response types. See the [OAuth 2.0 Multiple Response Type Encoding Practices] for
more technical information.

| Flow Type | Values |
|:-------------------------:|:---------------------:|
| [Authorization Code Flow] | `code` |
| [Implicit Flow] | `token id_token` |
| [Implicit Flow] | `id_token` |
| [Implicit Flow] | `token` |
| [Hybrid Flow] | `code token` |
| [Hybrid Flow] | `code id_token` |
| [Hybrid Flow] | `code token id_token` |
more technical information. The default response modes column indicates which response modes are allowed by default on
clients configured with this flow type value. If more than a single response type is configured

| Flow Type | Value | Default [Response Modes](#response-modes) Values |
|:-------------------------:|:---------------------:|:------------------------------------------------:|
| [Authorization Code Flow] | `code` | `form_post`, `query` |
| [Implicit Flow] | `id_token token` | `form_post`, `fragment` |
| [Implicit Flow] | `id_token` | `form_post`, `fragment` |
| [Implicit Flow] | `token` | `form_post`, `fragment` |
| [Hybrid Flow] | `code token` | `form_post`, `fragment` |
| [Hybrid Flow] | `code id_token` | `form_post`, `fragment` |
| [Hybrid Flow] | `code id_token token` | `form_post`, `fragment` |

[Authorization Code Flow]: https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth
[Implicit Flow]: https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth
Expand All @@ -139,16 +131,60 @@ more technical information.
### Response Modes

The following describes the supported response modes. See the [OAuth 2.0 Multiple Response Type Encoding Practices] for
more technical information.
more technical information. The default response modes of a client is based on the [Response Types](#response-types)
configuration.

| Name | Value |
|:---------------------:|:-----------:|
| [OAuth 2.0 Form Post] | `form_post` |
| Query String | `query` |
| Fragment | `fragment` |
| [OAuth 2.0 Form Post] | `form_post` |

[OAuth 2.0 Form Post]: https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html

### Grant Types

The following describes the various [OAuth 2.0] and [OpenID Connect 1.0] grant types and their support level. The value
field is both the required value for the `grant_type` parameter in the authorization request and the `grant_types`
configuration option.

| Grant Type | Supported | Value | Notes |
|:-----------------------------------------------:|:---------:|:----------------------------------------------:|:-----------------------------------------------------------------------------------------------:|
| [OAuth 2.0 Authorization Code] | Yes | `authorization_code` | |
| [OAuth 2.0 Resource Owner Password Credentials] | No | `password` | This Grant Type has been deprecated and should not normally be used |
| [OAuth 2.0 Client Credentials] | No | `client_credentials` | |
| [OAuth 2.0 Implicit] | Yes | `implicit` | This Grant Type has been deprecated and should not normally be used |
| [OAuth 2.0 Refresh Token] | Yes | `refresh_token` | This Grant Type should genreally only be used for clients which have the `offline_access` scope |
| [OAuth 2.0 Device Code] | No | `urn:ietf:params:oauth:grant-type:device_code` | |
|

[OAuth 2.0 Authorization Code]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1
[OAuth 2.0 Implicit]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.2
[OAuth 2.0 Resource Owner Password Credentials]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.3
[OAuth 2.0 Client Credentials]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4
[OAuth 2.0 Refresh Token]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.5
[OAuth 2.0 Device Code]: https://datatracker.ietf.org/doc/html/rfc8628#section-3.4

### Client Authentication Method

The following describes the supported client authentication methods. See the [OpenID Connect 1.0 Client Authentication]
specification and the [OAuth 2.0 - Client Types] specification for more information.

| Description | Value / Name | Supported Client Types | Default for Client Type | Assertion Type |
|:------------------------------------:|:-----------------------------:|:----------------------:|:-----------------------:|:--------------------------------------------------------:|
| Secret via HTTP Basic Auth Scheme | `client_secret_basic` | `confidential` | N/A | N/A |
| Secret via HTTP POST Body | `client_secret_post` | `confidential` | N/A | N/A |
| JWT (signed by secret) | `client_secret_jwt` | Not Supported | N/A | `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` |
| JWT (signed by private key) | `private_key_jwt` | Not Supported | N/A | `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` |
| [OAuth 2.0 Mutual-TLS] | `tls_client_auth` | Not Supported | N/A | N/A |
| [OAuth 2.0 Mutual-TLS] (Self Signed) | `self_signed_tls_client_auth` | Not Supported | N/A | N/A |
| No Authentication | `none` | `public` | `public` | N/A |


[OpenID Connect 1.0 Client Authentication]: https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication
[OAuth 2.0 Mutual-TLS]: https://datatracker.ietf.org/doc/html/rfc8705
[OAuth 2.0 - Client Types]: https://datatracker.ietf.org/doc/html/rfc8705#section-2.1

## Authentication Method References

Authelia currently supports adding the `amr` [Claim] to the [ID Token] utilizing the [RFC8176] Authentication Method
Expand Down Expand Up @@ -289,10 +325,13 @@ The advantages of this approach are as follows:

[JSON Web Key Set]: https://datatracker.ietf.org/doc/html/rfc7517#section-5

[Offline Access]: https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess

[Authorization]: https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint
[Pushed Authorization Requests]: https://datatracker.ietf.org/doc/html/rfc9126
[Token]: https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint
[UserInfo]: https://openid.net/specs/openid-connect-core-1_0.html#UserInfo

[Pushed Authorization Requests]: https://datatracker.ietf.org/doc/html/rfc9126
[Introspection]: https://datatracker.ietf.org/doc/html/rfc7662
[Revocation]: https://datatracker.ietf.org/doc/html/rfc7009
[Proof Key Code Exchange]: https://www.rfc-editor.org/rfc/rfc7636.html
Expand Down
2 changes: 1 addition & 1 deletion docs/content/en/integration/proxies/envoy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ Below you will find commented examples of the following configuration:

### Example

Support for [Envoy] is possible with Authelia v4.37.0 and higher via [Envoy]'s [external authorization] filter.
Support for [Envoy] is possible with Authelia v4.37.0 and higher via the [Envoy] proxy [external authorization] filter.

[external authorization]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-extauthz

Expand Down

0 comments on commit 3d2da0b

Please sign in to comment.