ADR1: OpenID Connect Client Authorization Policies

Date: May 28, 2024

Status#

Accepted

Submitters#

• James Elliott, Authelia

Change Log#

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