Project: Break The Glass - ForgeRock/frdp-uma-resource-server GitHub Wiki

Overview

There are situations where the Requesting Party (RqP) needs access to a resource when the Resource Owner (RO) is not able to grant access. A typical scenario would be an ER Doctor, a RqP, that needs emergency access to a patients medical records. The patient, the RO, has not previously granted the ER Doctor access. The ER Doctor needs to "Break The Glass" to obtain access.

A solution could involve a "privileged" Requesting Party, ER Doc, initiating a Request for access. The system could verify the "privileged" user and automatically grant / allow access to the resource. Transactions will be audited.

The existing applications and services shall be used, with minimal changes. There are no plans to implement a separate Client Application (RqP) to support this use case.

Designs

Assumptions

The "privileged" RqP (ER Doctor) would have a special Role / Group that would indicate they can "break the glass".
The RqP would be a member of an LDAP Group for users that can "break the glass".

Options

1: Authorization Server dynamically updates policy

2: Resource Server dynamically updates policy

This design is focused on leveraging the existing UMA protocol, as mush as possible. It's about having the RS dynamically add the RqP to the resource's policy, if needed. The RS gets a request for a resource which contains an extra "btg" scope. The RS checks that all of the following are true:

Resource has the "btg" scope
Request contains the "btg" scope
RqP is a member of the BTG Group ... NOTE: This option requires the RqP to be authenticated to the RS ... which is NOT part of the UMA protocol

Assuming all of the above conditions are true ... the RS determines if the RqP is not currently in the resource's policy, for the requested scopes. If not, it will automatically add/update the RqP in the resource's policy ... thus enabling access. After the policy has been automatically updated ... normal processing of the request will continue. The RS will get a Permission Ticket, from the AS, and return it to the CA. The CA will process the Permission Ticket (just like an other) ... the CA will get the Claim Token and then the RPT. The CA will use the RPT to get the resource, as per the standard protocol / flow.

Flow:

The "custom" non-standard UMA steps are bold and highlighted.

CA:
- RqP authenticates, normal level credential validation.
- Find the Resource for a given RO (assuming the RqP does not currently have access)
  - Extension consideration: enable the CA to browse resources that have the "btg" scope ... because the resource meta data may not have "discoverable" enabled.
- Submit request for access to the Resource. The request must include the "btg" scope, in addition to any others.
  - A stronger level of authentication may be leveraged to include the "btg" scope in the request.
RS:
- Request has no RPT
- If request contains "btg" scope AND resource has "btg" scope AND RqP is a member of BTG group
  - Update policy to include RqP (subject) using the requested scopes
    - Normal processing continues
      - Generate Permission Ticket and return to CA
CA:
- Get Authorization Code using SSO token, from the AS
- Get Claim Token, using Authorization Code, from the AS
- Get RPT, using Claim Token and Permission Ticket, from the AS ... this works because of the dynamically modified policy
- Send RPT and scopes to the RS
RS:
- Validates RPT, with AS
- Get the resource's content from the CS
- Returns a response based the scopes (meta, content, etc) to the CA
CA:
- The response (meta, content, etc.) is provided to the RqP
- enduser interface
  - Resource Owner can review access to resource
  - Resource Owner can review audit information

Impact:

Pro:

uses built-in UMA audit mechanism, viewable in ForgeRock product interfaces
still uses the standard RqP UMA resource flow
RO can view / manage automated access

Con:

The resource will have extra policies added for each RqP that activates the "BTG" process
User might want to remove the "BTG" RqP policies that are no longer needed

Implementation:

RS:
- add feature to check request for "btg" scope
- add feature to check resource for "btg" scope
- add feature to check for RqP in BTG group (in the resource access)
- add functionality to update resource's policy for the RqP
- update response to handle "BTG" condition and return resource / meta data instead of a Permission Ticket
CA:
- the basic functionality would should not need to be changed
- need to add user interface to invoke the "BTG" action
- optional:
- trigger higher level of authentication when "btg" scope is used.

3: Resource Server direct access / UMA bypass

This design proves direct access to a resource, bypassing the UMA protocol flow, when a request meets the "Break The Glass" criteria. It involves the RS checking for the following to be true:

Resource has the "btg" scope
Request contains the "btg" scope
RqP is a member of the BTG Group

Assuming all of the above are conditions are true ... the RS will skip all remaining UMA procedures / protocol flows. Normally when the RS receives a request without a valid RPT, a Permission Ticket is generated and returned to the CA. Then, the CA would continue with the UMA protocol flow, obtain an RPT, and then re-request access to the resource. In this design, when all the conditions are true, the RS will simply return the resource with related information (meta data) and scopes. This "bypass" response would appear just like a normal RPT request/response, to the CA.