Subject: [scim] SCIM Redirect Support Clarification - Draft Proposal

From: Phil Hunt <[email-masked]>
Date: Wed, 11 Dec 2013 12:10:27 -0800

The following is a new section to be added to draft-ietf-scim-api.  This provides clarification as to what HTTP redirects clients must support.  

My thought is we need to support 5.0 through 5.2.  

Section 5.2.1 (aliases) may be somewhat more controversial and thus has been written as an optional feature. I do agree strongly with the concern not to have multiple URIs for a resource. My thought here is that by using a redirect as a compromise, the redirect encourages the client to use the proper URL and thus might be seen as self-healing over time.  Yet at the same time, it does solve some scenarios where the client may be aware of a user-id but is not able to conveniently obtain the user's URI in advance.

In other cases, temporary and permanent redirection seem like a natural requirement for any REST service over time.  Though I must confess in many cases the issue is reduced since service providers would tend to coordinate with clients when data set URIs are changed as part of a service migration.

Proposed text:

5.0 Redirection Support

Section 10.3 of the HTTP specification [RFC2616] defines several redirect response codes normally used to redirect user-agents (browsers) in response to HTTP requests. As SCIM is not intended for user-agents, this section clarifies the use of HTTP redirection codes.

In order to preserve the integrity of SCIM operations, HTTP redirection codes 301-306 SHOULD NOT be used unless the service provider is aware the client is in fact a user-agent.  Redirection code 301-306 are require the clients to convert requests to HTTP GET or HEAD and are not normally suitable.
"The action required MAY be carried out by the user agent without interaction with the user if and only if the method used in the second request is GET or HEAD."

Because SCIM is a RESTful API and is normally performed without user interaction, HTTP redirection SHOULD preserve the integrity of requests after a redirect. This section clarifies the use of HTTP redirect code 307, as defined in [RFC2616] and HTTP Redirect code 308 as defined in [draft-reschke-http-status-308]. In both cases, the processing rules for Redirect 307 and 308 are to be applied.

Upon receiving a redirect, SCIM clients SHOULD preserve the HTTP action and SCIM operation by applying it to the new resource location specified in the redirect.

SCIM servers MAY issue two types of HTTP redirects:  HTTP redirect 307 for temporary redirection and HTTP redirect 308 for permanent redirection.

5.1 Temporary Redirection

A service provider MAY temporarily redirect clients using HTTP 307 as specified in RFC2616. The original HTTP action MUST be preserved. Clients MUST ensure that the new location keeps the operation intent intact.

The SCIM client MUST use the original permanent URI when referencing the affected SCIM resource in any other SCIM operations or SCIM resource (e.g. such as a Group).

If there is no user-agent involved in the transaction, the SCIM client MAY proceed by automatically processing the redirect.

5.2 Permanent Redirection

In the event that a SCIM resource has been relocated or reassigned, a service provider MAY issue an HTTP 308 redirect as specified in [draft-reschke-http-status-308]. This redirect informs the SCIM client of the new permanent URI for the object. 

SCIM clients MUST ensure that the new address keeps the operation intent intact and the same HTTP verb is used.

The SCIM client MUST use the new permanent URI when referencing the affected SCIM resource in any other SCIM operations or SCIM resource (e.g. such as a Group).

If there is no user-agent involved in the transaction, the SCIM client MAY proceed by automatically processing the redirect.

5.2.1 Alias Redirection

A SCIM service provider MAY support aliases by using HTTP 308 redirection [draft-reschke-http-status-308].  

Servers that DO NOT support aliases SHOULD respond with HTTP 404 (not found) if an aliased request is received or is not otherwise resolvable.

An aliases SHALL use HTTP 308 permanent redirects and follow the same processing rules in section [section 5.2].

5.2.1.1 Self-Referencing

In situations where the client wishes to refer to the current security context of the user, the server may translate a URI ending in "/me" to mean the resource represented by current authenticated subject. 

If "/me" does not resolve to a resource within the service endpoint requested, the service provider MUST respond with HTTP 404 (not found). If subject is resolved to a local resource, the service provider MAY use HTTP 308 to redirect the SCIM client to the permanent URI of the authenticated subject.

5.2.1.2 Unique-Key Reference

A client may wish to reference a resource by a unique-key alias such as a username. A non-normative example request URI would be of the form:

PATCH http://example.com/<path-prefix>/v2/Users/<username>

If the server is able to resolve the alias to the permanent resource URI, the service provider MAY redirect the SCIM client to the permanent URI using HTTP 308. 

The service provider SHALL return HTTP 404 (not found) if the alias cannot be translated into a permanent URI.

Phil

@independentid
www.independentid.com
[email-masked]

---

From: Patrick Radtke <[email-masked]>
Date: Wed, 11 Dec 2013 12:56:33 -0800

Thanks for the writeup Phil.

I know your example "Unique-Key Reference" is non-normative, but I 
suspect implementers will base their URL syntax on the example and it 
will become a defacto standard.

 From a client/service consumer perspective, that URL pattern is bad for 
our organization. We have a user with the username "me". If we integrate 
with a service provider that supports both 5.2.1.1 and 5.2.1.2 (with the 
example url syntax), one of those two features will break once we add 
our user "me".

 From an implementor's perspective, I would prefer to know the attribute 
key for the unique reference so I don't have to do multiple lookups 
internally. For example, if someone queried "Users/bob234ad", then 
internally I would lookup the resource by id, if not found then lookup 
by username, if not found then lookup by external_id). While the spec, 
as written, allows me to use whatever URL pattern I see fit, I would be 
worried that client implementations would only support the example 
syntax given.

I would highly prefer an example URL that contains they 'key' attribute 
name in the url to avoid usage of a URL pattern that will be problematic 
for us.

   PATCH http://example.com/<path-prefix>/v2/Users/userName=<username>

-Patrick

On 12/11/13, 12:10 PM, Phil Hunt wrote:
> The following is a new section to be added to draft-ietf-scim-api.  This
> provides clarification as to what HTTP redirects clients must support.
>
> Section 5.2.1 (aliases) may be somewhat more controversial and thus has
> been written as an optional feature. I do agree strongly with the
> concern not to have multiple URIs for a resource. My thought here is
> that by using a redirect as a compromise, the redirect encourages the
> client to use the proper URL and thus might be seen as self-healing over
> time.  Yet at the same time, it does solve some scenarios where the
> client may be aware of a user-id but is not able to conveniently obtain
> the user's URI in advance.
>
> In other cases, temporary and permanent redirection seem like a natural
> requirement for any REST service over time.  Though I must confess in
> many cases the issue is reduced since service providers would tend to
> coordinate with clients when data set URIs are changed as part of a
> service migration.
>
> Proposed text:
>
> 5.0 Redirection Support
>
> Section 10.3 of the HTTP specification [RFC2616] defines several
> redirect response codes normally used to redirect user-agents (browsers)
> in response to HTTP requests. As SCIM is not intended for user-agents,
> this section clarifies the use of HTTP redirection codes.
>
> In order to preserve the integrity of SCIM operations, HTTP redirection
> codes 301-306 SHOULD NOT be used unless the service provider is aware
> the client is in fact a user-agent.  Redirection code 301-306 are
> require the clients to convert requests to HTTP GET or HEAD and are not
> normally suitable.
>
>     "The action required MAY be carried out by the user agent without
>     interaction with the user if and only if the method used in the
>     second request is GET or HEAD."
>
>
> Because SCIM is a RESTful API and is normally performed without user
> interaction, HTTP redirection SHOULD preserve the integrity of requests
> after a redirect. This section clarifies the use of HTTP redirect code
> 307, as defined in [RFC2616] and HTTP Redirect code 308 as defined
> in [draft-reschke-http-status-308]. In both cases, the processing rules
> for Redirect 307 and 308 are to be applied.
>
> Upon receiving a redirect, SCIM clients SHOULD preserve the HTTP action
> and SCIM operation by applying it to the new resource location specified
> in the redirect.
>
> SCIM servers MAY issue two types of HTTP redirects:  HTTP redirect 307
> for temporary redirection and HTTP redirect 308 for permanent redirection.
>
>     A service provider MAY temporarily redirect clients using HTTP 307
>     as specified in RFC2616. The original HTTP action MUST be preserved.
>     Clients MUST ensure that the new location keeps the operation intent
>     intact.
>
>     The SCIM client MUST use the original permanent URI when referencing
>     the affected SCIM resource in any other SCIM operations or SCIM
>     resource (e.g. such as a Group).
>
>     If there is no user-agent involved in the transaction, the SCIM
>     client MAY proceed by automatically processing the redirect.
>
>
>     In the event that a SCIM resource has been relocated or reassigned,
>     a service provider MAY issue an HTTP 308 redirect as specified
>     in [draft-reschke-http-status-308]. This redirect informs the SCIM
>     client of the new permanent URI for the object.
>
>     SCIM clients MUST ensure that the new address keeps the operation
>     intent intact and the same HTTP verb is used.
>
>     The SCIM client MUST use the new permanent URI when referencing the
>     affected SCIM resource in any other SCIM operations or SCIM resource
>     (e.g. such as a Group).
>
>     If there is no user-agent involved in the transaction, the SCIM
>     client MAY proceed by automatically processing the redirect.
>
>
> 5.2.1 Alias Redirection
>
>     A SCIM service provider MAY support aliases by using HTTP 308
>     redirection [draft-reschke-http-status-308].
>
>     Servers that DO NOT support aliases SHOULD respond with HTTP 404
>     (not found) if an aliased request is received or is not otherwise
>     resolvable.
>
>     An aliases SHALL use HTTP 308 permanent redirects and follow the
>     same processing rules in section [section 5.2].
>
> 5.2.1.1 Self-Referencing
>
>     In situations where the client wishes to refer to the current
>     security context of the user, the server may translate a URI ending
>     in "/me" to mean the resource represented by current authenticated
>     subject.
>
>     If "/me" does not resolve to a resource within the service endpoint
>     requested, the service provider MUST respond with HTTP 404 (not
>     found). If subject is resolved to a local resource, the service
>     provider MAY use HTTP 308 to redirect the SCIM client to the
>     permanent URI of the authenticated subject.
>
>
>     A client may wish to reference a resource by a unique-key alias such
>     as a username. A non-normative example request URI would be of the form:
>
>     If the server is able to resolve the alias to the permanent resource
>     URI, the service provider MAY redirect the SCIM client to the
>     permanent URI using HTTP 308.
>
>     The service provider SHALL return HTTP 404 (not found) if the alias
>     cannot be translated into a permanent URI.
>
>
> Phil
>
> @independentid
> www.independentid.com <http://www.independentid.com>
> [email-masked] <mailto:[email-masked]>
>
>
>
> _______________________________________________
> scim mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/scim
>

---

From: Phil Hunt <[email-masked]>
Date: Wed, 11 Dec 2013 13:08:12 -0800

see below
Phil

@independentid
www.independentid.com
[email-masked]

On 2013-12-11, at 12:56 PM, Patrick Radtke <[email-masked]> wrote:

> I know your example "Unique-Key Reference" is non-normative, but I suspect implementers will base their URL syntax on the example and it will become a defacto standard.
> 
> From a client/service consumer perspective, that URL pattern is bad for our organization. We have a user with the username "me". If we integrate with a service provider that supports both 5.2.1.1 and 5.2.1.2 (with the example url syntax), one of those two features will break once we add our user "me".
That is unfortunate. Yet I suspect there is significant weight behind "me" thanks to Facebook. If we changed to "self" is someone else going to complain about that?  we have to choose something.  "self" then?
> 
> From an implementor's perspective, I would prefer to know the attribute key for the unique reference so I don't have to do multiple lookups internally. For example, if someone queried "Users/bob234ad", then internally I would lookup the resource by id, if not found then lookup by username, if not found then lookup by external_id). While the spec, as written, allows me to use whatever URL pattern I see fit, I would be worried that client implementations would only support the example syntax given.

I think this is something entirely for the SP to decide through some external negotiation. The format proposed was based on what MS is doing with OData and Google is doing with Google Directory.  
> 
> I would highly prefer an example URL that contains they 'key' attribute name in the url to avoid usage of a URL pattern that will be problematic for us.
> 

The only concern here is that then clients will want to go to full filters with multiple terms.  E.g.

PATCH http://example.com/<path-prefix>/v2/Users?filter=userName eq <username>

Aside from causing some invalid operation scenarios, I think we don't want to encourage this pattern too much. We want to keep it as limited as possible.

The real anti-pattern here is the desire by clients to "calculate" a URL rather than query for it in the first place. My gut feel is that in most cases this can be decided based on the context of the relationship between client and service provider.

The real debate will likely be that those who want aliases will not want redirects. They'll want that aliased URL to be handled as if it were the URL -- leading us to multi-URLs per object.

Curious to see what other people think.  I'd love to kill it, but I think even my employer won't agree.

---

From: Phil Hunt <[email-masked]>
Date: Wed, 11 Dec 2013 13:14:45 -0800

Patrick,

It occurs to me that if "/me" is performed at the root level then it won't conflict with /Users/me.  Would that work?  Using a root level match might actually work better for cases where the client security context is not a user, but rather a client "service" that has been issued its own credential.

Note: for cases like OAuth delegated tokens I would expect "me" or self to resolve to the resource owner.

Phil

@independentid
www.independentid.com
[email-masked]

---

From: Patrick Radtke <[email-masked]>
Date: Wed, 11 Dec 2013 13:26:33 -0800

> Note: for cases like OAuth delegated tokens I would expect "me" or self to resolve to the resource owner.

I like that idea.

Looking around at other alternatives, OpenSocial uses @me and LinkedIn 
uses ~.
If we need to go under the /Users/ then either of those would work for 
us. They contain special characters which makes them less likely to 
conflict with a userName.

thanks Phil,

Patrick