JarCasting
Okta Hooks SDK for Java
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.
| Version | Status |
|---|---|
| 0.1.x | |
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.
