keycloak-scim/topics/service/client-api.adoc

== Authorization Client API

If you are using Java you can access all {{book.project.name}} {{book.project.module}} using a client API.

=== Maven Dependency

```xml
<dependencies>
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-authz-client</artifactId>
        <version>${KEYCLOAK_VERSION}</version>
    </dependency>
</dependencies>
```

=== Configuration

The client configuration is defined in a JSON file as follows:

```json
{
  "client": {
    "configurationUrl": "http://localhost:8080/auth/realms/${realm_name}/.well-known/uma-configuration",
    "clientId": ${clientId},
    "clientSecret": ${clientSecret}
  }
}
```

* *configurationUrl*
+
Use this property to specify and URL pointing to the Authorization Services Discovery URL.
+
* *clientId*
+
The identifier of the client application configured as a resource server
+
* *clientSecret*
+
The credential of the client application configured as a resource server

=== Obtaining User Entitlements

Here is an example about how to obtain user entitlements:

```java
// create a new instance based on the configuration define at keycloak-authz.json
AuthzClient authzClient = AuthzClient.create();

// query the server for a resource with a given name
Set<String> resourceId = authzClient.protection()
        .resource()
            .findByFilter("name=Hello World Resource");

// obtian a Entitlement API Token in order to get access to the Entitlement API.
// this token is just an access token issued to a client on behalf of an user with a scope kc_entitlement
String eat = getEntitlementAPIToken(authzClient);

// create an entitlement request
EntitlementRequest request = new EntitlementRequest();

request.addPermission(new PermissionRequest(resourceId.iterator().next()));

// send the entitlement request to the server in order to obtain a RPT with all permissions granted to the user
EntitlementResponse response = authzClient.entitlement(eat)
    .get("hello-world-authz-service", request);
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
```

Here is an example about how to obtain user entitlements given a set of one or more resource:

```java
// create a new instance based on the configuration define at keycloak-authz.json
AuthzClient authzClient = AuthzClient.create();

// obtian a Entitlement API Token in order to get access to the Entitlement API.
// this token is just an access token issued to a client on behalf of an user with a scope kc_entitlement
String eat = getEntitlementAPIToken(authzClient);

// send the entitlement request to the server in order to obtain a RPT with all permissions granted to the user
EntitlementResponse response = authzClient.entitlement(eat)
    .getAll("hello-world-authz-service", request);
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

```java
// create a new instance based on the configuration define at keycloak-authz.json
AuthzClient authzClient = AuthzClient.create();

// create a new resource representation with the information we want
ResourceRepresentation newResource = new ResourceRepresentation();

newResource.setName("New Resource");
newResource.setType("urn:hello-world-authz:resources:example");

newResource.addScope(new ScopeRepresentation("urn:hello-world-authz:scopes:view"));

ProtectedResource resourceClient = authzClient.protection().resource();

// create the resource on the server
RegistrationResponse response = resourceClient.create(newResource);
String resourceId = response.getId();

// query the resource using its newly generated id
ResourceRepresentation resource = resourceClient.findById(resourceId).getResourceDescription();
```java