Working With OpenStack4j Identity Service (Keystone) V3

OpenStack4j is an open source library that helps you manage an OpenStack deployment. It is a fluent-based API giving you full control over the various OpenStack services.

Grab the latest release of Openstack4j from the central Maven repository. Starting with version 3.0.0+ OpenStack4j now has the ability to choose the underlying connection framework. By default, the APIs are configured to use the Jersey 2 connector. See optional configuration scenarios below:

Default Setup (Using Jersey 2 as the Connector)

<dependency>
    <groupId>org.pacesys</groupId>
    <artifactId>openstack4j</artifactId>
    <version>3.0.3</version>
</dependency>

With Dependencies (All in One JAR)

<dependency>
    <groupId>org.pacesys</groupId>
    <artifactId>openstack4j</artifactId>
    <version>3.0.3</version>
    <classifier>withdeps</classifier>
</dependency>

Using a Connector of Your Choice

• Declare the openstack4j core dependency in your POM   

<dependency>
    <groupId>org.pacesys</groupId>
    <artifactId>openstack4j-core</artifactId>
    <version>3.0.3</version>
</dependency>

• Declare a connector

<dependency>
    <groupId>org.pacesys.openstack4j.connectors</groupId>
    <artifactId>[ connector artifactId ]</artifactId>
    <version>3.0.3</version>
</dependency>

Valid artifactId's are: openstack4j-jersey2, openstack4j-jersey2-jdk16 [OS4J 2.0.X Only], openstack4j-resteasy, openstack4j-okhttp and openstack4j-httpclient.

Identity Service V3

The Identity (Keystone) V3 service provides the central directory of users, groups, region, service, endpoints, role management and authorization. This API is responsible for authenticating and providing access to all the other OpenStack services. The API also enables administrators to configured centralized access policies, users, domains, and projects.

Version 3 Authentication

import org.openstack4j.api.OSClient.OSClientV3;
import org.openstack4j.openstack.OSFactory;
import org.openstack4j.model.common.Identifier;

// use Identifier.byId("domainId") or Identifier.byName("example-domain")
Identifier domainIdentifier = Identifier.byId("domainId");

// unscoped authentication
// as the username is not unique across domains you need to provide the domainIdentifier
OSClientV3 os = OSFactory.builderV3()
                       .endpoint("http://127.0.0.1:5000/v3")
                       .credentials("admin","sample", domainIdentifier)
                       .authenticate();

// project scoped authentication
OSClientV3 os = OSFactory.builderV3()
                    .endpoint("http://127.0.0.1:5000/v3")
                    .credentials("admin", "secret", Identifier.byName("example-domain"))
                    .scopeToProject(Identifier.byId(projectIdentifier))
                    .authenticate();

// domain scoped authentication
// using the unique userId does not require a domainIdentifier
OSClientV3 os = OSFactory.builderV3()
                    .endpoint("http://127.0.0.1:5000/v3")
                    .credentials("userId", "secret")
                    .scopeToDomain(Identifier.byId(domainIdentifier))
                    .authenticate();

// Scoping to a project just by name isn't possible as the project name is only unique within a domain.
// You can either use this as the id of the project is unique across domains  
OSClientV3 os = OSFactory.builderV3()
                    .endpoint("http://127.0.0.1:5000/v3")
                    .credentials("userId", "secret")
                    .scopeToProject(Identifier.byName(projectName), Identifier.byName(domainName))
                    .authenticate();

// Or alternatively
OSClientV3 os = OSFactory.builderV3()
                    .endpoint("http://127.0.0.1:5000/v3")
                    .credentials("userId", "secret")
                    .scopeToDomain(Identifier.byName(domainName))
                    .authenticate();

Regions

OpenStack4j supports the ability to switch from one region to another within the same client. If you have a regional deployment (example: West and East coast) and would like to target certain calls to specific region see the sample below:

Switch to Another Region

// Switch to East Coast
os.useRegion("EastRegion");
List<? extends Server> eastServers = os.compute().servers().list();

// Switch to West Coast
os.useRegion("WestRegion");
List<? extends Server> westServers = os.compute().servers().list();

// Switch to Default - No region specified
os.removeRegion();

Creating a Region

Region region = os.identity().regions()
                                .create(Builders.regions()
                                .id("EastRegion")
                                .description("Region for east coast")
                                .build());

Querying for Regions

Find all Regions

List<? extends Region> regionList = os.identity().regions().list();

Find a specific Region

//Find by ID
Region region = os.identity().regions().get("EastRegion");

Updating a region

This example will change the description of EastRegion from Region for east coast to East coast region by looking up the region and updating it. The example also shows the fluent nature of the API and how easy you can go to and from a mutable state via builder

Region region = os.identity().regions().get("EastRegion");
if (region != null)
  region = os.identity().regions().update(region.toBuilder().description("East coast region").build());

Deleting a Region

This example will delete the EastRegion we have been working with

os.identity().regions().delete(region.getId());

Domains

The examples below will show basic Domain operations

Creating a Domain

Domain domain = os.identity().domains().create(Builders.domain()
            .name("domainName")
            .description("This is a new domain.")
            .enabled(true)
            .build());

Querying for Domains

Find all Domains

List<? extends Domain> domainList = os.identity().domains().list();

Find a Specific Domain

//Find by ID
Domain domain = os.identity().domains().get("domainId");

Updating a Domain

This example will change the enabled-status of the domain from true to false by looking up the domain and updating it. The example also shows the fluent nature of the API and how easy you can go to and from a mutable state via builder

Domain domain = os.identity().domains().get("domainId");
if (domain != null)
  domain = os.identity().domains().update(domain.toBuilder().enabled(false).build());

Deleting a Domain

This example will delete the Domain we have been working with

os.identity().domains().delete(domain.getId());

Projects

The examples below will show basic Project operations

Creating a Project

Project project = os.identity().projects().create(Builders.project()
            .name("projectName")
            .description("This is a new project.")
            .enabled(true)
            .build());

Querying for Projects

Find All Projects

List<? extends Project> projectList = os.identity().projects().list();

Find a Specific Project

//Find by ID
Project project = os.identity().projects().get("projectId");
//Find by Name and Domain
Project project = os.identity().projects().getByName("projectName","projectDomainId");

//Find by Name accross all Domains
List<? extends Project> projectList = os.identity().projects().getByName("projectName");

Updating a Project

This example will change the enabled-status of the project from true to false by looking up the domain and updating it. The example also shows the fluent nature of the API and how easy you can go to and from a mutable state via builder

Project project = os.identity().projects().get("projectId");
if (project != null)
  project = os.identity().projects().update(project.toBuilder().enabled(false).build());

Deleting a Project

This example will delete the Project we have been working with

os.identity().projects().delete(project.getId());

Users

The examples below will show basic User operations

Creating a User

User user = os.identity().users().create(Builders.user()
                                            .name("Foobar")
                                            .description("A new user.")
                                            .password("secret")
                                            .email("foobar@example.org")
                                            .domainId("domainId")
                                            .build());

Querying for Users

Find all Users

List<? extends User> userList = os.identity().users().list();

Find a specific User

//Find by ID
User user = os.identity().users().get("userId");

//Find by name and domain
User user = os.identity().users().getByName("userName", "userDomainId");

// Find user by name across all domains
List<? extends Users> userList = os.identity().users().getByName("userName");

List Roles for User

//In a Domain
List<? extends Role> domainUserRolesList = os.identity().users().listDomainUserRoles("userId", "domainId");

//In a Project
List<? extends Role> projectUserRolesList = os.identity().users().listProjectUserRoles("userId", "projectId");

List Groups for User

List<? extends Group> userGroupsList = os.identity().users().listUserGroups("userId");

Updating a User

This example will change the email of the user Foobar from foobar@example.org to foobar@openstack.com by looking up the user and updating it. The example also shows the fluent nature of the API and how easy you can go to and from a mutable state via builder

User user = os.identity().users().get("userId");
if (user != null)
  user = os.identity().users().update(user.toBuilder().email("foobar@openstack.com").build());

Deleting a User

This example will delete the User Foobar we have been working with

os.identity().users().delete(user.getId());

Groups

The examples below will show basic Group operations

Creating a Group

Group group = os.identity().groups().create(Builders.group()
                                                .name("myGroup")
                                                .description("A new group.")
                                                .domainId("domainId")
                                                .build());

Querying for Groups

Find All Groups

List<? extends Group> groupList = os.identity().groups().list();

Find a Specific Group

//Find by ID
Group group = os.identity().groups().get("groupId");

//Find by Name
List<? extends Group> groupList = os.identity().groups().getByName("groupName")

List the Users in a Group

List<? extends User> userGroupList = os.identity().groups().listGroupUsers("groupId");

Group Management

// Add user to group
os.identity().groups().addUserToGroup("groupId", "userId");

// Check if a user is a member of a group
os.identity().groups().checkGroupUser("groupId", "userId");

// Remove user from group
os.identity().groups().removeUserFromGroup("groupId", "userId");

Updating a Group

Group group = os.identity().groups().get("groupId");
if (group != null)
  group = os.identity().groups().update(group.toBuilder().description("admin-group").build());

Deleting a Group

This example will delete the Group myGroup we have been working with

os.identity().groups().delete(group.getId());

Role Management

The examples below will show basic Role and role management operations

Creating a Role

Role role = os.identity().roles().create(Builders.role()
                                            .name("developer")
                                            .build());

Querying for Roles

Find All Roles

List<? extends Role> roleList = os.identity().roles().list();

Find a Specific Role

//Find by ID
Role role = os.identity().roles().get("roleId");

//Find by Name
List<? extends Role> roleList = os.identity().roles().getByName("roleName")

Role Assignments

This example will show how to grant and revoke roles to/from a user and group in both project and domain contexts.

To a User

//Grant a role to a user in a project
ActionResponse grantProjectRole = os.identity().roles().grantProjectUserRole("projectId", "userId", "roleId");

//Check if a user has a specific role in a project
ActionResponse checkProjectRole = os.identity().roles().checkProjectUserRole("projectId", "userId", "roleId");

//Revoke a role from a user in a project
ActionResponse revokeProjectRole = os.identity().roles().revokeProjectUserRole("projectId", "userId", "roleId");

//Grant a role to a user in a domain
ActionResponse grantDomainRole = os.identity().roles().grantDomainUserRole("domainId", "userId", "roleId");

//Check if a user has a specific role in a domain
ActionResponse checkDomainRole = os.identity().roles().checkDomainUserRole("domainId", "userId", "roleId");

//Revoke a role from a user in a domain
ActionResponse revokeDomainRole = os.identity().roles().revokeDomainUserRole("domainId", "userId", "roleId");

To a Group

//Grant a role to a group in a project
ActionResponse grantProjectRole = os.identity().roles().grantProjectGroupRole("projectId", "groupId", "roleId");

//Check if a group has a specific role in a project
ActionResponse checkProjectRole = os.identity().roles().checkProjectGroupRole("projectId", "groupId", "roleId");

//Revoke a role from a group in a project
ActionResponse revokeProjectRole = os.identity().roles().revokeProjectGroupRole("projectId", "groupId", "roleId");

//Grant a role to a group in a domain
ActionResponse grantDomainRole = os.identity().roles().grantDomainGroupRole("domainId", "groupId", "roleId");

//Check if a group has a specific role in a domain
ActionResponse checkDomainRole = os.identity().roles().checkDomainGroupRole("domainId", "groupId", "roleId");

//Revoke a role from a group in a domain
ActionResponse revokeDomainRole = os.identity().roles().revokeDomainGroupRole("domainId", "groupId", "roleId");

Updating a Role

This example will change the name of the role from developer to admin-role by looking up the role and updating it. The example also shows the fluent nature of the API and how easy you can go to and from a mutable state via builder:

Role role = os.identity().roles().get("roleId");
if (role != null)
  role = os.identity().roles().update(role.toBuilder().name("admin-role").build());

Deleting a Role

This example will delete the Role we have been working with

os.identity().roles().delete(role.getId());

Policies

The examples below will show basic Policy operations

Creating a Policy

Policy policy = os.identity().policies().create(Builders.policy()
                                                    .blob("{'foobar' : 'role:admin-user'}")
                                                    .type("application/json")
                                                    .projectId("projectId")
                                                    .userId("userId")
                                                    .build());

Querying for Policies

Find all Policies

List<? extends Policy> policyList = os.identity().policies().list();

Find a Specific Policy

//Find by ID
Policy policy_byId = os.identity().policies().get("policyId");

Updating a Policy

This example will change the blob of the policy from {'foobar': 'role:admin-user'} to {'foobar': 'role:demo-user'} by looking up the policy and updating it. The example also shows the fluent nature of the API and how easy you can go to and from a mutable state via builder:

Policy policy = os.identity().policies().get("policyId");
if (policy != null)
  policy = os.identity().policies().update(policy.toBuilder().blob("{'foobar': 'role:demo-user'}").build());

Deleting a Policy

This example will delete the Policy we have been working with

os.identity().policies().delete(policy.getId());

Services and Endpoints

The examples below will show basic Services & Endpoints operations

Creating a Service

Service service = os.identity().serviceEndpoints().create(Builders.service()
                                                            .type("serviceType")
                                                            .name("serviceName")
                                                            .description("A new service.")
                                                            .enabled(true)
                                                            .build());

Querying for Services

Find all Services

List<? extends Service> serviceList = os.identity().serviceEndpoints().list();

Find a specific Service

//Find by ID
Service service = os.identity().serviceEndpoints().get("serviceId");

Updating a Service

This example will change the description of the service from "A new service." to "Identity V3 Service" by looking up the service and updating it. The example also shows the fluent nature of the API and how easy you can go to and from a mutable state via builder.

Service service = os.identity().services().get("serviceId");
if (service != null)
  service = os.identity().services().update(service.toBuilder().description("Identity V3 Service").build());

Deleting a Service

This example will delete the Service we have been working with

os.identity().services().delete(service.getId());

Creating an Endpoint for a Service

This example will create an endpoint for a service specified by its identifier.

Endpoint endpoint = os.identity().serviceEndpoints().createEndpoint(Builders.endpoint()
                                                                        .name("endpointName")
                                                                        .url(new URL( "http", "devstack.openstack.stack", 5000, "/v3"))
                                                                        .iFace(Facing.ADMIN).regionId("regionId")
                                                                        .serviceId("serviceId")
                                                                        .enabled(true)
                                                                        .build());

Querying for Endpoints

Find All Available Endpoints

List<? extends Endpoint> endpointList = os.identity().serviceEndpoints().listEndpoints()

Find a Specific Endpoint

Endpoint endpoint = os.identity().serviceEndpoints().getEndpoint("endpointId")

Updating an Endpoint

This example will change the URL of the endpoint from http://devstack.openstack.stack:5000/v3 to http://openstack.stack:5000/v3 by looking up the endpoint and updating it. The example also shows the fluent nature of the API and how easy you can go to and from a mutable state via builder.

Endpoint endpoint = os.identity().services().getEndpoint("endpointId");
if (endpoint != null)
  endpoint = os.identity().services().updateEndpoint(endpoint.toBuilder().url(new URL( "http", "openstack.stack", 5000, "/v3")).build());

Deleting an Endpoint

os.identity().serviceEndpoints().deleteEndpoint("endpointId");

Credentials

The examples below will show basic Credential operations

Creating a Credential

Credential credential = os.identity().credentials().create(Builders.credential()
                                            .blob("{\"access\":\"181920\",\"secret\":\"secretKey\"}")
                                            .type("ec2")
                                            .projectId("projectId")
                                            .userId("userId")
                                            .build());

Find All Credentials

List<? extends Credential> credentialList = os.identity().credentials().list();

Find a Specific Credential

//Find by ID
Credential credential = os.identity().credentials().get("credentialId");

Updating a Credential

This example will change the BLOB of the Credential from:

{\"access\":\"181920\",\"secret\":\"secretKey\"}
to
{\"access\":\"181920\",\"secret\":\"updatedSecretKey\"}

by looking up the credential and updating it. The example also shows the fluent nature of the API and how easy you can go to and from a mutable state via builder

Credential credential = os.identity().credentials().get("credential id");
if (credential != null)
    credential = os.identity().credentials().update(credential.toBuilder()
                                .blob("{\"access\":\"181920\",\"secret\":\"updatedSecretKey\"}")
                                .build());

Deleting a Credential

This example will delete the Credential we have been working with

os.identity().credentials().delete("credentialId");

Tokens

Tokens are obtained during authentication. Please refer to the authentication guide.

Validating Another Token

// validate and show details for another token
Token token = os.identity().tokens().get("USER_TOKEN_ID")

// validate another token
ActionResponse validateToken = os.identity().tokens().check("USER_TOKEN_ID")

Get a Service Catalog for Another Token

// get service catalog for
List<? extends Service> serviceCatalog = os.identity().tokens().getServiceCatalog("USER_TOKEN_ID");

Get Available Scopes for Another Token

// get available project scopes
List<? extends Project> availableProjectScopes = os.identity().tokens().getProjectScopes("USER_TOKEN_ID");

// get available domain scopes
List<? extends Domain> availableDomainScopes = os.identity().tokens().getDomainScopes("USER_TOKEN_ID");

Deleting Another Token

ActionResponse deleteToken = os.identity().tokens().delete("USER_TOKEN_ID")