Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New CAEP event - Risk level change event #205

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

New CAEP event - Risk level change event #205

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4287686
Risk level change event
apoorvadeshpande-okta Sep 20, 2024
5499837
Update openid-caep-1_0.md
appsdesh Nov 5, 2024
4dc0213
Added risk_reason
appsdesh Nov 15, 2024
5376434
Shayne's review
appsdesh Nov 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions openid-caep-1_0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -822,6 +822,60 @@ The following is a non-normative example of a Session Presented event:
}}
~~~

## Risk Level Change {#risk-level-change}
Event Type URI:

`https://schemas.openid.net/secevent/caep/event-type/risk-level-change`

A vendor may deploy mechanisms to gather and analyze various signals associated with subjects such as users, devices, etc. These signals, which can originate from diverse channels and methods beyond the scope of this event description, are processed to derive an abstracted risk level representing the subject's current threat status.

The Risk Level Change event is employed by the Transmitter to communicate any modifications in a subject's assessed risk level at the time indicated by the `event_timestamp` field in the Risk Level Change event. The Transmitter may generate this event to indicate:

* User's risk has changed due to potential suspecious access from unknown destination, password compromise, addition of strong authenticator or other reasons.
* Device's risk has changed due to installation of unapproved software, connection to insecure pheripheral device, encryption of data or other reasons.
* Any other subject's risk changes due to variety of reasons.


### Event Specific Claims {#risk-level-change-event-specific-claims}

appsdesh marked this conversation as resolved.
Show resolved Hide resolved
risk_reason
: REQUIRED, JSON string indicates the reason that contributed to the risk level changes by the Transmitter.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
: REQUIRED, JSON string indicates the reason that contributed to the risk level changes by the Transmitter.
: REQUIRED, JSON object: a localizable message indicating the reason that contributed to the risk level changes by the Transmitter. The object MUST contain one or more key/value pairs, with a BCP47 {{RFC5646}} language tag as the key and the locale-specific administrative message as the value.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this REQUIRED? It seems like it ought to be an optional field

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

risk_reason is marked required since, without this, there is no benefit for the receiver to process such an event. Transmitter updating the risk will be a black box process and hinder the visibility.

Also, it may not make sense to localize the message as this is intended for the receiver to make sense why Tx decided to update the risk. This could become ENUM between Tx-Rx. (Happy to update the description if that clarifies)

User-visible messages would be part of reason_admin and reason_user which could be localized


current_level
: REQUIRED, JSON string indicates the current level of the risk for the subject. Value MUST be one of LOW, MEDIUM, HIGH
Copy link

@ysarig75 ysarig75 Nov 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mandating the use of a LOW, MEDIUM, HIGH for risk levels may be too restricted for some usage. Some Companies may want to use a numeric range (e.g., 1-5 or 1-10) instead without needing to map it into LOW, MEDIUM, HIGH range.

One option is to add some kind of an optional "risk type" or "risk system" that may indicates to receivers how the risk is calculated and how it is being represented

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assurance level change uses namespace, but in that example, there are standardized ways of representing levels.

In this case, I feel even the numeric system will be subjective, it will not help bring standardization.

Another option is to plainly define a score as an optional attribute that could satisfy your use case, but I believe that could be solved by adopting #221

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The assurance level change event has a "Any other value..." escape, that makes it possible to define your own namespace. I feel having a standard set of values - whether Low, Medium, High or 1-10, will improve interoperability, so I'm in favor of keeping it simple. Like Apoorva says, we can include additional information in the "event data" field. I feel the numeric range is slightly more expressive, and you could define LOW, MEDIUM and HIGH as three points in that range, so it subsumes that.

appsdesh marked this conversation as resolved.
Show resolved Hide resolved

previous_level
: OPTIONAL, JSON string indicates the previously known level of the risk for the subject. Value MUST be one of LOW, MEDIUM, HIGH. If the Transmitter omits this value, the Receiver MUST assume that the previous assurance level is unknown to the Transmitter.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
: OPTIONAL, JSON string indicates the previously known level of the risk for the subject. Value MUST be one of LOW, MEDIUM, HIGH. If the Transmitter omits this value, the Receiver MUST assume that the previous assurance level is unknown to the Transmitter.
: OPTIONAL, string: indicates the previously known level of the risk for the subject. Value MUST be one of LOW, MEDIUM, HIGH. If the Transmitter omits this value, the Receiver MUST assume that the previous assurance level is unknown to the Transmitter.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the second statement ought to be a SHOULD:

If the Transmitter omits this value, the Receiver SHOULD assume that the previous assurance level is unknown to the Transmitter.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following the same convention of the other CAEP events



### Examples {#risk-level-change-examples}
The following is a non-normative example of a Risk Level Change event:

~~~json
{
"iss": "https://idp.example.com/123456789/",
"jti": "24c63fb56e5a2d77a6b512616ca9fa24",
"iat": 1615305159,
"aud": "https://sp.example.com/caep",
"txn": 8675309,
"sub_id": {
"format": "iss_sub",
"iss": "https://idp.example.com/3456789/",
"sub": "[email protected]"
},
"events":{
"https://schemas.openid.net/secevent/caep/event-type/risk-level-change":{
"current_level": "LOW",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add "principal" to the example?

"previous_level": "HIGH",
"event_timestamp": 1615304991643,
"risk_reason":{
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be a string, not be a dict of language to string

"en": "User's password detected in the pwned password dump"
}
}
}
}
~~~

# Security Considerations
Any implementations of events described in this document SHOULD comply with the Shared Signals Framework {{SSF}}. Exchanging events described herein without complying with the Shared Signals Framework {{SSF}} may result in security issues.

Expand Down
Loading