Platform Overview
Beyond Identity uses the Beyond Identity Cloud and Beyond Identity Authenticators to establish user identity and authorization.
The Cloud hosts user directories, authentication servers, event logs, and policy rules, while Authenticators are endpoint components embedded in applications that work with the Cloud to authenticate users and authorize actions based on configured policies.
Tenant​
A Beyond Identity tenant represents an organization in the Beyond Identity Cloud. It serves as the root container for all other cloud components in your configuration. Your tenant has a unique identifier, a modifiable name, and contains one or more realms that make up the organization.
If you log into the Admin Console from another device or browser, you'll need your Tenant ID, email address used to sign up, and the console link to your region.
Realm​
When your tenant is deployed, the Beyond Identity Admin Realm gets created and populated for you. It's home for your Beyond Identity Console application and Beyond Identity Management API. In addition, it's populated with your initial Admin identity and credential, Console Authorization Policy, Console application configuration, and API configuration.
While you can only have one tenant per account, a tenant can have many realms and one Beyond Identity Admin Realm. A realm contains multiple applications, and an application utilizes the realm's directory (identity and groups), policy, events, and branding objects.
Some tenants will only need the use of a single realm, in this case a realm and a tenant may seem synonymous. It's possible that you never need to create another realm for your use case. Some of the common use cases for realms include:
A need for multiple development environments - staging, QA, production - an admin could create a realm for each,
The desire to provide separated services based on different administrative domains (holding company delegating realms to its various companies, company delegating realms to its various brands, etc), and
The desire to separate Admin Console and API identities, credentials and policies from those for an end-user application.
When a new realm is created, the SCIM server is available by default and a separate SCIM server is available for each realm. However, to use any SCIM functionality, an access token with scim:all scope is required. See SCIM server setup for more details.
Event​
Events are an immutable record of all transactions carried out by an end user or an administrator that occur in a Realm. Events may be used for auditing, debugging or understanding the system.
Events can be exported to a number of SIEM products or viewed within your Console.
In console, the events table presents a chronologically sorted view of all events that have occurred in the currently selected realm of the current tenant. The events are persisted for 90 days.
Principal Actor​
Principal actor is the entity whose action caused the event to be recorded.
There are three types of actors:
- Identity - this type of actor represents the end user
- Application - this actor is used in case that a token minted using client_id + client_secret has been used to authorize an operation
- Anonymous - used when there’s no actor information available. For example, at the very beginning of the login process, we don’t know who the user is yet, so there’s no way to supply an actor.
Correlation ID​
Unique identifier that links together events that are part of a single flow.
Outcome​
Outcome is a short, machine-readable description of the result of the operation that the event represents. By convention, outcome is formatted as an UPPERCASE string.
Outcome is especially important for events that represent an attempt to perform an operation rather than the fact that an operation has been performed.
Each event type has a different set of possible outcomes. Some event types don’t use an outcome because they are expressive enough by themselves.
Policy​
A Realm Policy is a collection of rules that determine how to treat any given transaction managed by the Beyond Identity Cloud. Policy rules can be thought of as match action pairs. Where the match could be a complex predicate describing which transactions it governs and the action states how to handle the matching transactions.
Each registration (credential binding) and authentication operation consults the Realm’s Policy for an Allow or Deny decision before completion. A Deny decision results in rejection of the operation.
Directory​
A Directory contains the Identities, associated Credentials and Groups within a Realm. Directories are not shared across Realms.
Beyond Identity offers a SCIM 2.0 compliant server for standardized approach to managing Users and Groups. It uses common REST API endpoints to create, update, and delete these entities. An access token with scim:all scope is required to use any SCIM functionality. For more details, see SCIM server setup.
How does SCIM work with Beyond Identity?
The System for Cross-domain Identity Management (SCIM) is a protocol and schema that simplifies identity management in multi-domain scenarios. SCIM makes user data more secure and simplifies the user experience by automating the user identity lifecycle management process. With SCIM, user identities can be created in external systems, such as OKTA or Active directory. As SCIM is a standard, directory data (users and groups they belong to), can be stored consistently and communicated via SCIM to different applications.
SCIM is a REST and JSON-based protocol that defines a client and server role. A client is usually an identity provider (IDP), like Okta, that contains a robust directory of user identities. A service provider (SP) like Beyond Identity needs a subset of information from those identities. When changes to identities are made in the IdP, including create, update, and delete, they are automatically synced to the SP according to the SCIM protocol. The IdP can also read identities from the SP to add to its directory and to detect incorrect values in the SP that could create security vulnerabilities.
Beyond Identity’s (BI) SCIM server implementation follows the tenant/realm paradigm, where a separate SCIM server is available for each realm. The SCIM user resource is equivalent to a BI identity object. When the SCIM client creates a user, the BI SCIM service will create an identity. The SCIM group resource maps to BI’s group. The BI SCIM configuration can be inspected via standard SCIM discovery endpoints.
Identity​
An identity is a unique identifier that may be used by an end-user to gain access governed by Beyond Identity. An end-user may have multiple identities. A realm can have many identities.
An identity can have one or many credentials, also known as passskeys.
A passkey is a public-private key pair that belongs to an identity. The public key is stored in the Beyond Identity Cloud and the private key never leaves the device. Passkeys are created through binding jobs, in which a binding link is generated to bind a passkey to a specific device or browser. The passkey gets stored in the device hardware root of trust (secure enclave). All cryptographic operations that use the private key are handled by the Beyond Identity SDKs. For more details, see [Univeral Passkeys]((/docs/universal-passkeys).
Group​
A group is a logical collection of identities. A realm can have many groups. An identity can belong to many groups. Groups are commonly used as a predicate in a policy rule. (e.g. Allow group "Beyond Identity Administrators" to access the "Beyond Identity Admin Console" application)
Resource Server​
A resource server is a logical grouping of scopes. Scopes are data elements included in access tokens that enable applications to provide fine grained levels of access control.
There is one built in resource server, the Beyond Identity Management API, located in the Beyond Identity Admin Realm. It is linked to the two built in Beyond Identity Admin apps: the Beyond Identity Management API and the Beyond Identity Admin Console.
In order to use scopes for your application's tokens, you must create at least one resource server in the same realm as the application that requires scopes.
Use these guidelines to determine the Resource Server settings of your application:
| If your application... | Then... |
|---|---|
| References a Resource Server, | The application can include scopes in issued access tokens. The scopes your app can issue are configured in the allowed_scopes setting and must be equal to or a subset of the resource server's available scopes. |
| Doesn't reference a Resource Server | The application can only be used to provide authentication (identity) but not authorization (access). Therefore, the scopes element in access tokens will be empty. |
| Doesn't need to provide multiple access levels, like admin vs. user, | Does not necessarily need a resource server. |
| Is for minting tokens for access to the Beyond Identity API | You must set your application's Resource Server to Beyond Identity Management API. |
Application​
An application in the Beyond Identity Cloud represents an app, such as a Todo-List iOS or AcmeCorp Android app. You'll create applications within a realm to configure your OAuth or OIDC flows. A realm contains multiple applications, and an application utilizes the realm's directory, policy, events, and branding objects.
Applications contain client and token configurations that allows you to configure passkey binding and authentication in your mobile/web apps. Each application is tied to a single authenticator type (Hosted Web or Embedded SDK). You can create an application through the Admin Console or via the Beyond Identity API.
There are two scenarios for your apps:
| Scenario | When to use |
|---|---|
| One application per platform | One admin console application is created per app on each platform your app supports (iOS, Android, Web, etc.). This approach is easier to configure upfront and provides flexibility regarding platform-specific configurability. However, generating passkey binding links across platforms can be more challenging. |
| One application for all platforms | One admin console application is created for your app across all platforms you support. This approach is more difficult to configure upfront because it requires building a web routing layer to redirect passkey binding links appropriately. However, generating passkey binding links across platforms makes it easier to accomplish a more seamless experience. |
Authenticator Config​
An Authenticator Config tells us how and where to invoke passkey creation, and authentication flows for your native/mobile or web application.
Each application is tied to a single Configuration type, which is configured on the app's Authenticator Config tab.
Authenticator configuration types are used for both web and native mobile applications:
| Type | When to use |
|---|---|
| Hosted Web | In this model, Beyond Identity's hosted web app handles passkey registration and authentication for you, including generating new passkeys, presenting users with authenticator choice options as needed, and validating passkey assertions. With this model, your app simply needs to redirect to Beyond Identity's hosted web authenticator, and we do the rest. |
| Embedded SDK | With this model you have more control over the authentication user experience, but your app must do the work of registering and enumerating passkeys for the user, presenting a passkey selection page if required, initiating authentication and verifying passkey assertions. |
| None | If the authenticator configuration type is set to "none", it means that the application uses the client credentials grant type and does not use an authenticator. This configuration is designed to be used for machine to machine authentication |
For more details, see Authenticator Types.
API Token​
All Beyond Identity API endpoints require an access token for authentication. The access token is generated through OAuth 2.0 or OIDC, using either the Authorization Code or Client Credentials flow.
The Beyond Identity Management API application created during developer setup only supports the Client Credentials flow. However, if you want to use the Authorization Code flow instead, create another application referencing the Beyond Identity Management API Resource Server in the Beyond Identity Admin realm. Then, set the application's grant type to Authorization Code.
The access tokens are JWTs with two types of token formats available:
self-contained tokens as JWS (default token format)
referential tokens as JWE
You can create an API access token using the Beyond Identity Admin Console or the Beyond Identity APIs. You'll generate the access token with your Beyond Identity Management API application to authorize access to any Beyond Identity APIs. The Beyond Identity Management API application is provided by default upon tenant creation and resides within the Beyond Identity Admin Realm.
For API requests, you must provide the access token in the Authorization header, as shown in the following example:
curl <https://api-us.beyondidentity.com/v1/>... \\\\
-X $HTTP_METHOD -H "Authorization: Bearer $TOKEN"
API access tokens are valid for three months (TTL 7776000 seconds). You can restrict the token's access with scopes by selecting a list in the Beyond Identity Admin Console or specifying a space-separated string of scopes in your API request, following RFC6749#3.3. You can also configure token expiration from your Beyond Identity Management API application.
Admin Console​
The Beyond Identity Admin Console provides you with a UI for administering your tenant. The Console utilizes your Beyond Identity Admin Realm and Console application configuration to authenticate and authorize admin logins. In addition, an initial Policy gets created in the Beyond Identity Admin Realm on the deployment of your tenant.
When the tenant gets deployed, the Beyond Identity Admin Console gets created as a managed object under Beyond Identity Admin > Apps. As a managed object, it is not editable through the Console.
You'll access the Admin Console at any time using your selected region:
https://console-{REGION}.beyondidentity.com
The Admin Console Access User Group is created, and the identity established at sign-up is added. Adding users to the group will allow them to log into the Console as Administrators of your tenant utilizing any credentials established within the Admin Realm.
It's possible to lock yourself out of the Console with this policy and group control access.