[keycloak-dev] Scope parameter support

[Marek Posolda]

It seems that for OIDC certification, we will need more proper support 
for "scope" parameter. There are few tests from OIDC conformance 
testsuite, which end with WARNING because of issues with "scope" parameter.


SUMMARY OF SPECS REQUIREMENTS
-----------------------------

- In OIDC specification, the "scope" parameter is actually REQUIRED. And 
you must add the scope value "openid" to all authorization requests. 
Hence if you don't use "scope=openid", the request is pure OAuth2 
request, but it's not OIDC request.

In https://issues.jboss.org/browse/KEYCLOAK-3147 we discuss the 
possibility that we should change our adapters and add "scope=openid" to 
all requests, and also the possibility to remove IDToken if it's not 
OIDC request (and maybe other things). However it may be potential issue 
with backward compatibility with older adapters (which don't add 
"scope=openid" at all).


- OIDC also prescribes the "scope=offline_access", which you use if you 
want offline token. We actually support this as we have realm role 
"offline_access", with scopeParamRequired=true . So this role is applied 
just if it's included in scope parameter. This is our only support of 
scope param actually. ATM we reference the realm roles by name (role 
name must match the value of scope parameter) and clientRoles by 
"clientId/roleName" . So it's not very flexible and won't work well in 
the future with role namespaces.


- OIDC defines four other scope values, which we don't support, with the 
meaning like this:

profile
     OPTIONAL. This scope value requests access to the End-User's 
default profile Claims, which are: "name", "family_name", "given_name", 
"middle_name", "nickname", "preferred_username", "profile", "picture", 
"website", "gender", "birthdate", "zoneinfo", "locale", and "updated_at".

email
     OPTIONAL. This scope value requests access to the "email" and 
"email_verified" Claims.

address
     OPTIONAL. This scope value requests access to the "address" Claim.

phone
     OPTIONAL. This scope value requests access to the "phone_number" 
and "phone_number_verified" Claims.


- Not directly related to scopes, however OIDC also has one parameter 
"claims" described in section 
http://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter . 
This allows to define some additional claims, which should be included 
in IDToken or UserInfo endpoint in addition to claims specified by 
"scope" parameter.



HOW TO IMPLEMENT?
-----------------

My current thinking is, that we will have 2 kinds of protocolMappers and 
roles.

1) "Always applied" - Those roles/protocolMappers are always applied to 
token even if they are not specified by scope parameter.

2) "Applied on demand" - Those roles/protocolMappers are applied just if 
they are specifically requested by scope parameter

For roles, we already have that with "scope param required" flag defined 
per roleModel. However for protocolMappers we don't have it yet.

IMO We will also need some more flexible way to specify how the value of 
scope parameter will be mapped to roles and protocolMappers. For example 
if I use "scope=foo", it can mean that I want realm role "foo1", client 
role "client1/foo2" and protocolMapper for "firstName" and "lastName" etc.

I can see 2 possibilities:

a) Configure allowed scope param separately per each role / protocolMapper

If some role has "Scope param required" checked, you will have 
possibility to configure list of available values of scope parameter, 
which this role will be applied to. This will be configured per-each 
role separately.

Example: I have realm role "foo" . I check "scope param required" to 
true. Then I will define "scope param values" :  "bar" and "baz". It 
means that if someone uses parameter "scope=bar" or
scope=baz", then role "foo" will be applied to token. Otherwise it won't 
be applied.

Similarly it will be for protocolMappers. We will add switch "Scope 
param required" to protocolMappers and we will use list of available 
values of scope parameter, which is configured per each protocolMapper 
separately.


b) Configure scope parameter in separate place

We will have another tab "Scope parameter config" (or maybe rather 
another sub-tab under existing "Scope" tab). Here you will define the 
allowed values of scope parameter. For each allowed value, you will 
define protocolMappers and roles to apply. Hence for example for 
"profile" scope parameter, you will define all protocolMappers for 
corresponding claims ( name, family_name, ...) here.

We will still need "scope param required" switch for protocolMappers in 
case (b).

My current thinking is to go with (a). So when you go to some role (or 
protocolMapper) in admin console you will see if you need scope 
parameter and what are available values of scope parameter to request it.

WDYT? Another ideas?


Marek