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:
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".
OPTIONAL. This scope value requests access to the "email" and
OPTIONAL. This scope value requests access to the "address" Claim.
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
This allows to define some additional claims, which should be included
in IDToken or UserInfo endpoint in addition to claims specified by
HOW TO IMPLEMENT?
My current thinking is, that we will have 2 kinds of protocolMappers and
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
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
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
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
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?
I’m working at the moment in a Master Thesis project in TU Berlin where we are using Keycloak for Authentication and Authorisation purposes.
We are planning on extending Keycloak in order to provide users a way to register clients/applications by themselves into the platform, while having an admin overseeing the system.
This would mean that as a user, if I have the proper rights I should be able to create and manage my own clients. With, this it comes the idea of ownership, as this would mean that a client ownership could be transferred to someone else.
Also, the admin should be able to accept, revoke and delete the clients and requests to create clients in my Keycloak.
At the moment the only option would be giving the permission to create clients to the user, but that would allow to change ANY of the possible clients.
Then, I have two questions:
1. Would it make sense to integrate this to the Keycloak core?
2. If it doesn’t make sense to merge it in the core, is there any plugin system to extend Keycloak’s core? I’ve seen a discussion related to a plugin system in GitHub but there is no outcome yet. We would rather like to integrate it with Keycloak itself, otherwise the other option would be creating a client that uses Keycloak’s REST API to manage the clients remotely.
Thanks a lot in advance!
Erik Berdonces Bonelo
just wanted to let you know that there will be an OAuth Security Workshop
University of Trier (Germany) in July see:
I learned from one of the organizers that they will also discuss Keycloak as
an OpenID Connect Provider - just wanted to let you guys know.
I'm going to attend this workshop as well.
We have a Maven project setup on Eclipse that uses some keycloak features
and we generate a jar that contains our AuthenticationProvider classes etc.
We use docker for the deployment. We basically run a jboss/keycloak image
We have a shell script that has a bunch of commands to copy our project
jars from local to the keycloak image on docker container like:
docker cp /customauthenticator-1.0.0-SNAPSHOT.jar
docker restart keycloak
Running this shell script deploys everything on keycloak on docker.
And so far we are just putting logs throughout our code to debug issues.
We want to be able to setup a debugging environment on our eclipse. I am
not sure how to achieve this when we use keycloak. Because, here we
basically build our modules or authenticator jars etc and copy them to
keycloak directories. So, it's not a standalone project war file that we
are directly deploying to app server as such. So, then how do we put our
maven project (creating jars etc) in a debug mode in eclipse? Is it
I am adding some OIDC specs JIRAs with possibility how to fix them. I am
including those, which will be easy to fix and I can look into them
later today or tomorrow before PTO :
https://issues.jboss.org/browse/KEYCLOAK-3189 - Add 'typ' to JWT header
<https://issues.jboss.org/browse/KEYCLOAK-3190> - Add 'kid' to JWT header
https://issues.jboss.org/browse/KEYCLOAK-3217 - UserInfo endpoint not
accessible by POST request secured with Bearer header
https://issues.jboss.org/browse/KEYCLOAK-3147 - OpenID Connect auth
request redirect_uri behaviour not according to spec
<https://issues.jboss.org/browse/KEYCLOAK-3222> - WellKnown endpoint
doesn't return supported types of client authentication
https://issues.jboss.org/browse/KEYCLOAK-3219 - WellKnown endpoint
doesn't support claims_supported
All of those are quite straightforward and easy to fix IMO.
Besides that, there are those 2, which I first rather want to confirm
what exactly to do:
- https://issues.jboss.org/browse/KEYCLOAK-3221 Tokens not invalidated
if an attempt to reuse code is made
We have just single-use code (which is good), however OAuth2 specs
recommends to invalidate existing tokens if an attempt to reuse code is
done. And one OIDC test is in WARNING state because of it (it tries to
access UserInfo endpoint with the accessToken issued with the reused code).
I can see 2 possibilities to fix:
a) Invalidate just single clientSession where "code" attempt reuse was made
b) Logout whole userSession
It looks to me that (a) is sufficient solution. The potential issue with
(b) is, that if attacker can steal code, it gives him the possibility to
trigger global logout of user from all apps. WDYT?
- https://issues.jboss.org/browse/KEYCLOAK-3218 Support for "max_age" in
AuthorizationEndpoint and "auth_time" claim on IDToken
The possibility to implement is :
- Add new note AUTH_TIME to UserSessionModel. It will be time when
authentication of user was fully finished (including requiredActions).
Session note is used just so we don't need to change the model ;)
- If "max_age" parameter was requested, the "auth_time" will be added to
IDToken (or I will re-check specs if we should rather always add it to
- I am also thinking about adding hook to CookieAuthenticator, so that
if max_age parameter was used and userSession authTime is too "old", the
CookieAuthenticator will be ignored and user will need to
re-authenticate with other authenticators (username/password form etc).
Then authTime will be updated on userSession once authentication is
That will leave us with bigger things for OIDC Basic certification (
scope parameter support, possibly 'claims' param support and 'acr' support).
I am thinking whether to add configuration switch in admin console per
client, where you can define what is the adapter version the particular
client is using. In that case, some behaviour can be different/backwards
Example: For new clients, we will include IDToken just if they use
"scope=openid" . However for clients with adapter "1.9" or older, the
IDToken will be included even if "scope=openid" is not used.
I've started work on Client Registration CLI tool. As a first step, here is
a design document describing how I imagine the tool would be used.
I'll use this document as a spec / guide as I implement the client tool.
Within days I'll also send a link to initial ideas for Admin Client tool
which in principle should allow administrator to configure everything that
can otherwise be done through Admin Console.
Any feedback welcome.