Package com.osohq.oso_cloud

Class Oso

java.lang.Object

com.osohq.oso_cloud.Oso

public class Oso
extends java.lang.Object

Oso Cloud client.

For more detailed documentation, see https://www.osohq.com/docs/app-integration/client-apis/java

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	Oso.Async

Constructor Summary

Constructors

Constructor	Description
Oso(java.lang.String apiKey)	Construct an Oso Cloud client with the provided API key
Oso(java.lang.String apiKey, java.net.URI uri)	Construct an Oso Cloud client with the provided API key and URI
Oso(java.lang.String apiKey, java.net.URI uri, OsoClientOptions options)	Construct an Oso Cloud client with the provided API key, URI, and optional configuration parameters
Oso(java.lang.String apiKey, java.net.URI uri, java.net.URI fallbackUri)	Construct an Oso Cloud client with the provided API key, custom Oso Cloud URI, and fallback URI.
Oso(java.lang.String apiKey, java.net.URI uri, java.net.URI fallbackUri, java.nio.file.Path dataBindingsPath)	Construct an Oso Cloud client with the provided API key, custom Oso Cloud URI, fallback URI, and local authorization data bindings config.

Method Summary

Modifier and Type	Method	Description
java.lang.String[]	actions(Value actor, Value resource)	Get a list of actions an actor is allowed to perform on a resource
java.lang.String[]	actions(Value actor, Value resource, java.util.List<Fact> contextFacts)	Get a list of actions an actor is allowed to perform on a resource
java.lang.String	actionsLocal(Value actor, Value resource)	Fetch a query that can be run against your database to determine the actions an actor can perform on a resource.
java.lang.String	actionsLocal(Value actor, Value resource, java.util.List<Fact> contextFacts)	Fetch a query that can be run against your database to determine the actions an actor can perform on a resource.
java.lang.String	actionsLocal(Value actor, java.lang.String action, Value resource)	Deprecated. Use the two argument version of this method instead.
boolean	authorize(Value actor, java.lang.String action, Value resource)	Check if an actor is allowed to perform an action on a resource
boolean	authorize(Value actor, java.lang.String action, Value resource, ParityHandle parityHandle)	Check if an actor is allowed to perform an action on a resource
boolean	authorize(Value actor, java.lang.String action, Value resource, java.util.List<Fact> contextFacts)	Check if an actor is allowed to perform an action on a resource
boolean	authorize(Value actor, java.lang.String action, Value resource, java.util.List<Fact> contextFacts, ParityHandle parityHandle)	Check if an actor is allowed to perform an action on a resource
java.lang.String	authorizeLocal(Value actor, java.lang.String action, Value resource)	Check if an actor is allowed to perform an action on a resource depending on data both in Oso Cloud and stored in a local database.
java.lang.String	authorizeLocal(Value actor, java.lang.String action, Value resource, ParityHandle parityHandle)	Check if an actor is allowed to perform an action on a resource depending on data both in Oso Cloud and stored in a local database.
java.lang.String	authorizeLocal(Value actor, java.lang.String action, Value resource, java.util.List<Fact> contextFacts)	Check if an actor is allowed to perform an action on a resource depending on data both in Oso Cloud and stored in a local database.
java.lang.String	authorizeLocal(Value actor, java.lang.String action, Value resource, java.util.List<Fact> contextFacts, ParityHandle parityHandle)	Check if an actor is allowed to perform an action on a resource depending on data both in Oso Cloud and stored in a local database.
void	batch(java.util.function.Consumer<BatchTransaction> fn)	Transactionally delete and add facts.
QueryBuilder	buildQuery(java.lang.String predicate, QueryArg... args)	Query for an arbitrary expression.
ParityHandle	createParityHandle()	Creates a new ParityHandle for testing authorization results in the Oso Dev Server Debugger.
void	delete(Fact fact)	Delete a single fact.
void	delete(FactPattern pattern)	Delete facts matching the provided pattern.
Fact[]	get(FactPattern pattern)	Get facts matching the provided pattern.
void	insert(Fact fact)	Insert a single fact.
java.lang.String[]	list(Value actor, java.lang.String action, java.lang.String resourceType)	Get a list of which resources of the provided type an actor is allowed to perform an action on
java.lang.String[]	list(Value actor, java.lang.String action, java.lang.String resourceType, java.util.List<Fact> contextFacts)	Get a list of which resources of the provided type an actor is allowed to perform an action on
java.lang.String	listLocal(Value actor, java.lang.String action, java.lang.String resourceType, java.lang.String column)	Get a list of which resources of the provided type an actor is allowed to perform an action on depending on data both in Oso Cloud and stored in a local database.
java.lang.String	listLocal(Value actor, java.lang.String action, java.lang.String resourceType, java.lang.String column, java.util.List<Fact> contextFacts)	Get a list of which resources of the provided type an actor is allowed to perform an action on depending on data both in Oso Cloud and stored in a local database.
java.lang.String	policy()	Get the Polar policy currently active in Oso Cloud
void	policy(java.lang.String policy)	Set the Polar policy currently active in Oso Cloud
PolicyMetadata	policyMetadata()	Get metadata about the currently active policy.
void	setMaxConnections(int maxConnections)	Set the maximum number of connections the connection pool will use when communicating with Oso Cloud.
Oso.Async	withAsyncExecutor(java.util.concurrent.Executor executor)	Returns a handle to the Async API, which returns CompletableFutures that run on the given executor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Oso

public Oso(java.lang.String apiKey)

Construct an Oso Cloud client with the provided API key

Parameters:

apiKey - The API key to use for authentication

Oso

public Oso(java.lang.String apiKey,
           java.net.URI uri)

Construct an Oso Cloud client with the provided API key and URI

Parameters:

apiKey - The API key to use for authentication

uri - An alternate URI by which to access Oso Cloud. This is useful for testing against the Local Development binary.

Oso

public Oso(java.lang.String apiKey,
           java.net.URI uri,
           java.net.URI fallbackUri)

Construct an Oso Cloud client with the provided API key, custom Oso Cloud URI, and fallback URI.

Parameters:

apiKey - The API key to use for authentication

uri - An alternate URI by which to access Oso Cloud. This is useful for testing against the Local Development binary.

fallbackUri - The URI of your Oso Fallback node

Oso

public Oso(java.lang.String apiKey,
           java.net.URI uri,
           java.net.URI fallbackUri,
           java.nio.file.Path dataBindingsPath)

Construct an Oso Cloud client with the provided API key, custom Oso Cloud URI, fallback URI, and local authorization data bindings config.

Parameters:

apiKey - The API key to use for authentication

uri - An alternate URI by which to access Oso Cloud. This is useful for testing against the Local Development binary.

fallbackUri - The URI of your Oso Fallback node

dataBindingsPath - The path to your data bindings configuration YAML file

Oso

public Oso(java.lang.String apiKey,
           java.net.URI uri,
           OsoClientOptions options)

Construct an Oso Cloud client with the provided API key, URI, and optional configuration parameters

Parameters:

apiKey - The API key to use for authentication

uri - An alternate URI by which to access Oso Cloud. This is useful for testing against the Local Development binary.

options - Additional configuration options for the Oso client

See Also:

to construct an OsoClientOptions instance

Method Detail

setMaxConnections

public void setMaxConnections(int maxConnections)

Set the maximum number of connections the connection pool will use when communicating with Oso Cloud.

Defaults to 20. A higher number will enable more concurrent requests to Oso Cloud, but may consume more resources.

Parameters:

maxConnections - The maximum number of pooled connections to Oso Cloud

policy

public java.lang.String policy()
                        throws java.io.IOException,
                               ApiException

Get the Polar policy currently active in Oso Cloud

Returns:

The Polar policy currently active in Oso Cloud

Throws:

java.io.IOException

ApiException

policyMetadata

public PolicyMetadata policyMetadata()
                              throws java.io.IOException,
                                     ApiException

Get metadata about the currently active policy.

Returns:

Metadata about the currently active policy.

Throws:

java.io.IOException

ApiException

policy

public void policy(java.lang.String policy)
            throws java.io.IOException,
                   ApiException

Set the Polar policy currently active in Oso Cloud

Parameters:

policy - The Polar policy to set

Throws:

java.io.IOException

ApiException

insert

public void insert(Fact fact)
            throws java.io.IOException,
                   ApiException

Insert a single fact.

Parameters:

fact - The fact to insert.

Throws:

java.io.IOException

ApiException

get

public Fact[] get(FactPattern pattern)
           throws java.io.IOException,
                  ApiException

Get facts matching the provided pattern.

Use ValueOfType or ValuePattern.ANY in the arguments list to represent wildcards.

Parameters:

pattern - The fact pattern to match.

Returns:

An array of facts matching the provided pattern.

Throws:

java.io.IOException

ApiException

delete

public void delete(Fact fact)
            throws java.io.IOException,
                   ApiException

Delete a single fact. Does not throw an exception if a matching fact does not exist.

Parameters:

fact - The fact to delete.

Throws:

java.io.IOException

ApiException

delete

public void delete(FactPattern pattern)
            throws java.io.IOException,
                   ApiException

Delete facts matching the provided pattern. Does not throw an exception if a matching fact does not exist.

Use ValueOfType or ValuePattern.ANY in the arguments list to represent wildcards.

Parameters:

pattern - The fact pattern to match for deletion.

Throws:

java.io.IOException

ApiException

batch

public void batch(java.util.function.Consumer<BatchTransaction> fn)
           throws java.io.IOException,
                  ApiException

Transactionally delete and add facts.

Allows deleting and inserting many facts in one atomic transaction. Deletions and insertions are run in the order they appear in the closure.

Use ValueOfType or ValuePattern.ANY in the arguments list passed to BatchTransaction.delete(FactPattern) to represent wildcards.

Parameters:

fn - The function which runs the inserts and deletes via the provided BatchTransaction.

Throws:

java.io.IOException

ApiException

authorize

public boolean authorize(Value actor,
                         java.lang.String action,
                         Value resource,
                         java.util.List<Fact> contextFacts,
                         ParityHandle parityHandle)
                  throws java.io.IOException,
                         ApiException

Check if an actor is allowed to perform an action on a resource

Parameters:

actor - The actor performing the action

action - The action being performed

resource - The resource the action is being performed on

contextFacts - Additional context to consider when making the decision

parityHandle - A handle to indicate the expected decision

Returns:

Whether the actor is allowed to perform the action on the resource

Throws:

java.io.IOException

ApiException

authorize

public boolean authorize(Value actor,
                         java.lang.String action,
                         Value resource,
                         java.util.List<Fact> contextFacts)
                  throws java.io.IOException,
                         ApiException

Check if an actor is allowed to perform an action on a resource

Parameters:

actor - The actor performing the action

action - The action being performed

resource - The resource the action is being performed on

contextFacts - Additional context to consider when making the decision

Returns:

Whether the actor is allowed to perform the action on the resource

Throws:

java.io.IOException

ApiException

authorize

public boolean authorize(Value actor,
                         java.lang.String action,
                         Value resource,
                         ParityHandle parityHandle)
                  throws java.io.IOException,
                         ApiException

Check if an actor is allowed to perform an action on a resource

Parameters:

actor - The actor performing the action

action - The action being performed

resource - The resource the action is being performed on

parityHandle - A handle to indicate the expected decision

Returns:

Whether the actor is allowed to perform the action on the resource

Throws:

java.io.IOException

ApiException

authorize

public boolean authorize(Value actor,
                         java.lang.String action,
                         Value resource)
                  throws java.io.IOException,
                         ApiException

Check if an actor is allowed to perform an action on a resource

Parameters:

actor - The actor performing the action

action - The action being performed

resource - The resource the action is being performed on

Returns:

Whether the actor is allowed to perform the action on the resource

Throws:

java.io.IOException

ApiException

list

public java.lang.String[] list(Value actor,
                               java.lang.String action,
                               java.lang.String resourceType,
                               java.util.List<Fact> contextFacts)
                        throws java.io.IOException,
                               ApiException

Get a list of which resources of the provided type an actor is allowed to perform an action on

Parameters:

actor - The actor performing the action

action - The action being performed

resourceType - The type of resource to list

contextFacts - Additional context to consider when making the decisions

Returns:

The resources of the provided type on which the actor is allowed to perform the action

Throws:

java.io.IOException

ApiException

list

public java.lang.String[] list(Value actor,
                               java.lang.String action,
                               java.lang.String resourceType)
                        throws java.io.IOException,
                               ApiException

Get a list of which resources of the provided type an actor is allowed to perform an action on

Parameters:

actor - The actor performing the action

action - The action being performed

resourceType - The type of resource to list

Returns:

The resources of the provided type on which the actor is allowed to perform the action

Throws:

java.io.IOException

ApiException

actions

public java.lang.String[] actions(Value actor,
                                  Value resource,
                                  java.util.List<Fact> contextFacts)
                           throws java.io.IOException,
                                  ApiException

Get a list of actions an actor is allowed to perform on a resource

Parameters:

actor - The actor performing the action

resource - The resource the action is being performed on

contextFacts - Additional context to consider when making the decisions

Returns:

The actions the actor is allowed to perform on the resource

Throws:

java.io.IOException

ApiException

actions

public java.lang.String[] actions(Value actor,
                                  Value resource)
                           throws java.io.IOException,
                                  ApiException

Get a list of actions an actor is allowed to perform on a resource

Parameters:

actor - The actor performing the action

resource - The resource the action is being performed on

Returns:

The actions the actor is allowed to perform on the resource

Throws:

java.io.IOException

ApiException

authorizeLocal

public java.lang.String authorizeLocal(Value actor,
                                       java.lang.String action,
                                       Value resource,
                                       java.util.List<Fact> contextFacts,
                                       ParityHandle parityHandle)
                                throws java.io.IOException,
                                       ApiException

Check if an actor is allowed to perform an action on a resource depending on data both in Oso Cloud and stored in a local database.

Parameters:

actor - The actor performing the action

action - The action being performed

resource - The resource the action is being performed on

contextFacts - Additional context to consider when making the decisions

parityHandle - A handle to indicate the expected decision

Returns:

A SQL query to run against the local database

Throws:

java.io.IOException

ApiException

authorizeLocal

public java.lang.String authorizeLocal(Value actor,
                                       java.lang.String action,
                                       Value resource,
                                       java.util.List<Fact> contextFacts)
                                throws java.io.IOException,
                                       ApiException

Check if an actor is allowed to perform an action on a resource depending on data both in Oso Cloud and stored in a local database.

Parameters:

actor - The actor performing the action

action - The action being performed

resource - The resource the action is being performed on

contextFacts - Additional context to consider when making the decisions

Returns:

A SQL query to run against the local database

Throws:

java.io.IOException

ApiException

authorizeLocal

public java.lang.String authorizeLocal(Value actor,
                                       java.lang.String action,
                                       Value resource,
                                       ParityHandle parityHandle)
                                throws java.io.IOException,
                                       ApiException

Check if an actor is allowed to perform an action on a resource depending on data both in Oso Cloud and stored in a local database.

Parameters:

actor - The actor performing the action

action - The action being performed

resource - The resource the action is being performed on

parityHandle - A handle to indicate the expected decision

Returns:

A SQL query to run against the local database

Throws:

java.io.IOException

ApiException

authorizeLocal

public java.lang.String authorizeLocal(Value actor,
                                       java.lang.String action,
                                       Value resource)
                                throws java.io.IOException,
                                       ApiException

Check if an actor is allowed to perform an action on a resource depending on data both in Oso Cloud and stored in a local database.

Parameters:

actor - The actor performing the action

action - The action being performed

resource - The resource the action is being performed on

Returns:

A SQL query to run against the local database

Throws:

java.io.IOException

ApiException

listLocal

public java.lang.String listLocal(Value actor,
                                  java.lang.String action,
                                  java.lang.String resourceType,
                                  java.lang.String column)
                           throws java.io.IOException,
                                  ApiException

Get a list of which resources of the provided type an actor is allowed to perform an action on depending on data both in Oso Cloud and stored in a local database.

Parameters:

actor - The actor performing the action

action - The action being performed

resourceType - The type of resource to list

column - The name of the column that contains the resource ID

Returns:

A SQL query to run against the local database

Throws:

java.io.IOException

ApiException

listLocal

public java.lang.String listLocal(Value actor,
                                  java.lang.String action,
                                  java.lang.String resourceType,
                                  java.lang.String column,
                                  java.util.List<Fact> contextFacts)
                           throws java.io.IOException,
                                  ApiException

Get a list of which resources of the provided type an actor is allowed to perform an action on depending on data both in Oso Cloud and stored in a local database.

Parameters:

actor - The actor performing the action

action - The action being performed

resourceType - The type of resource to list

column - The name of the column that contains the resource ID

contextFacts - Additional context to consider when making the decisions

Returns:

A SQL query to run against the local database

Throws:

java.io.IOException

ApiException

actionsLocal

@Deprecated
public java.lang.String actionsLocal(Value actor,
                                     java.lang.String action,
                                     Value resource)
                              throws java.io.IOException,
                                     ApiException

Deprecated.

Use the two argument version of this method instead.

Throws:

java.io.IOException

ApiException

actionsLocal

public java.lang.String actionsLocal(Value actor,
                                     Value resource)
                              throws java.io.IOException,
                                     ApiException

Fetch a query that can be run against your database to determine the actions an actor can perform on a resource.

Parameters:

actor - The actor performing the action

resource - The resource the action is being performed on

Returns:

A SQL query to run against the local database

Throws:

java.io.IOException

ApiException

actionsLocal

public java.lang.String actionsLocal(Value actor,
                                     Value resource,
                                     java.util.List<Fact> contextFacts)
                              throws java.io.IOException,
                                     ApiException

Fetch a query that can be run against your database to determine the actions an actor can perform on a resource.

Parameters:

actor - The actor performing the action

resource - The resource the action is being performed on

contextFacts - Additional context to consider when making the decisions

Returns:

A SQL query to run against the local database

Throws:

java.io.IOException

ApiException

buildQuery

public QueryBuilder buildQuery(java.lang.String predicate,
                               QueryArg... args)

Query for an arbitrary expression.

Parameters:

predicate - The predicate of the query

args - The arguments to the predicate, which can be: - Concrete values created with Value constructors - Variables created with TypedVar constructor

Returns:

A QueryBuilder for chaining additional constraints

Example: TypedVar actor = new TypedVar("actor"); QueryBuilder builder = oso.buildQuery( "has_permission", actor, // Variable binding new Value("read"), // Concrete string new Value("Repository", "oso") // Concrete Value ); // The builder can now be used to add constraints or execute the query.

createParityHandle

public ParityHandle createParityHandle()

Creates a new ParityHandle for testing authorization results in the Oso Dev Server Debugger.

Returns:

A new ParityHandle

withAsyncExecutor

public Oso.Async withAsyncExecutor(java.util.concurrent.Executor executor)

Returns a handle to the Async API, which returns CompletableFutures that run on the given executor.

Useful for interoperation with Kotlin coroutines- eg in Kotlin, `oso.withAsyncExecutor(Dispatchers.IO.asExecutor()).authorize(...).await()`

Cancelling the CompletableFutures returned by the Async API will also cancel the underlying HTTP request.

Parameters:

executor - Executor the executor to run requests on- eg `Executors.newSingleThreadExecutor()` to run the Async API in a new thread

Returns:

Async