Skip to content

Spontaneous scopes

Jump to bottom
Alexander Altshuler edited this page Mar 12, 2020 · 16 revisions

Here should be all links about the spontaneous scopes as well as detailed design description.

Abbreviations are used in this document:

  • SS - spontaneous scope
  • PSS - particular spontaneous scope, should match one existing SS
  • PC - path capture
  • AT - OAuth2 Access Token
  • RPT - requesting party token, UMA access token associated with a set of authorization data, used by the client to gain access to protected resources at the resource server
  • PCRE - Perl compartible Regular Expression
  • GG - Gluu Gateway
  • GS - Gluu Server

OAuth2 Spontaneous Scopes workflow is straightforward, below is the summary.

  1. An OAuth2 client may register SS as regexp upon registration.
  2. Later it may request AT with PSS which match the SS regexp, for example ^user:.+$ - SS, user:123 - PSS.
  3. GS persists PSS with some TTL.
  4. GG may introspect AT and see a valid PSS.
  5. gluu-oauth-pep plugin may be provisioned to match not only to fixed scopes, but also against SS regexp.

Path capture (PC)

We use special wildcard/regexp notation for our PEP plugins.

Usually we need that SS match some path element, but it is not mandatory. The variable part of protected path may be detected as path capture. 2 types of our wildcard/regexp notation may catch path capture(s):

  • ? single path element
  • {<regexp)>} - regexp path element. Regexp may contain one or more PCRE capture group(s), otherwise the whole match is used as PC.

Allowing multiple wildcard elements ?? is considered too wide and cannot be used as path capture.

The particular spontaneous scope may be required to match a path capture.

The simplest example is a path with one path capture, e.g. /user/?/?? and one SS ^user:.+$. The real request path example /user/123abc/folder/page1. In order to access this page, the AT should be authorized with user:123abc scope.

But real world examples may include multiple PCs and SSs per protected resource, so we need to think about PC and SS mapping.

The simplest proposed solution:

Path captures may be numbered in accordance with its position in the path template, for example: Path template - /folder/?/transaction/{(.+)\-(.+)} We see here 3 PCs, first one from ? element and second and third from regexp.

We may refer to a path capture in spontaneous scope regexp using some convention, for example, PCRE named capturing group: ^user:(?P<PC1>.+)$

This approach works fine for OAuth2 use case, because we only need to match PSS against SS regexp. The same PCRE notation with named capturing group metadata may be used for both Gluu Server and for Gluu Gateway PEP.

But in UMA SS use case we need one additional operation - construct required PSS for a resource from SS and PCs. This operation is required when GG requests a ticket for a protected resource. Before it was oxd's responsibility to provide the required scopes for a ticket. With spontaneous scopes, we need to specify PSS is case of SS usage for a resource.

The example UMA workflow:

  1. gluu-uma-pep is configured to protect a resource with path template /user/?/??. Required scope regexp ^user:(?P<PC1>.+)$
  2. UMA client send unauthorized request to /user/123abc/edit.jsp page.
  3. GG doesn't see RPT and request the UMA tiket from GS.

yuriyz wrote https://github.com/GluuFederation/gluu-gateway/issues/410#issuecomment-577151568

There is additional scopes array parameter added in 4.2. It's already available but I can't give link to docs because it's not picked up. See https://github.com/GluuFederation/oxd/blob/master/oxd-server/src/main/resources/swagger.yaml#L1296

  1. gluu-uma-pep plugin should catch 123abc path capture #1 and replace named group PC1 in spontaneous scope regexp ^user:(?P<PC1>.+)$. So the requesting scope should be user:123abc.
  2. gluu-uma-pep call /uma-rs-check-access oxd endpoint with empty RPT and user:123abc scope.
  3. Gluu Server looks the protection document for the protected resource and matches scope user:123abc against ^user:(?P<PC1>.+)$ regexp.
  4. GS persists the scope user:123abc with configured TTL.
  5. Gluu Server responds with a ticket.
  6. GG responds with 401 and the ticket.
  7. UMA client request RPT by the ticket from GS.
  8. UMA client access the /user/123abc/edit.jsp path with the RPT.
  9. gluu-uma-pep call /uma-rs-check-access with RPT parameter.
  10. GS responds with access allow.

The syntax of a PCRE is too rich, and in general it's not possible to build a match from a PCRE and some known named groups. But we may add some SS regexp limitations, for example:

  • only named capturing groups are allowed
  • only named capturing groups may contain variable characters parts
  • accepted capturing group names are from PC1 to PC9, it should be enough, one single digit simplify parsing a lot
  • capturing groups shouldn't be nested and recursive
  • all special characters outside capturing groups should be escaped in accordance with PCRE rules

With limitations above, we may use same SS regexp for GS and GG. The implementation of such manual regexp parser/replacer is still not trivial. There may be some corner cases with special PCRE characters and so on. IMO proof-of-concept code is required first.

On GS side, the captures maybe ignored. But IMO it would be interesting for a policy script.

On GG side we may easily parse PCRE, check every PC against its definition and build resulting PSS.

References:

Support ticket with good UMA spontaneous scopes application: https://support.gluu.org/7344/

Github issues:

oxAuth SS: https://github.com/GluuFederation/oxAuth/issues/839 oxAuth UMA SS: https://github.com/GluuFederation/oxAuth/issues/1133

GG root SS issue: https://github.com/GluuFederation/gluu-gateway/issues/410 - closed in favor of 2 issues below.

GG OAauth2 SS issue: https://github.com/GluuFederation/gluu-gateway/issues/414 GG UMA SS issue: https://github.com/GluuFederation/gluu-gateway/issues/414

Clone this wiki locally