kaiyaok2 / okta-hooks-sdk-java

Okta Hooks SDK for Java

Okta Hooks SDK for Java

• Release status
• Need help?
• Getting started
• Usage guide
• Building the SDK
• Contributing

The Okta Hooks SDK for Java project contains utilities to make responding to Okta's Hooks easy. For more information on Okta's Inline hooks checkout out the Documentation.

Release status

This library uses semantic versioning and follows Okta's library version policy.

✔️ The current beta major version series is: 0.1.x

Version	Status
0.1.x	⚠️ Beta

The latest release can always be found on the releases page.

Need help?

If you run into problems using the SDK, you can

• Ask questions on the Okta Developer Forums
• Post issues here on GitHub (for code errors)

Getting started

To use this SDK you will need to include the following dependencies:

For Apache Maven:

<dependency>
    <groupId>com.okta.hooks.sdk</groupId>
    <artifactId>okta-hooks</artifactId>
    <version>${okta.version}</version>
</dependency>

For Gradle:

compile "com.okta.hooks.sdk:okta-hooks:${okta.version}"

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/

Usage guide

These examples will help you understand how to use this library. You can also browse the full API reference documentation.

This library helps you build the response objects for an Okta Inline Hook. Before you use this library you will need to setup a route or controller that will listen for the incoming hook from Okta.

Serialization can be handled within the library or through another framework.

For example a simple Spring Controller might look like:

@PostMapping("/user-reg")
public HookResponse userReg(@RequestBody String request) throws IOException {

    return Hooks.builder()
            .userRegistration(denyRegistration())
            .build();
}

Or you could serialize directly by calling the toString() method on the builder instance:

String result = Hooks.builder()
            .userRegistration(denyRegistration())
            .toString();

These examples below make use of static imported methods, to see the full example with package declarations checkout ReadmeSnippets.

OAuth2/OIDC Tokens Hooks

Okta's Token Inline Hook docs

Error

Hooks.builder()
    .error("Some Error")
    .build();

Noop Success

Hooks.builder()
    .build();

Add Claim to Access Token

Hooks.builder()
    .oauth2(addAccessTokenClaim("aClaim", "test-value"))
    .build();

Add Claim to ID Token

Hooks.builder()
    .oauth2(addIdTokenClaim("iClaim", "another-value"))
    .build();

User Registration Hooks

Okta's Registration Inline Hook docs

Error

Hooks.builder()
    .errorCause("An Error")
    .build();

Deny Registration

Hooks.builder()
    .userRegistration(denyRegistration())
    .build();

Allow Registration

Hooks.builder()
    .userRegistration(allowRegistration())
    .build();

Add User Profile Property

Hooks.builder()
    .userRegistration(UserRegistrationCommand.addProfileProperties(
            Collections.singletonMap("someKey", "a-value")))
    .build();

Import Users Hook

Okta's Import Inline Hooks docs

Add User Profile Property

Hooks.builder()
    .userImport(UserImportCommand.addProfileProperties(
            Collections.singletonMap("someKey", "a-value")))
    .build();

Create User

Hooks.builder()
    .userImport(createUser())
    .build();

Link User

Hooks.builder()
    .userImport(linkUser("oktaUserId"))
    .build();

SAML Assertion Hooks

Okta's SAML Assertion Inline Hooks docs

Replace Attribute

Hooks.builder()
    .samlAssertion(replace("/claims/array/attributeValues/1/value", "replacementValue"))
    .build();

Add Attribute

Hooks.builder()
    .samlAssertion(add("/claims/foo", new SamlAssertionCommand.SamlAttribute()
        .setAttributes(Collections.singletonMap("NameFormat", "urn:oasis:names:tc:SAML:2.0:attrname-format:basic"))
        .setAttributeValues(Collections.singletonList(
            new SamlAssertionCommand.SamlAttributeValue()
                .setAttributes(Collections.singletonMap("xsi:type", "xs:string"))
                .setValue("bearer")))))
    .build();

Add Debug Information

Additional debug information can be added to any hook response, these additional fields will be available via Okta's System Log, and as such should NOT contain any secrets.

Hooks.builder()
    .errorCause("An Error")
    .debugContext(Collections.singletonMap("key", "value"))
    .build();

Building the SDK

In most cases, you won't need to build the SDK from source. If you want to build it yourself, take a look at the build instructions wiki (though just cloning the repo and running mvn install should get you going).

Contributing

We're happy to accept contributions and PRs! Please see the contribution guide to understand how to structure a contribution.