Skip to main content

Concepts

📄️ Service

A Katanemo Service is a representation of the API surface area that developers want to enrich with enterprise-readiness capabilities (authentication, authorization, auditing - 3xA). Services are created using the familiar OpenAPI standard. OpenAPI neatly captures RESTful API definitions, resource schemas and establishes a great foundation for authorization and auditing. With familiar RESTful semantics developers (and customers) don’t need to learn a new policy language, and get to enrich their API experience with rich 3xA capabilities without having to build and scale complex authorization and auditing engines

📄️ Organizations

An organization is a container for SaaS customers to organize roles, manage users, machine (API) keys, SSO settings, and pull audit logs. An organization is created when a SaaS customer signs up to a SaaS application managed by Katanemo. Organizations also act as a thin wrapper to facilitate critical interactions between SaaS developers and SaaS customers. Developers can use Organizations in Katanemo to get detailed information about their customers and to set meta-data like subscription tiers, enabled/disable features, support prompts etc.

📄️ Roles

Roles establish a permission boundary that enables access to select API operations of a SaaS application. You don’t need to learn a new policy language to create Roles. Simply associate a list of OpenAPI-based operations (API paths and HTTP methods) with a Role, and assign Roles to Users or API Keys to enforce a strict authorization boundary. For example, the below UI shows how an API subscriber can define a Role for a set of API operations of an SaaS EHR application. Once the Role gets assigned to a User or an API Key, those principals are then limited to only those API operations associated with the Role. For instance the “Intern” Role below can only conduct the following API operations.

📄️ Resource Access (via Tags)

Tags consist of a key and value pair, and are part of a resource’s meta-data. Tags are used to ensure that API resources that belong to a set of principals are only accessible by those principals. Tags and Roles complement each other to create a powerful, yet simple authorization strategy. Roles capture what API operations can be performed by a principal, and Tags capture which resources are accessible to a set of principals. SaaS developers store Tags for resources created by their customers, and customers attach Tags to authorization principals to be used in authorization.

📄️ Connections

Katanemo enables customers to invite and manage Users via the CIAM console. But enterprise customers will demand that they federate users via an existing Identity provider (Idp) . Katanemo supports Single sign-on (SSO) for OIDC and SAML compliant Identity providers like Okta, Ping, Auth0 via Connections. An enterprise IT administrator simply creates a Connection to their preferred Idp, and Katanemo uses the upstream Idp to initiate login and manages the token lifecycle before returning an authorization code to the application via its configured redirect_uri. For more details, read How to Configure a New OIDC connection?

📄️ Scopes (OAuth 2.0)

Katanemo makes working with OAuth2.0 scopes simple. As an developer you simply define “service-defined” Roles in your OpenAPI spec via Katanemo extensions. A “service-defined” Role is a unique name mapped to a set of OpenAPI operations (resource paths and HTTP methods). Your customers use "service-defined” role names when assigning permissions to users or machine principals, or when initiating an OAuth2.0 flow via the Katanemo /oauth/authorize endpoint. Katanemo’s evaluation engine maps OAuth2.0 claims received in the JWT to “service-defined” Roles via the claim name, and performs appropriate authorization checks when a user or 3rd party applications tries to access a resource or perform an API operation. Note, service-defined Roles can’t be modified by customers.