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:

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:

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.

isabella232 / okta-shiro-plugin Goto Github PK