Okta Shiro Plugin

• Release status
• Need help?
• Getting started
• Usage guide
• Configuration reference
• Building this project
• Contributing

This repository contains a Shiro Realm for Okta, for use with OAuth 2.0 Resource Servers. This realm will validate Okta JWT access tokens.

We also publish these libraries for Java:

• Spring Boot Integration
• Okta JWT Verifier for Java
• Management SDK

You can learn more on the Okta + Java page in our documentation.

Release status

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

✔️ The current stable major version series is: 1.x

Version	Status
0.x.0	Beta

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

Need help?

If you run into problems using this project, you can

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

Getting started

To use this Shiro (1.5+) realm you will need to include the following dependency:

For Apache Maven:

<dependency>
    <groupId>com.okta.shiro</groupId>
    <artifactId>okta-shiro-plugin</artifactId>
    <version>${okta.shiro.version}</version>
</dependency>

For Gradle:

runtime "com.okta.shiro:okta-shiro-plugin:${okta.shiro.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/

You'll also need:

• An Okta account, called an organization (sign up for a free developer organization if you need one)
• Another application configured to send access tokens to the project using this plugin. You could use Spring Cloud Gateway

Usage guide

This plugin provides a Shiro Realm that will authenticate requests with an Authorization: Bearer <access-token> header.

To use the realm, first define and configure the OktaResourceServerRealm

[main]
# define the realm
oktaRealm = com.okta.shiro.realm.OktaResourceServerRealm

# Set the issuer to your Okta org
oktaRealm.issuer = https://{yourOktaDomain}/oauth2/default

# Additionally, you can override the following default values
oktaRealm.audience = "api://default"
oktaRealm.groupClaim = "groups"
oktaRealm.nameClaim = "sub"

[urls]
# You must use the `authcBearer` filer to parse access token from the `Authorization` header
/** = authcBearer

The JWT claim information can be retrieved from the current Shiro Subject by casting the principal to OktaJwtPrincipal:

import com.okta.shiro.OktaJwtPrincipal;
...

OktaJwtPrincipal jwtPrincipal = (OktaJwtPrincipal) SecurityUtils.getSubject().getPrincipal();

See the examples to help you get started even faster:

• JAX-RS
• Servlet

Building the Project

In most cases, you won't need to build this project from source. If you want to build it yourself, just clone the repo and run:

./mvnw install

Contributing

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