More docs
This commit is contained in:
parent
7ece7ddaec
commit
e480943bc4
3 changed files with 193 additions and 5 deletions
|
@ -44,5 +44,6 @@
|
||||||
.. link:topics/service/client-api.adoc[Authorization Client Java API]
|
.. link:topics/service/client-api.adoc[Authorization Client Java API]
|
||||||
. link:topics/enforcer/overview.adoc[Policy Enforcers]
|
. link:topics/enforcer/overview.adoc[Policy Enforcers]
|
||||||
.. link:topics/enforcer/keycloak-enforcement-filter.adoc[Keycloak Servlet Policy Enforcer]
|
.. link:topics/enforcer/keycloak-enforcement-filter.adoc[Keycloak Servlet Policy Enforcer]
|
||||||
.. link:topics/enforcer/bearer-enforcement-filter.adoc[Bearer Token Servlet Policy Enforcer]
|
.. link:topics/enforcer/entitlement-bearer-enforcement-filter.adoc[Entitlement Bearer Token Servlet Policy Enforcer]
|
||||||
|
.. link:topics/enforcer/uma-bearer-enforcement-filter.adoc[UMA Bearer Token Servlet Policy Enforcer]
|
||||||
. link:topics/example/overview.adoc[Examples]
|
. link:topics/example/overview.adoc[Examples]
|
|
@ -1,6 +1,6 @@
|
||||||
== Bearer Token Enforcement Filter
|
== Entitlement Bearer Token Enforcement Filter
|
||||||
|
|
||||||
The *org.keycloak.authorization.policy.enforcer.servlet.BearerTokenEnforcementFilter* can be used to protect servlet applications providing
|
The *org.keycloak.authorization.policy.enforcer.servlet.EntitlementBearerTokenEnforcementFilter* can be used to protect servlet applications providing
|
||||||
RESTful services. For instance, applications using JAX-RS.
|
RESTful services. For instance, applications using JAX-RS.
|
||||||
|
|
||||||
This filter does not require that your application is configured with any {{book.project.name}} OIDC Adapter.
|
This filter does not require that your application is configured with any {{book.project.name}} OIDC Adapter.
|
||||||
|
@ -10,7 +10,7 @@ To configure it, change your web application descriptor (WEB-INF/web.xml) as fol
|
||||||
```xml
|
```xml
|
||||||
<filter>
|
<filter>
|
||||||
<filter-name>Keycloak Authorization Enforcer</filter-name>
|
<filter-name>Keycloak Authorization Enforcer</filter-name>
|
||||||
<filter-class>org.keycloak.authorization.policy.enforcer.servlet.BearerTokenEnforcementFilter</filter-class>
|
<filter-class>org.keycloak.authorization.policy.enforcer.servlet.EntitlementBearerTokenEnforcementFilter</filter-class>
|
||||||
</filter>
|
</filter>
|
||||||
|
|
||||||
<filter-mapping>
|
<filter-mapping>
|
||||||
|
@ -27,9 +27,19 @@ curl -X GET \
|
||||||
"http://my-app/api/resource"
|
"http://my-app/api/resource"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
If the client application (or requesting party) trying to access the protected resource does not provide a RPT within the request, the filter is going to respond to the client with a 401 HTTP status code and
|
||||||
|
a *WWW-Authenticate* header as follows:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
HTTP/1.1 401 Unauthorized
|
||||||
|
WWW-Authenticate: KC_ETT realm="${resource_server_id}",as_uri="http://${kc_server_host}:${kc_server_port}/auth/realms/${realm_name}/authz/entitlement"
|
||||||
|
```
|
||||||
|
|
||||||
|
Where *KC_ETT* indicates that the resource server requires a RPT with entitlements and *as_uri* holds the URI that clients can use to obtain a RPT based on an OAuth2 Access Token previously issued by a {{book.project.name}} server during user authentication.
|
||||||
|
|
||||||
=== Configuration
|
=== Configuration
|
||||||
|
|
||||||
The BearerTokenEnforcementFilter can be configured by a simple JSON file. The file can be as simple as:
|
The _EntitlementBearerTokenEnforcementFilter_ can be configured by a simple JSON file. The file can be as simple as:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
177
topics/enforcer/uma-bearer-enforcement-filter.adoc
Executable file
177
topics/enforcer/uma-bearer-enforcement-filter.adoc
Executable file
|
@ -0,0 +1,177 @@
|
||||||
|
== UMA Bearer Token Enforcement Filter
|
||||||
|
|
||||||
|
The *org.keycloak.authorization.policy.enforcer.servlet.UmaBearerTokenEnforcementFilter* can be used to protect servlet applications providing
|
||||||
|
RESTful services. For instance, applications using JAX-RS.
|
||||||
|
|
||||||
|
This filter does not require that your application is configured with any {{book.project.name}} OIDC Adapter.
|
||||||
|
|
||||||
|
To configure it, change your web application descriptor (WEB-INF/web.xml) as follows:
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<filter>
|
||||||
|
<filter-name>Keycloak Authorization Enforcer</filter-name>
|
||||||
|
<filter-class>org.keycloak.authorization.policy.enforcer.servlet.UmaBearerTokenEnforcementFilter</filter-class>
|
||||||
|
</filter>
|
||||||
|
|
||||||
|
<filter-mapping>
|
||||||
|
<filter-name>Keycloak Authorization Enforcer</filter-name>
|
||||||
|
<url-pattern>/*</url-pattern>
|
||||||
|
</filter-mapping>
|
||||||
|
```
|
||||||
|
|
||||||
|
When using this filter, client applications need to send a RPT as a *Bearer* token using the *Authorization* header in order to gain access to a protected resource.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X GET \
|
||||||
|
-H "Authorization: Bearer %{RPT}" \
|
||||||
|
"http://my-app/api/resource"
|
||||||
|
```
|
||||||
|
|
||||||
|
If the client application (or requesting party) trying to access the protected resource does not provide a RPT within the request, the filter is going to respond to the client with a 401 HTTP status code and
|
||||||
|
a *WWW-Authenticate* header as follows:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
HTTP/1.1 401 Unauthorized
|
||||||
|
WWW-Authenticate: UMA realm="${resource_server_id}",as_uri="http://${kc_server_host}:${kc_server_port}/auth/realms/${realm_name}/authz/authorize",ticket="${PERMISSION_TICKET}"
|
||||||
|
```
|
||||||
|
|
||||||
|
From that response, users can use the permission ticket returned by the resource server and use it to obtain a RPT using the UMA protocol, as described by link:../service/authorization/authorization-api.html[Authorization API].
|
||||||
|
|
||||||
|
Where *UMA* indicates that this resource server requires a RPT and *as_uri* holds the URI that clients can use to obtain the RPT based on UMA protocol.
|
||||||
|
|
||||||
|
=== Configuration
|
||||||
|
|
||||||
|
The _EntitlementBearerTokenEnforcementFilter_ can be configured by a simple JSON file. The file can be as simple as:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"client": {
|
||||||
|
"configurationUrl": "http://localhost:8080/auth/realms/{realm_name}/authz/uma_configuration",
|
||||||
|
"clientId": "{client_id}",
|
||||||
|
"clientSecret": "{client_secret}"
|
||||||
|
},
|
||||||
|
"enforcer": {
|
||||||
|
"user-managed-access": {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Or a little more verbose if you want to manually define the resources being protected:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"client": {
|
||||||
|
"configurationUrl": "http://localhost:8080/auth/realms/{realm_name}/authz/uma_configuration",
|
||||||
|
"clientId": "{client_id}",
|
||||||
|
"clientSecret": "{client_secret}"
|
||||||
|
},
|
||||||
|
"enforcer": {
|
||||||
|
"user-managed-access": {},
|
||||||
|
"paths": [
|
||||||
|
{
|
||||||
|
"path" : "/someUri/*",
|
||||||
|
"methods" : [
|
||||||
|
{
|
||||||
|
"method": "GET",
|
||||||
|
"scopes" : ["urn:app.com:scopes:view"]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"method": "POST",
|
||||||
|
"scopes" : ["urn:app.com:scopes:create"]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name" : "Some Resource",
|
||||||
|
"path" : "/usingPattern/{id}",
|
||||||
|
"methods" : [
|
||||||
|
{
|
||||||
|
"method": "DELETE",
|
||||||
|
"scopes" : ["urn:app.com:scopes:delete"]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path" : "/exactMatch"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name" : "Admin Resources",
|
||||||
|
"path" : "/usingWildCards/*"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The file with the enforcer configuration must be under your application's classpath as *keycloak-authz.json".
|
||||||
|
|
||||||
|
Here is a description of each configuration option:
|
||||||
|
|
||||||
|
* *client*
|
||||||
|
+
|
||||||
|
Specify the information about the resource server being protected
|
||||||
|
+
|
||||||
|
** *configurationUrl*
|
||||||
|
+
|
||||||
|
A URL pointing to a configuration endpoint. This is important for the automatic discovery of the services invoked during the authorization process.
|
||||||
|
+
|
||||||
|
** *clientId*
|
||||||
|
+
|
||||||
|
The id of the client acting as a resource server.
|
||||||
|
+
|
||||||
|
** *clientSecret*
|
||||||
|
+
|
||||||
|
The client secret.
|
||||||
|
+
|
||||||
|
* *enforcer*
|
||||||
|
+
|
||||||
|
Specify the configuration options to define how policies are actually enforced and optionally the paths you want to protect. If empty, the policy enforcer will query the server
|
||||||
|
for all resources associated with the resource server being protected. In this case, you need to make sure the resources are properly configured with a *uri* property that matches the paths
|
||||||
|
you want to protect.
|
||||||
|
+
|
||||||
|
** *paths*
|
||||||
|
+
|
||||||
|
Specify the paths to protect.
|
||||||
|
+
|
||||||
|
*** *name*
|
||||||
|
+
|
||||||
|
The name of a resource in the server that must be associated with a given path. If provided, the policy enforcer will ignore the resource's *uri* property and use the path you provided.
|
||||||
|
*** *path*
|
||||||
|
+
|
||||||
|
A URI relative to the application's context path. If this option is provided, the policy enforcer will query the server for a resource with a *uri* with the same value.
|
||||||
|
Right now, we support some very basic logic for path matching. Examples of valid paths are:
|
||||||
|
+
|
||||||
|
**** Wildcards: `/*`
|
||||||
|
**** Suffix: `/*.html`
|
||||||
|
**** Sub-paths: `/path/*`
|
||||||
|
**** Path parameters: /resource/{id}
|
||||||
|
**** Exact match: /resource
|
||||||
|
+
|
||||||
|
*** *methods*
|
||||||
|
The HTTP methods to protect and how they are associated with the scopes for a given resource in the server.
|
||||||
|
+
|
||||||
|
**** *method*
|
||||||
|
+
|
||||||
|
The name of the HTTP method.
|
||||||
|
+
|
||||||
|
**** *scopes*
|
||||||
|
+
|
||||||
|
An array of strings with the scopes associated with the method.
|
||||||
|
|
||||||
|
=== Container Specific Configuration
|
||||||
|
|
||||||
|
==== WildFly 10.0.0.Final
|
||||||
|
|
||||||
|
In order to make the filter available to your application at runtime, you must create a *META-INF/jboss-deployment-structure.xml* at the application root directory.
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<jboss-deployment-structure>
|
||||||
|
<deployment>
|
||||||
|
<dependencies>
|
||||||
|
<module name="org.keycloak.keycloak-authz-servlet-enforcer" services="import"/>
|
||||||
|
<module name="org.jboss.resteasy.resteasy-jackson2-provider" services="import"/>
|
||||||
|
</dependencies>
|
||||||
|
<exclusions>
|
||||||
|
<module name="org.jboss.resteasy.resteasy-jackson-provider"/>
|
||||||
|
</exclusions>
|
||||||
|
</deployment>
|
||||||
|
</jboss-deployment-structure>
|
Loading…
Reference in a new issue