More docs
This commit is contained in:
Pedro Igor
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/enforcer/overview.adoc[Policy Enforcers]
|
||||
.. 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]
|
||||
|
|
@ -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.
|
||||
|
||||
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
|
||||
<filter>
|
||||
<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-mapping>
|
||||
|
|
@ -27,9 +27,19 @@ curl -X GET \
|
|||
"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
|
||||
|
||||
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
|
||||
{
|
||||
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