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