Skip to content

Commit

Permalink
incorporated subject identifiers from RFC9493
Browse files Browse the repository at this point in the history
  • Loading branch information
@tulshi
tulshi committed Dec 11, 2023
1 parent 4fcc754 commit 260fd58
Showing 1 changed file with 102 additions and 25 deletions.
127 changes: 102 additions & 25 deletions api/authorization-api-1_0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ normative:
RFC6750: #OAuth 2.0 Bearer Tokens
RFC8259: #JSON
RFC9110: # HTTP Semantics
RFC9493: # Subject Identifiers for SETs
XACML:
title: eXtensible Access Control Markup Language (XACML) Version 1.1
target: https://www.oasis-open.org/committees/xacml/repository/cs-xacml-specification-1.1.pdf
Expand Down Expand Up @@ -128,27 +129,61 @@ X-Request-ID: bfe9eb29-ab87-4ca3-be83-a1d5d8305716
## Subjects {#subjects}
A Subject is the user or robotic principal about whom the Authorization API is being invoked. The Subject may be requesting access at the time the Authorization API is invoked, or the Subject may be of interest in a Search API call.

A Subject is a JSON ({{RFC8259}}) object that has the following fields:
A Subject is in the format specified by the `Subject Identifiers for Security Event Tokens` specification {{RFC9493}}. A Subject MUST include at least one identifier, but MAY include more than one identifier if the format of the field is of type `aliases`.

id:
: REQUIRED. A field, whose value is of type `string`, which uniquely identifies the user within the scope of a PEP. This identifier could be an email address, or it might be an internal identifier such as a UUID or employee ID.
The following new Subject Identifier Formats SHALL be added to the `Security Event Identifier Formats Registry` IANA Repository, as defined in the {{IANA}} section below:

### IP Address {#subject-ip-address}
The IP Address of the Subject. The IP Address Subject Identifier Format is identified by the name `ip_address`. It identifies the IP Address of the subject, identified with an `ip_address` field, whose value is a textual representation of an IP Address, as defined in `Textual Conventions for Internet Network Addresses` {{RFC4001}}.

The following is a non-normative example of a Subject Identifier Format of type IP Address:

ipAddress:
: OPTIONAL. A field, whose value is of type `string`, which is a {{RFC4001}} text representation of the IP Address
~~~ json
{
"format": "ip_address",
"ip_address": "172.217.22.14"
}
~~~
{: #ipaddresssubjectexample title="Example IP Address format Subject Identifier"}

deviceId:
: OPTIONAL. A field, whose value is of type `string`, which uniquely identifies the device of the Subject
### Device Identifier {#subject-device-id}
The Device Identifier of the Subject. The Device Identifier Subject Identifier Format is identified by the name `device_id`. It identifies the Device Identifier of the subject, identified with a `device_id` field, whose value is a string representation of the device identifier.

The following non-normative example describes a Subject:
The following is a non-normative example of a Subject Identifier Format of type Device Identifier:

~~~ json
{
"id": "[email protected]",
"ipAddress": "172.217.22.14",
"deviceId": "8:65:ee:17:7e:0b"
"format": "device_id",
"device_id": "8:65:ee:17:7e:0b"
}
~~~
{: #subjectexample title="Example Subject Object"}
{: #deviceidssubjectexample title="Example Device Identifier format Subject Identifier"}

### Multiple Subject Identifier Formats {#subject-multi-format}
A Subject may be described using multiple formats, using the `aliases` Subject Identifier Format. The individual subject identifiers within the `aliases` Subject Identifier Format are interpreted to mean different attributes of the same Subject.

The following non-normative example describes a Subject with multiple formats:

~~~ json
{
"format": "aliases",
"identifiers": [
{
"format": "email",
"email": "[email protected]"
},
{
"format": "ip_address",
"ip_address": "172.217.22.14"
},
{
"format": "device_id",
"device_id": "8:65:ee:17:7e:0b"
}
]
}
~~~
{: #subjectexample title="Example Subject Identifier using multiple formats"}

## Resources {#resources}
An Resource is the target of an access request. It is a JSON ({{RFC8259}}) object that has the following fields:
Expand Down Expand Up @@ -383,7 +418,8 @@ X-Request-ID: bfe9eb29-ab87-4ca3-be83-a1d5d8305716

{
"subject": {
"id": "[email protected]",
"format": "email",
"email": "[email protected]",
},
"queries": [
{
Expand Down Expand Up @@ -516,8 +552,19 @@ Authorization: <myoauthtoken>

{
"subject": {
"id": "[email protected]"
"ipAddress": "172.217.22.14",
{
"format": "aliases",
"identifiers": [
{
"format": "email",
"email": "[email protected]"
},
{
"format": "ip_address",
"ip_address": "172.217.22.14"
}
]
}
}
"queries": ["delete", "read"],
}
Expand Down Expand Up @@ -576,9 +623,20 @@ X-Request-ID: bfe9eb29-ab87-4ca3-be83-a1d5d8305720
"iat": 1234567890,
"exp": 1234568890,
"subject": {
"id": "[email protected]"
"ipAddress": "172.217.22.14",
}
{
"format": "aliases",
"identifiers": [
{
"format": "email",
"email": "[email protected]"
},
{
"format": "ip_address",
"ip_address": "172.217.22.14"
}
]
}
},
"decisions": [
{
"action": "read",
Expand Down Expand Up @@ -682,9 +740,12 @@ The following is a non-normative example of a Subject Query Decision:
"createDate",
"lastUpdated"
],
"subject": {
"id": "[email protected]"
"subject": {
{
"format": "email",
"email": "[email protected]"
}
}
}
~~~
{: #example-subject-query-decision title="Example Subject Query Decision"}
Expand Down Expand Up @@ -718,7 +779,8 @@ X-Request-ID: bfe9eb29-ab87-4ca3-be83-a1d5d8305720
"author"
],
"subject": {
"id": "[email protected]"
"format": "email",
"email": "[email protected]"
}
},
{
Expand All @@ -729,7 +791,8 @@ X-Request-ID: bfe9eb29-ab87-4ca3-be83-a1d5d8305720
"lastUpdated"
],
"subject": {
"id": "[email protected]"
"format": "email",
"email": "[email protected]"
}
},
{
Expand All @@ -740,9 +803,10 @@ X-Request-ID: bfe9eb29-ab87-4ca3-be83-a1d5d8305720
"lastUpdated"
],
"subject": {
"id": "[email protected]"
"format": "email",
"email": "[email protected]"
}
}
}
],
"nextPageToken": "1DlR0Em5panAPy5llasLPfNUpDztEKgTDKF2I5gPwymnc"
}
Expand All @@ -751,8 +815,21 @@ X-Request-ID: bfe9eb29-ab87-4ca3-be83-a1d5d8305720

# IANA Considerations {#IANA}

TBS
The following Subject Identifier Formats SHALL be added to the "Security Event Identifier Formats" Registry as described in "Subject Identifiers for Security Event Tokens" {{RFC9493}}:

## IP Address {#ipaddress-registry-entry}

* Format Name: ip_address
* Format Description: A value that describes a subject through its IP Address
* Change Controller: OpenID Foundation
* Reference: Section {{subject-ip-address}} of the Authorization API specification

## Device Identifier {#deviceid-registry-entry}

* Format Name: device_id
* Format Description: A value that describes a subject through its device identifier
* Change Controller: OpenID Foundation
* Reference: Section {{subject-device-id}} of the Authorization API specification

# Security Considerations {#Security}

Expand Down

0 comments on commit 260fd58

Please sign in to comment.