mirror of https://github.com/authelia/authelia.git
132 lines
7.1 KiB
Markdown
132 lines
7.1 KiB
Markdown
---
|
|
title: "ADR1: OpenID Connect Client Authorization Policies"
|
|
description: "An official Architecture Decision Record"
|
|
date: 2024-06-16T09:32:59+10:00
|
|
weight: 1001
|
|
toc: true
|
|
seo:
|
|
title: "" # custom title (optional)
|
|
description: "" # custom description (recommended)
|
|
canonical: "" # custom canonical URL (optional)
|
|
noindex: false # false (default) or true
|
|
---
|
|
|
|
Date: May 28, 2024
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Submitters
|
|
|
|
- [James Elliott](https://github.com/james-d-elliott), [Authelia](https://github.com/authelia)
|
|
|
|
## Change Log
|
|
|
|
| Date | PR | Status | Notes |
|
|
|:----------:|:-------------------------------------------------------:|:--------:|:---------------------------------------------------------:|
|
|
| 2024-05-28 | [#7357](https://github.com/authelia/authelia/pull/7357) | Accepted | Initial Publication |
|
|
| 2024-06-22 | [#7450](https://github.com/authelia/authelia/pull/7450) | Accepted | Corrected Mistakes, Added More Context, Adjusted Template |
|
|
|
|
## Context
|
|
|
|
This ADR is necessary as it describes the method to properly handle OpenID Connect 1.0 based Authorization Request
|
|
Policies. In addition the Access Control Rules are incompatible with the OpenID Connect 1.0 Authorization Code Flow for
|
|
several reasons. These factors have clearly presented confusion in the community and this both helps to explain these
|
|
issues and prevent a potential development mistake in the future surrounding the reasons for avoiding this
|
|
functionality.
|
|
|
|
### Rational
|
|
|
|
While this is not the full extent of the reasons, the most impactful ones are as follows:
|
|
|
|
1. Several elements of the standard Access Control Rules do not have any standard associated with them that facilitates
|
|
the implementation. i.e. the method, resource URI, query parameters, and the client IP address are all not
|
|
communicated to the OpenID Connect 1.0 Provider.
|
|
2. The Authorization Code Flow only occurs a single time, meaning the policy is only considered during the initial
|
|
login.
|
|
3. The only thing that can be evaluated during the Refresh Flow is the subject itself as the Refresh Flow occurs from
|
|
the context of the relying party, meaning the only factor that can reliably be evaluated is the subject.
|
|
4. There are differing contexts by which the rules could be understood to be applied. While the subject rules apply
|
|
generally speaking for the life of a OpenID Connect 1.0 session none of the other criteria apply in this same way.
|
|
The combination of the fact these contexts are different and the fact the administrator could understand it different
|
|
to how it applies even with very clear documentation due to ignorance (i.e. unaware the documentation exists) or due
|
|
to unclear terminology (i.e. the OAuth 2.0 and OpenID Connect 1.0 specifications are vast and complex) it seems
|
|
abundantly clear this presents a significant security issue.
|
|
|
|
### Access Control Specific Elements Explainer
|
|
|
|
This section describes the various access control criteria elements and if they are compatible with the flows and if not
|
|
the reason they are not compatible.
|
|
|
|
Special Note: Some may theorize that some of these criteria can be used against the `redirect_uri`. However this is not
|
|
the purpose of these criteria; the purpose is to compare the resources the user is accessing.
|
|
|
|
Special Notes:
|
|
|
|
1. Some may theorize that some of these criteria can be used against the `redirect_uri`. However this is not
|
|
the purpose of these criteria; the purpose is to compare the resources the user is accessing. In addition several of
|
|
the criteria use regular expression syntax (i.e. `domain_regex`, `resources`, and `query`) however regular
|
|
expressions are not compatible with `redirect_uri` comparison as the OAuth 2.0 and OpenID Connect 1.0 standards
|
|
prohibit anything other than simple string comparison for the `redirect_uri`.
|
|
2. Some may theorize that the criteria that match the requested resource (i.e. `domain`, `domain_regex`, `resources`,
|
|
`methods`, and `query`) could be used to compare the resource the user is accessing. However this is not the case as
|
|
this would require the Relying Party (i.e. client) to make requests to the Authorization Server with the Access Token
|
|
for each request the Resource Owner (i.e. end-user) makes and no specification describes this functionality. The only
|
|
time there is a request to the Authorization Server which may contain information about what a user is trying to do
|
|
is during the Authorization Code Flow which is unfortunately absent all of this metadata.
|
|
|
|
Individual Criteria:
|
|
|
|
- The `domain`, `domain_regex`, `resources`, and `query` criteria:
|
|
- Compatability: None
|
|
- Reasoning: See Special Note 1 and 2.
|
|
- The `methods` criteria:
|
|
- Compatability: None
|
|
- Reasoning: See Special Note 2.
|
|
- The `subject` criteria:
|
|
- Compatability: Full
|
|
- Reasoning: While this is fully compatible due to other compatibility it makes sense to separate this specifically
|
|
for OpenID Connect 1.0.
|
|
- The `networks` criteria:
|
|
- Compatability: Partial
|
|
- Reasoning: While this is partially compatible due to other compatibility it makes sense to separate this
|
|
specifically for OpenID Connect 1.0. This is only partially compatible as the only times it realistically can be
|
|
used are during the Authorization Code Flow as the Resource Owner (i.e. user) is required to directly make the
|
|
request, or during the Client Credentials Flow as the Resource Owner is the client itself. This means if the users
|
|
IP address changes the tokens are still valid and there is no way to invalidate them. In addition if the Refresh
|
|
Flow is used the remote IP is not the Resource Owner with the exception of the Client Credentials Flow, it's the
|
|
Relying Party (i.e. client).
|
|
|
|
## Proposed Design
|
|
|
|
Implement a separate authorization policies configuration option specifically for OpenID Connect 1.0 client
|
|
registrations which allows setting a specific policy:
|
|
|
|
1. For the `subject` criteria i.e. username or groups.
|
|
2. Potentially for the `networks` criteria which is enforced at the Authorization Code Flow stage.
|
|
|
|
Potentially implement another separate relying parties policy which allows:
|
|
|
|
1. Limiting which remote IP's relying parties are allowed to use i.e. `networks`.
|
|
|
|
|
|
## Decision
|
|
|
|
The criteria for OpenID Connect 1.0 Authorization Policies will be strictly limited to the elements that make the most
|
|
sense. At the time of this decision being published the only element that is considered is the subject; however, there
|
|
is the possibility that the network criteria will be added in the future as a reasonable argument for why it may be
|
|
practical has been made.
|
|
|
|
In addition, we will aim to instead of implementing provider side policies to implement the elements that are part of
|
|
the specification such as the Authentication Method References claim (i.e. `amr`) which is already supported, and the
|
|
Requested Authentication Context Class Reference parameter (i.e. `acr_values`).
|
|
|
|
## Consequences
|
|
|
|
Several elements that administrators may be used to will not be implementable due to the above issues.
|
|
|
|
## Related ADRs
|
|
|
|
_N/A_
|