111 lines
7.8 KiB
Text
111 lines
7.8 KiB
Text
//[id="con-client-scopes_{context}"]//
|
|
|
|
[[_client_scopes]]
|
|
= Client scopes
|
|
|
|
[role="_abstract"]
|
|
Use {project_name} to define a shared client configuration in an entity called a _client scope_. A _client scope_ configures <<_protocol-mappers, protocol mappers>> and <<_role_scope_mappings, role scope mappings>> for multiple clients.
|
|
|
|
Client scopes also support the OAuth 2 *scope* parameter. Client applications use this parameter to request claims or roles in the access token, depending on the requirement of the application.
|
|
|
|
include::proc-creating-client-scopes.adoc[]
|
|
|
|
|
|
== Protocol
|
|
When you create a client scope, choose the *Protocol*. Clients linked in the same scope must have the same protocol.
|
|
|
|
Each realm has a set of pre-defined built-in client scopes in the menu.
|
|
|
|
* SAML protocol: The *role_list*. This scope contains one protocol mapper for the roles list in the SAML assertion.
|
|
* OpenID Connect protocol: Several client scopes are available:
|
|
** *roles*
|
|
+
|
|
This scope is not defined in the OpenID Connect specification and is not added automatically to the *scope* claim in the access token. This scope has mappers, which are used to add the roles of the user to the access token and
|
|
add audiences for clients that have at least one client role. These mappers are described in more detail in the <<_audience_resolve, Audience section>>.
|
|
+
|
|
** *web-origins*
|
|
+
|
|
This scope is also not defined in the OpenID Connect specification and not added to the *scope* claiming the access token. This scope is used to add allowed web origins to the access token *allowed-origins* claim.
|
|
+
|
|
** *microprofile-jwt*
|
|
+
|
|
This scope handles claims defined in the https://github.com/eclipse/microprofile/wiki/JWT_Auth[MicroProfile/JWT Auth Specification]. This scope defines a user property mapper for the *upn* claim and a realm role mapper for the *groups* claim. These mappers can be changed so different properties can be used to create the MicroProfile/JWT specific claims.
|
|
+
|
|
** *offline_access*
|
|
+
|
|
This scope is used in cases when clients need to obtain offline tokens. More details on offline tokens is available in the <<_offline-access, Offline Access section>> and in the https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess[OpenID Connect specification].
|
|
+
|
|
** *profile*
|
|
** *email*
|
|
** *address*
|
|
** *phone*
|
|
|
|
The client scopes *profile*, *email*, *address* and *phone* are defined in the https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims[OpenID Connect specification]. These scopes do not have any role scope mappings defined but they do have protocol mappers defined. These mappers correspond to the claims defined in the OpenID Connect specification.
|
|
|
|
For example, when you open the *phone* client scope and open the *Mappers* tab, you will see the protocol mappers which correspond to the claims defined in the specification for the scope *phone*.
|
|
|
|
.Client scope mappers
|
|
image:images/client-scopes-phone.png[]
|
|
|
|
When the *phone* client scope is linked to a client, the client automatically inherits all the protocol mappers defined in the *phone* client scope. Access tokens issued for this client contain the phone number information about the user, assuming that the user has a defined phone number.
|
|
|
|
Built-in client scopes contain the protocol mappers as defined in the specification. You are free to edit client scopes and create, update, or remove any protocol mappers or role scope mappings.
|
|
|
|
== Consent related settings
|
|
Client scopes contain options related to the consent screen. Those options are useful if the linked client if *Consent Required* is enabled on the client.
|
|
|
|
Display On Consent Screen::
|
|
If *Display On Consent Screen* is enabled, and the scope is added to a client that requires consent, the text specified in *Consent Screen Text* will be displayed on the consent screen. This text is shown when the user is authenticated and before the user is redirected from {project_name} to the client. If *Display On Consent Screen* is disabled, this client scope will not be displayed on the consent screen.
|
|
|
|
Consent Screen Text::
|
|
The text displayed on the consent screen when this client scope is added to a client when consent required defaults to the name of client scope. The value for this text can be customised by specifying a substitution variable with *${var-name}* strings. The customised value is configured within the property files in your theme. See the link:{developerguide_link}[{developerguide_name}] for more information on customisation.
|
|
|
|
[[_client_scopes_linking]]
|
|
== Link client scope with the client
|
|
Linking between a client scope and a client is configured in the *Client Scopes* tab of the client. Two ways of linking between client scope and client are available.
|
|
|
|
Default Client Scopes::
|
|
This setting is applicable to the OpenID Connect and SAML clients. Default client scopes are applied when issuing OpenID Connect tokens or SAML assertions for a client. The client will inherit Protocol Mappers and Role Scope Mappings that are defined on the client scope. For the OpenID Connect Protocol, the Mappers and Role Scope Mappings are always applied, regardless of the value used for the scope parameter in the OpenID Connect authorization request.
|
|
|
|
Optional Client Scopes::
|
|
This setting is applicable only for OpenID Connect clients. Optional client scopes are applied when issuing tokens for this client but only when requested by the *scope* parameter in the OpenID Connect authorization request.
|
|
|
|
=== Example
|
|
For this example, assume the client has *profile* and *email* linked as default client scopes, and *phone* and *address* linked as optional client scopes. The client uses the value of the scope parameter when sending a request to the OpenID Connect authorization endpoint.
|
|
|
|
[source,bash,subs=+attributes]
|
|
----
|
|
scope=openid phone
|
|
----
|
|
|
|
The scope parameter contains the string, with the scope values divided by spaces. The value *openid* is the meta-value used for all OpenID Connect requests. The token will contain mappers and role scope mappings from the default client scopes *profile* and *email* as well as *phone*, an optional client scope requested by the scope parameter.
|
|
|
|
[[_client_scopes_evaluate]]
|
|
== Evaluating Client Scopes
|
|
include::proc-evaluating-client-scopes.adoc[]
|
|
|
|
== Client scopes permissions
|
|
|
|
When issuing tokens to a user, the client scope applies only if the user is permitted to use it.
|
|
|
|
When a client scope does not have any role scope mappings defined, each user is permitted to use this client scope. However, when a client scope has role scope mappings defined, the user must be a member of at least one of the roles. There must be an intersection between the user roles and the roles of the client scope. Composite roles are factored into evaluating this intersection.
|
|
|
|
If a user is not permitted to use the client scope, no protocol mappers or role scope mappings will be used when generating tokens. The client scope will not appear in the _scope_ value in the token.
|
|
|
|
== Realm default client scopes
|
|
include::proc-updating-default-scopes.adoc[]
|
|
|
|
== Scopes explained
|
|
Client scope::
|
|
Client scopes are entities in {project_name} that are configured at the realm level and can be linked to clients. Client scopes are referenced by their name when a request is sent to the {project_name} authorization endpoint with a corresponding value of the *scope* parameter. See the <<_client_scopes_linking, client scopes linking>> section for more details.
|
|
|
|
Role scope mapping::
|
|
This is available under the *Scope* tab of a client or client scope. Use *Role scope mapping* to limit the roles that can be used in the access tokens. See the <<_role_scope_mappings, Role Scope Mappings section>> for more details.
|
|
|
|
ifeval::[{project_community}==true]
|
|
|
|
Authorization scopes::
|
|
The *Authorization Scope* covers the actions that can be performed in the application. See the link:{authorizationguide_link}[Authorization Services Guide] for more details.
|
|
|
|
endif::[]
|
|
|