From dfcf35f5894296c7612eef8baa32cd3153d078aa Mon Sep 17 00:00:00 2001 From: mposolda Date: Wed, 3 Oct 2018 15:02:32 +0200 Subject: [PATCH] KEYCLOAK-6884 KEYCLOAK-3454 KEYCLOAK-8298 Documentation for default 'roles' and 'web-origins' client scopes --- .../topics/clients/client-scopes.adoc | 10 ++++++++- .../topics/clients/oidc/audience.adoc | 21 +++++++++++++++++++ upgrading/topics/keycloak/changes.adoc | 20 ++++++++++++++++++ 3 files changed, 50 insertions(+), 1 deletion(-) diff --git a/server_admin/topics/clients/client-scopes.adoc b/server_admin/topics/clients/client-scopes.adoc index 6262307c13..6a4683993d 100644 --- a/server_admin/topics/clients/client-scopes.adoc +++ b/server_admin/topics/clients/client-scopes.adoc @@ -28,7 +28,8 @@ Once you have created new realm, you can see that there is a list of pre-defined * For the SAML protocol, there is one builtin client scope, `roles_list`, which contains one protocol mapper for showing the roles list in the SAML assertion. -* For the OpenID Connect protocol, there are client scopes `profile`, `email`, `address`, `phone` and `offline_access` . +* For the OpenID Connect protocol, there are client scopes `profile`, `email`, `address`, `phone`, `offline_access`, `roles` and +`web-origins`. The client scope, `offline_access`, is useful when client wants to obtain offline tokens. Learn about offline tokens in the <<_offline-access, Offline Access section>> or in the https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[OpenID Connect specification], @@ -51,6 +52,13 @@ the user has a defined phone number. Builtin client scopes contain exactly the protocol mappers as defined per the specification, however you are free to edit client scopes and create/update/remove any protocol mappers (or role scope mappings). +The client scope `roles` is not defined in the OpenID Connect specification and it is also not added automatically to the `scope` +claim in the access token. This client scope has some mappers, which are used to add roles of the user to the access token and +possibly add some audiences for the clients with at least one client role as described in the <<_audience_resolve, Audience section>>. + +The client scope `web-origins` is also not defined in the OpenID Connect specification and not added to the `scope` claim. This is used +to add allowed web origins to the access token `allowed-origins` claim. + ==== Consent related settings Client scope contains options related to the consent screen. Those options are useful only if the linked client is configured to diff --git a/server_admin/topics/clients/oidc/audience.adoc b/server_admin/topics/clients/oidc/audience.adoc index d087dd8b02..3266fed7e6 100644 --- a/server_admin/topics/clients/oidc/audience.adoc +++ b/server_admin/topics/clients/oidc/audience.adoc @@ -108,4 +108,25 @@ image:{project_images}/audience_mapper.png[] adapter, or the link:{adapterguide_link}#_javascript_adapter[javascript adapter section], if your application uses the javascript adapter. +[[_audience_resolve]] +===== Automatically add audience + +There is another way that the audience can be added to the token. In the default client scope _roles_, there is an _Audience Resolve_ +protocol mapper defined. This protocol mapper will check all the clients for which current token has at least one client role +available. Then the client ID of each of those clients will be added as an audience automatically. This is especially useful if +your service (usually bearer-only) clients rely on client roles. In the example in previous section, if all of those are true: + +* The `good-service` client has any client role defined on itself + +* Target user has this client role assigned + +* Client `my-app` has the role scope mappings for this role + +then the `good-service` will be automatically added as an audience. In this case, you do not need to set up the audience client +scope as described in the previous section. + +NOTE: If you are unsure what the correct audience and roles in the token will be, it is always a good idea to +<<_client_scopes_evaluate, Evaluate Client Scopes>> in the admin console and do some testing around it. + + diff --git a/upgrading/topics/keycloak/changes.adoc b/upgrading/topics/keycloak/changes.adoc index 0b45b5bf2f..624cdcd01a 100644 --- a/upgrading/topics/keycloak/changes.adoc +++ b/upgrading/topics/keycloak/changes.adoc @@ -1,5 +1,25 @@ == Migration Changes +=== Migrating to 4.6.0 + +==== New default client scopes + +We have added new realm default client scopes `roles` and `web-origins`. These client scopes contain protocol +mappers to add the roles of the user and allowed web origins to the token. During migration, these client scopes should be +automatically added to all the OpenID Connect clients as default client scopes. Hence no setup should be required after database +migration is finished. + +===== Protocol mapper SPI addition +Related to this, there is a small addition in the (unsupported) Protocol Mappers SPI. You can be affected only if you +implemented a custom ProtocolMapper. There is a new `getPriority()`` method on the ProtocolMapper interface. The method has the +default implementation set to return 0. If your protocol mapper implementation relies on the roles in the access token `realmAccess` +or `resourceAccess` properties, you may need to increase the priority of your mapper. + +===== Audience resolving + +Audiences of all the clients, for which authenticated user has at least one client role in the token, are automatically added +to the `aud` claim in the access token now. + === Migrating to 4.4.0 ==== Upgrade to Wildfly 13