okta-sdk-java

This SDK is in EA, so all existing features are supported by Okta in a production setting.

This version of the Okta Java SDK supports CRUD (Create, Read, Update, Delete) operations for the following resource:

• User
• Group
• Group Membership Rules

Usage

Javadocs

You can see this project's Javadocs at https://developer.okta.com/okta-sdk-java/apidocs/.

Dependencies

The only compile time dependency you will need is okta-sdk-api. You will also need to add the implementation dependencies too: okta-sdk-impl and okta-sdk-httpclient.

<dependency>
    <groupId>com.okta.sdk</groupId>
    <artifactId>okta-sdk-api</artifactId>
    <version>${okta.version}</version>
</dependency>
<dependency>
    <groupId>com.okta.sdk</groupId>
    <artifactId>okta-sdk-impl</artifactId>
    <version>${okta.version}</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>com.okta.sdk</groupId>
    <artifactId>okta-sdk-httpclient</artifactId>
    <version>${okta.version}</version>
    <scope>runtime</scope>
</dependency>

SNAPSHOT Dependencies

Snapshots are deployed off of the 'master' branch to OSSRH and can be consumed using the following repository configured for Apache Maven or Gradle:

https://oss.sonatype.org/content/repositories/snapshots/

Client configuration

There are a few ways to configure the client, but the easiest way is to create a ~/.okta/okta.yamlfile and set the token and orgUrl values:

okta:
  client:
    token: <your-api-token>
    orgUrl: https://dev-123456.oktapreview.com

Creating a Client

Once you create your okta.yaml file, you can create a client with a couple of lines:

// Instantiate a builder for your Client. If needed, settings like Proxy and Caching can be defined here.
ClientBuilder builder = Clients.builder();

// No need to define anything else; build the Client instance. The ClientCredential information will be automatically found
// in pre-defined locations.
Client client = builder.build();

For more details see: Creating a Client

Client CRUD Operations

The client is used to perform CRUD operations against Okta's management APIs.

Create a group:

UserGroup group = GroupBuilder.instance()
        .setName("my-user-group-" + UUID.randomUUID().toString())
        .setDescription("Quickstart created Group")
        .buildAndCreate(client);

// print a couple of the attributes
println("Group: '" + group.getId() + "' was last updated on: " + group.getLastUpdated());

Create a User Account:

String email = "joe.coder+" + UUID.randomUUID().toString() + "@example.com";

User user = UserBuilder.instance()
    .setEmail(email)
    .setFirstName("Joe")
    .setLastName("Coder")
    .setPassword("Password1")
    .setSecurityQuestion("Favorite security question?")
    .setSecurityQuestionAnswer("None of them!")
    .putProfileProperty("division", "Seven") // key/value pairs predefined in the user profile schema
    .setActive(true)
    .buildAndCreate(client);

String userId = user.getId();
println("User created with ID: " + userId);

Add user to the newly created group:

user.addToGroup(group.getId());

User lookup by ID or email:

// You can look up user by ID
println("User lookup by ID: "+ client.getUser(userId).getProfile().getLogin());

// or by Email
println("User lookup by Email: "+ client.getUser(email).getProfile().getLogin());

Paging

Paging is handled automatically when iterating over a any collection.

// get the list of users
UserList users = client.listUsers();

// get the first user in the collection
println("First user in collection: " + users.iterator().next().getProfile().getEmail());

// or loop through all of them (paging is automatic)
int ii = 0;
for (User tmpUser : users) {
    println("["+ ii++ +"] User: " + tmpUser.getProfile().getEmail());
}

Contribute to the Project

Take a look at the (contribution guide)[CONTRIBUTING.md] and the build instructions wiki (though just cloning the repo and running mvn install should get you going).

Versioning

This project follows SemVer to retain binary compatibility (not source compatibility). This is similar to the stance the OSGI Alliance has taken.

In practical terms this means we may add methods to interfaces between MINOR version releases, this should not affect your application at runtime. If for some reason this is causing your project a lot of grief please reach out to us!