Merge pull request #125 from pedroigor/master

Some updates and fixes
This commit is contained in:
Stian Thorgersen 2017-04-26 08:37:53 +02:00 committed by GitHub
commit 3a0b56a7b1
12 changed files with 86 additions and 21 deletions

View file

@ -51,6 +51,8 @@
... link:authorization_services/topics/policy/aggregated-policy.adoc[Aggregated Policy] ... link:authorization_services/topics/policy/aggregated-policy.adoc[Aggregated Policy]
... link:authorization_services/topics/policy/client-policy.adoc[Client Policy]
... link:authorization_services/topics/policy/logic.adoc[Positive and Negative Logic] ... link:authorization_services/topics/policy/logic.adoc[Positive and Negative Logic]
... link:authorization_services/topics/policy/evaluation-api.adoc[Policy Evaluation API] ... link:authorization_services/topics/policy/evaluation-api.adoc[Policy Evaluation API]

Binary file not shown.

After

Width:  |  Height:  |  Size: 76 KiB

View file

@ -57,4 +57,15 @@ Although both examples address the same requirements, they do so in different wa
Now, suppose your security requirements have changed and in addition to project managers, PMOs can also create new projects. Now, suppose your security requirements have changed and in addition to project managers, PMOs can also create new projects.
Security requirements change, but with {{book.project.name}} there is no need to change your application code to address the new requirements. Once your application is based on the resource and scope identifier, you need only change the configuration of the permissions or policies associated with a particular resource in the authorization server. In this case, the permissions and policies associated with the `Project Resource` and/or the scope `urn:project.com:project:create` would be changed. Security requirements change, but with {{book.project.name}} there is no need to change your application code to address the new requirements. Once your application is based on the resource and scope identifier, you need only change the configuration of the permissions or policies associated with a particular resource in the authorization server. In this case, the permissions and policies associated with the `Project Resource` and/or the scope `urn:project.com:project:create` would be changed.
==== Using the AuthorizationContext to obtain an Authorization Client Instance
The ```AuthorizationContext``` can also be used to obtain a reference to the <<fake/../../service/client-api.adoc#_service_client_api, Authorization Client API>> configured to your application:
```java
ClientAuthorizationContext clientContext = ClientAuthorizationContext.class.cast(authzContext);
AuthzClient authzClient = clientContext.getClient();
```
In some cases, resource servers protected by the policy enforcer need to access the APIs provided by the authorization server. With an ```AuthzClient``` instance in hands, resource servers can interact with the server in order to create resources or check for specific permissions programmatically.

View file

@ -111,6 +111,7 @@ Currently a very basic logic for path matching is supported. Examples of valid p
**** Sub-paths: `/path/*` **** Sub-paths: `/path/*`
**** Path parameters: /resource/{id} **** Path parameters: /resource/{id}
**** Exact match: /resource **** Exact match: /resource
**** Patterns: /{version}/resource, /api/{version}/resource, /api/{version}/resource/*
+ +
*** *methods* *** *methods*
The HTTP methods (for example, GET, POST, PATCH) to protect and how they are associated with the scopes for a given resource in the server. The HTTP methods (for example, GET, POST, PATCH) to protect and how they are associated with the scopes for a given resource in the server.

View file

@ -3,7 +3,7 @@
As mentioned previously, {{book.project.name}} allows you to build a policy of policies, a concept referred to as policy aggregation. You can use policy aggregation to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the policies that are evaluated during the processing of authorization requests. As mentioned previously, {{book.project.name}} allows you to build a policy of policies, a concept referred to as policy aggregation. You can use policy aggregation to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the policies that are evaluated during the processing of authorization requests.
To create a new aggregated policy, select *Aggregated* in the dropdown list located in the right upper corner of the permission listing. To create a new aggregated policy, select *Aggregated* in the dropdown list located in the right upper corner of the policy listing.
.Add an Aggregated Policy .Add an Aggregated Policy
image:../../{{book.images}}/policy/create-aggregated.png[alt="Add Aggregated Policy"] image:../../{{book.images}}/policy/create-aggregated.png[alt="Add Aggregated Policy"]

View file

@ -0,0 +1,28 @@
[[_policy_client]]
=== Client-Based Policy
You can use this type of policy to define conditions for your permissions where a set of one or more clients is permitted to access an object.
To create a new client-based policy, select *Client* in the dropdown list in the upper right corner of the policy listing.
.Add a Client-Based Policy
image:../../{{book.images}}/policy/create-client.png[alt="Add Client-Based Policy"]
==== Configuration
* *Name*
+
A human-readable and unique string identifying the policy. A best practice is to use names that are closely related to your business and security requirements, so you
can identify them more easily.
+
* *Description*
+
A string containing details about this policy.
+
* *Clients*
+
Specifies which clients are given access by this policy.
+
* *Logic*
+
The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.

View file

@ -4,7 +4,7 @@
With this type of policy you can define conditions for your permissions using http://www.drools.org[Drools], which is a rule evaluation environment. It is one of the _Rule-Based_ policy types With this type of policy you can define conditions for your permissions using http://www.drools.org[Drools], which is a rule evaluation environment. It is one of the _Rule-Based_ policy types
supported by {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>. supported by {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
To create a new Rule-based policy, in the dropdown list in the right upper corner of the permission listing, To create a new Rule-based policy, in the dropdown list in the right upper corner of the policy listing,
select *Rule*. select *Rule*.
.Add Rule Policy .Add Rule Policy

View file

@ -4,7 +4,7 @@
You can use this type of policy to define conditions for your permissions using JavaScript. It is one of the rule-based policy types You can use this type of policy to define conditions for your permissions using JavaScript. It is one of the rule-based policy types
supported by {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>. supported by {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
To create a new JavaScript-based policy, select *JavaScript* in the dropdown list in the upper right corner of the permission listing. To create a new JavaScript-based policy, select *JavaScript* in the dropdown list in the upper right corner of the policy listing.
.Add JavaScript Policy .Add JavaScript Policy
image:../../{{book.images}}/policy/create-js.png[alt="Add JavaScript Policy"] image:../../{{book.images}}/policy/create-js.png[alt="Add JavaScript Policy"]

View file

@ -7,7 +7,7 @@ By default, roles added to this policy are not specified as required and the pol
Role policies can be useful when you need more restricted role-based access control (RBAC), where specific roles must be enforced to grant access to an object. For instance, you can enforce that a user must consent to allowing a client application (which is acting on the user's behalf) to access the user's resources. You can use {{book.project.name}} Client Scope Mapping to enable consent pages or even enforce clients to explicitly provide a scope when obtaining access tokens from a {{book.project.name}} server. Role policies can be useful when you need more restricted role-based access control (RBAC), where specific roles must be enforced to grant access to an object. For instance, you can enforce that a user must consent to allowing a client application (which is acting on the user's behalf) to access the user's resources. You can use {{book.project.name}} Client Scope Mapping to enable consent pages or even enforce clients to explicitly provide a scope when obtaining access tokens from a {{book.project.name}} server.
To create a new role-based policy, select *Role-Based* in the dropdown list in the upper right corner of the permission listing. To create a new role-based policy, select *Role* in the dropdown list in the upper right corner of the policy listing.
.Add Role-Based Policy .Add Role-Based Policy
image:../../{{book.images}}/policy/create-role.png[alt="Add Role-Based Policy"] image:../../{{book.images}}/policy/create-role.png[alt="Add Role-Based Policy"]

View file

@ -3,7 +3,7 @@
You can use this type of policy to define time conditions for your permissions. You can use this type of policy to define time conditions for your permissions.
To create a new time-based policy, select *Time* in the dropdown list in the upper right corner of the permission listing. To create a new time-based policy, select *Time* in the dropdown list in the upper right corner of the policy listing.
.Add Time Policy .Add Time Policy
image:../../{{book.images}}/policy/create-time.png[alt="Add Time Policy"] image:../../{{book.images}}/policy/create-time.png[alt="Add Time Policy"]

View file

@ -3,7 +3,7 @@
You can use this type of policy to define conditions for your permissions where a set of one or more users is permitted to access an object. You can use this type of policy to define conditions for your permissions where a set of one or more users is permitted to access an object.
To create a new user-based policy, select *User-Based* in the dropdown list in the upper right corner of the permission listing. To create a new user-based policy, select *User* in the dropdown list in the upper right corner of the policy listing.
.Add a User-Based Policy .Add a User-Based Policy
image:../../{{book.images}}/policy/create-user.png[alt="Add User-Based Policy"] image:../../{{book.images}}/policy/create-user.png[alt="Add User-Based Policy"]

View file

@ -1,7 +1,10 @@
[[_service_client_api]] [[_service_client_api]]
=== Authorization Client Java API === Authorization Client Java API
If you are using Java, you can access all {{book.project.name}} {{book.project.module}} using a client API. Depending on your requirements, a resource server should be able to manage resources remotely or even check for permissions programmatically.
If you are using Java, you can access the {{book.project.name}} Authorization Services using the Authorization Client API.
It is targeted for resource servers that want to access the different APIs provided by the server such as the Protection, Authorization and Entitlement APIs.
==== Maven Dependency ==== Maven Dependency
@ -17,7 +20,7 @@ If you are using Java, you can access all {{book.project.name}} {{book.project.m
==== Configuration ==== Configuration
The client configuration is defined in a JSON file as follows: The client configuration is defined in a ``keycloak.json`` file as follows:
```json ```json
{ {
@ -43,7 +46,18 @@ The base URL of the {{book.project.name}} server. All other {{book.project.name}
The client-id of the application. Each application has a client-id that is used to identify the application. The client-id of the application. Each application has a client-id that is used to identify the application.
* *credentials* (required) * *credentials* (required)
Specifies the credentials of the application. This is an object notation where the key is the credential type and the value is the value of the credential type. Currently only secret/password is supported. Specifies the credentials of the application. This is an object notation where the key is the credential type and the value is the value of the credential type.
The configuration file is usually located in your application's classpath, the default location from where the client is going to try to find a ```keycloak.json``` file.
==== Creating the Authorization Client
Considering you have a ```keycloak.json``` file in your classpath, you can create a new ```AuthzClient``` instance as follows:
```java
// create a new instance based on the configuration defined in a keycloak.json located in your classpath
AuthzClient authzClient = AuthzClient.create();
```
==== Obtaining User Entitlements ==== Obtaining User Entitlements
@ -55,17 +69,14 @@ AuthzClient authzClient = AuthzClient.create();
// obtain an Entitlement API Token to get access to the Entitlement API. // obtain an Entitlement API Token to get access to the Entitlement API.
// this token is an access token issued to a client on behalf of an user // this token is an access token issued to a client on behalf of an user
// with a scope = kc_entitlement // with a uma_authorization scope
String eat = getEntitlementAPIToken(authzClient); String eat = getEntitlementAPIToken(authzClient);
// send the entitlement request to the server to // send the entitlement request to the server to
// obtain an RPT with all permissions granted to the user // obtain an RPT with all permissions granted to the user
EntitlementResponse response = authzClient.entitlement(eat) EntitlementResponse response = authzClient.entitlement(eat).getAll("hello-world-authz-service");
.getAll("hello-world-authz-service");
String rpt = response.getRpt(); String rpt = response.getRpt();
System.out.println("You got a RPT: " + rpt);
// now you can use the RPT to access protected resources on the resource server // now you can use the RPT to access protected resources on the resource server
``` ```
@ -77,7 +88,7 @@ AuthzClient authzClient = AuthzClient.create();
// obtain an Entitlement API Token to get access to the Entitlement API. // obtain an Entitlement API Token to get access to the Entitlement API.
// this token is an access token issued to a client on behalf of an user // this token is an access token issued to a client on behalf of an user
// with a scope = kc_entitlement // with a uma_authorization scope
String eat = getEntitlementAPIToken(authzClient); String eat = getEntitlementAPIToken(authzClient);
// create an entitlement request // create an entitlement request
@ -90,11 +101,10 @@ request.addPermission(permission);
// send the entitlement request to the server to obtain an RPT // send the entitlement request to the server to obtain an RPT
// with all permissions granted to the user // with all permissions granted to the user
EntitlementResponse response = authzClient.entitlement(eat) EntitlementResponse response = authzClient.entitlement(eat).get("hello-world-authz-service", request);
.get("hello-world-authz-service", request);
String rpt = response.getRpt(); String rpt = response.getRpt();
System.out.println("You got a RPT: " + rpt); // now you can use the RPT to access protected resources on the resource server
``` ```
==== Creating a Resource Using the Protection API ==== Creating a Resource Using the Protection API
@ -112,8 +122,7 @@ newResource.setType("urn:hello-world-authz:resources:example");
newResource.addScope(new ScopeRepresentation("urn:hello-world-authz:scopes:view")); newResource.addScope(new ScopeRepresentation("urn:hello-world-authz:scopes:view"));
ProtectedResource resourceClient = authzClient.protection().resource(); ProtectedResource resourceClient = authzClient.protection().resource();
Set<String> existingResource = resourceClient Set<String> existingResource = resourceClient.findByFilter("name=" + newResource.getName());
.findByFilter("name=" + newResource.getName());
if (!existingResource.isEmpty()) { if (!existingResource.isEmpty()) {
resourceClient.delete(existingResource.iterator().next()); resourceClient.delete(existingResource.iterator().next());
@ -125,4 +134,18 @@ String resourceId = response.getId();
// query the resource using its newly generated id // query the resource using its newly generated id
ResourceRepresentation resource = resourceClient.findById(resourceId).getResourceDescription(); ResourceRepresentation resource = resourceClient.findById(resourceId).getResourceDescription();
```
==== Introspecting a RPT
```java
AuthzClient authzClient = AuthzClient.create();
String rpt = getRequestingPartyToken(authzClient);
TokenIntrospectionResponse requestingPartyToken = authzClient.protection().introspectRequestingPartyToken(rpt);
if (requestingPartyToken.getActive()) {
for (Permission granted : requestingPartyToken.getPermissions()) {
// iterate over the granted permissions
}
}
``` ```