okta

package
v1.86.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 23, 2026 License: BSD-3-Clause Imports: 20 Imported by: 0

README

Okta Adapter

Entity External IDs

The Entity External ID maps to an Okta API resource path. The adapter constructs URLs as:

{baseURL}/api/v1/{resource}?limit={pageSize}
Entity External ID API Path Unique ID Attribute Description
User /api/v1/users id Okta users
Group /api/v1/groups id Okta groups
GroupMember /api/v1/groups/{groupID}/users id Group members (child of Group)
Application /api/v1/apps id Okta applications

Parent-Child Relationships

  • GroupMember is a child of Group - the adapter iterates through groups and fetches members per group.

Filter and Search Support

Entity Filter Search Default Filter
User Yes Yes (mutually exclusive with filter) None
Group Yes Yes (mutually exclusive with filter) type eq "OKTA_GROUP" or type eq "APP_GROUP"
GroupMember No No None
Application Yes No None

Notes

  • Group has a default filter applied when neither filter nor search is configured.
  • Pagination uses Link header-based cursors (Okta's standard pagination).

Adding New Entity External IDs

Requires code changes. The adapter validates against ValidEntityExternalIDs and uses a switch statement in endpoint.go to construct entity-specific URL paths.

To add a new entity:

  1. Add a constant in datasource.go (e.g., Role string = "Role").
  2. Add the entity to ValidEntityExternalIDs.
  3. Add a case in the switch statement in ConstructEndpoint in endpoint.go with the Okta API path.
  4. If the entity supports filter or search, add handling in the endpoint construction.
  5. If it's a child entity (like GroupMember), implement collection-based pagination with a parent reference.
  6. Add tests.

Documentation

Index

Constants

View Source
const (
	Users        string = "User"
	Groups       string = "Group"
	GroupMembers string = "GroupMember"
	Applications string = "Application"
)

Variables

View Source
var (
	// ValidEntityExternalIDs is a set of valid external IDs of entities that can be queried.
	ValidEntityExternalIDs = map[string]struct{}{
		Users:        {},
		Groups:       {},
		GroupMembers: {},
		Applications: {},
	}
)

Functions

func ConstructEndpoint

func ConstructEndpoint(request *Request) (string, *framework.Error)

ConstructEndpoint constructs and returns the endpoint to query the datasource.

func NewAdapter

func NewAdapter(client Client) framework.Adapter[Config]

NewAdapter instantiates a new Adapter.

func ParseResponse

func ParseResponse(body []byte) (objects []map[string]any, err *framework.Error)

Types

type Adapter

type Adapter struct {
	OktaClient Client
}

Adapter implements the framework.Adapter interface to query pages of objects from datasources.

func (*Adapter) GetPage

func (a *Adapter) GetPage(ctx context.Context, request *framework.Request[Config]) framework.Response

GetPage is called by SGNL's ingestion service to query a page of objects from a datasource.

func (*Adapter) RequestPageFromDatasource

func (a *Adapter) RequestPageFromDatasource(
	ctx context.Context, request *framework.Request[Config],
) framework.Response

RequestPageFromDatasource requests a page of objects from a datasource.

func (*Adapter) ValidateGetPageRequest

func (a *Adapter) ValidateGetPageRequest(ctx context.Context, request *framework.Request[Config]) *framework.Error

ValidateGetPageRequest validates the fields of the GetPage Request.

type Client

type Client interface {
	GetPage(ctx context.Context, request *Request) (*Response, *framework.Error)
}

Client is a client that allows querying the Okta datasource which contains JSON objects.

func NewClient

func NewClient(client *http.Client) Client

NewClient returns a Client to query the datasource.

type Config

type Config struct {
	*config.CommonConfig

	APIVersion string            `json:"apiVersion,omitempty"`
	Filters    map[string]string `json:"filters,omitempty"`
	Search     map[string]string `json:"search,omitempty"`
}

Config is the configuration passed in each GetPage calls to the adapter. Adapter configuration example: nolint: godot

{
    "requestTimeoutSeconds": 10,
    "localTimeZoneOffset": 43200,
    "apiVersion": "v1",
    "filters": {
        "User": "status eq \"ACTIVE\"",
        "Group": "type eq \"OKTA_GROUP\"",
        "Application": "status eq \"ACTIVE\""
    },
	"search": {
        "User": "profile.department eq \"Engineering\""
    }
}

func (*Config) Validate

func (c *Config) Validate(_ context.Context) error

ValidateConfig validates that a Config received in a GetPage call is valid.

type Datasource

type Datasource struct {
	Client *http.Client
}

Datasource directly implements a Client interface to allow querying an external datasource.

func (*Datasource) GetPage

func (d *Datasource) GetPage(ctx context.Context, request *Request) (*Response, *framework.Error)

type DatasourceResponse

type DatasourceResponse = []map[string]any

type Request

type Request struct {
	// BaseURL is the Base URL of the datasource to query.
	BaseURL string

	// Token is the API token to authenticate a request. Okta supports both API tokens and OAuth2 Client Credential
	// auth, so this may either be in the form "SSWS XXXX" (for API tokens) or "Bearer eyJhbG[...]1LQ" (for OAuth2).
	Token string

	// PageSize is the maximum number of objects to return from the entity.
	PageSize int64

	// EntityExternalID is the external ID of the entity.
	// The external ID should match the API's resource name.
	EntityExternalID string

	// Cursor identifies the first object of the page to return, as returned by
	// the last request for the entity.
	// nil in the request for the first page.
	Cursor *pagination.CompositeCursor[string]

	// APIVersion the API version to use.
	APIVersion string

	// Filter is the Okta Filter syntax to apply to requests for Users, Groups, and/or Applications
	Filter string

	// Search is the Okta Search syntax to apply to requests for Users and/or Groups
	Search string

	// RequestTimeoutSeconds is the timeout duration for requests made to datasources.
	// This should be set to the number of seconds to wait before timing out.
	RequestTimeoutSeconds int
}

Request is a request to Okta.

type Response

type Response struct {
	// StatusCode is an HTTP status code.
	StatusCode int

	// RetryAfterHeader is the Retry-After response HTTP header, if set.
	RetryAfterHeader string

	// Objects is the list of
	// May be empty.
	Objects []map[string]any

	// NextCursor is the cursor that identifies the first object of the next page.
	// nil if this is the last page in this full sync.
	NextCursor *pagination.CompositeCursor[string]
}

Response is a response returned by the datasource.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL