Skip to main content
Version: v2

Add new app

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:

ScenarioWhen to use
One application per platformOne 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 platformsOne 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.

Prerequisites

You'll need to have a developer account, which comes with the Beyond Identity Admin Realm and Beyond Identity Management API app.

Admin Console

An application can be created from the Beyond Identity Admin Console.

tip

Most of the time you will want to create a new application in a different realm other than your Beyond Identity Admin Realm. Applications created in the Beyond Identity Admin Realm default to the Client Credentials grant which is used for applications requesting access outside of the context of a user. Applications created in another realm default to the Authorization Code grant which is used by users requesting access. If you need guidance, visit Create a realm.

  1. From the Admin Console, under Authentication, select Apps > Add new app.

    Admin Console Apps Add new app

  2. Give your application a name.

    Admin Console Add a new application window

External Protocol Tab

Configure your application's basic settings.

After saving, the values entered will be used to generate OIDC configuration endpoints for your application as well as your Client ID and Client Secret.

The application's External Protocol settings determine how tokens should be requested, what tokens issued for the app look like, and how they should be validated.

Client Configuration

SettingImpact
ProtocolDetermines which protocol flow the app must use to request tokens:
  • OAuth2: With the OAuth2 protocol, you can use either the client credentials grant type or the authorization code grant type.
  • OIDC: With the OIDC protocol, you must use the authorization code grant type. With OIDC, you can obtain an id_token as well as an access_token.
For help determining which to select, see API Token Request Scenarios
Client Type
  • Confidential: Confidential clients are applications that are able to keep their registered client credentials (such as a client secret) safe. Think of an application with a backend. The client credentials can then be used to authenticate calls to the token APIs.
  • Public: Public clients, such as applications running in a browser or on a mobile device, are unable to protect registered client secrets and are not issued client credentials.
PKCE
  • If the app's PKCE setting is S256, the app will need to create and send the PKCE parameters (code_challenge, code_challenge_method, and code_verifier) in token requests as described in this Create an access token example
  • If PKCE is set to Disabled, you do not need to send the PKCE parameters (code_challenge, code_challenge_method, and code_verifier) in your token requests. However, authorization code grant with PKCE is the recommended flow for token requests and is required for public clients.
Redirect URIsA list of valid URIs to redirect the resource owner's user-agent to after completing its interaction with the authorization server. See Section 3.1.2 for more information.
Token Endpoint Auth Method
  • Client Secret Basic: The client uses HTTP Basic as defined in OAuth 2.0, Section 2.3.1. The client ID and client secret are sent in the Basic Authorization header.
  • Client Secret Post: The client uses the HTTP POST parameters as defined in OAuth 2.0, Section 2.3.1. The client ID and client secret are sent in the body of the POST request.
Grant Type
  • Authorization Code: The authorization code grant type defined in OAuth 2.0, Section 4.1. Namely, the client may authorize to the token endpoint with a grant code which it obtains via the authorize endpoint.
  • Client Credentials: The client credentials grant type defined in OAuth 2.0, Section 4.4. Namely, the client may authorize to the token endpoint with a client credentials tuple of client_id and client_secret. If you select Client Credentials, the application cannot have an associated authenticator configuration.
Resource ServerIf the app is linked to a resource server, the resource server determines the scopes the app can be allowed to issue.
Token FormatThe two options for token format are Self-Contained and Referential. The difference between these two options impacts how the tokens will be validated. Self-Contained tokens can be validated offline because they contain all of the validation information. Referential tokens require a call to the introspection endpoint for validation.

Token Configuration

SettingImpact
Allowed ScopesIf the app is configured with a Resource Server, then this setting specifies the scopes allowed to be included in tokens for this application. The allowed scopes can match or be a subset of the Resource Server scopes
ExpiresToken lifetime in seconds
SubjectProperty of a principal which is used to fill the subject of a token issued for this application.
Token Signing AlgorithmSigning algorithm to use for an application token. The only allowable value at present is RS256.

Refresh Token Configuration

SettingImpact
Enable Refresh TokensWhen enabled, the token response JSON object will contain an additional field called refresh_token, similar to RFC6749#4.1.4.

Authenticator Config Tab

Select the authenticator configuration type.

Select the Hosted Web option if you want Beyond Identity to do the heavy lifting. This option requires less configuration and code because Beyond Identity handles the end-user authentication via a redirect.


Hosted Web Authenticator comes preconfigured with the following values:

  • Invocation Type: automatic
  • Invoke URL: https://auth-{REGION}.beyondidentity.com/authenticator/
  • Trusted Origin: [https://auth-{REGION}.beyondidentity.com/authenticator/]
  • Authentication Profile: The Authentication Profile allows you to customize the authentication flow for new or returning users.

    Email verification for sign-up and new browser login

    This configuration allows you to customize the authentication flow for user registration. This includes users who are registering for the first time or for the first time on a new browser, which includes browsers on the same device or a different device.

    Currently the following authentication factors are supported and more are coming soon:

    • One-time password

      Verify email with OTP when an end user signs up or logs in on a new browser.


    Authentication method for returning login

    This configuration allows you to customize the authentication flow for user login.

    Currently, the following authentication factors are supported and more are coming soon:

    • Hardware-bound passkey (Recommended)

      This option generates a hardware key within your device's trusted execution environment (TEE).

      Hardware-bound passkeys support biometric step-up during authentication. Available on Chrome and Edge.

      Select fallback method for when a browser isn’t supported:

      • Software-bound passkey (Recommended)

        Use software-bound passkey when a browser doesn’t support hardware-bound passkey.

      • One-time password

        Use OTP when a browser doesn’t support hardware-bound passkey.

    • Software-bound passkey

      This option generates a passkey securely created within the browser's context.

      Software-bound passkeys do not support biometric step-up during authentication.

    • One-time password

      Authenticate with OTP when an end user returns to log in on a browser previously used.

Click Submit. You'll be taken to the app page for the new application. Here, you'll be able to a number of things, such as edit the basic and advanced settings or configure the signup/login experience.

API

Before creating an application by API, you must have an API access token. You'll also need to create a Resource Server and an Authenticator Config, which you'll do below. A Resource Server is a namespace for application scopes that are a set of all scopes supported by the application. An Authenticator Config defines the invocation type, invoke URL, and trusted origins.

  1. Create a Resource Server. A Resource Server is a namespace for application scopes that are a set of all scopes supported by the application.

    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 ServerThe 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 APIYou must set your application's Resource Server to Beyond Identity Management API.
    /resource-servers
    1
    2
    3
    4
    5
    curl "https://api-$(REGION).beyondidentity.com/v1/tenants/$(TENANT_ID)/realms/$(REALM_ID)/resource-servers" \
    -X POST \
    -H "Authorization: Bearer $(TOKEN)" \
    -H "Content-Type: application/json" \
    -d "{\"resource_server\":{\"display_name\":\"$(APPLICATION_DISPLAY_NAME)\",\"identifier\":\"$(APPLICATION_URI)\",\"scopes\":[\"$(SCOPE)\"]}}"
  2. Create an Authenticator Config and make a note of the Authenticator Config ID.

    Follow these guidelines to determine if your use case requires the Authenticator Config ID for creating your application:

    ProtocolGrant TypeRequired?
    OAuthClient CredentialsNo
    OAuthAuthorization CodeYes

    You'll set the application's Configuration Type, Invocation Type, Invoke URL, and Trusted Origins.

    /authenticator-config
    1
    2
    3
    4
    5
    curl "https://api-$(REGION).beyondidentity.com/v1/tenants/$(TENANT_ID)/realms/$(REALM_ID)/authenticator-config" \
    -X POST \
    -H "Authorization: Bearer $(TOKEN)" \
    -H "Content-Type: application/json" \
    -d "{\"authenticator_config\":{\"config\":{\"type\":\"$(CONFIGURATION_TYPE)\",\"invoke_url\":\"$(INVOKE_URL)\",\"trusted_origins\":[\"$(TRUSTED_ORIGIN)\"],\"invocation_type\":\"$(INVOCATION_TYPE)\"}}}"
  3. Create an application using at least the Authenticator Config ID, specifically if your application's grant_type is set to authorization_code. The Resource Server ID is optional.

    You'll set the application's Display Name, Client Type (confidentiality), Token Configuration, and one ore more redirect URIs.

    There are two options available for confidentiality:

    OptionWhat to do
    confidentialset the token_endpoint_auth_method to one of the following:
    • client_secret_post
    • client_secret_basic
    publicset the token_endpoint_auth_method to none
    /applications
    1
    2
    3
    4
    5
    curl "https://api-$(REGION).beyondidentity.com/v1/tenants/$(TENANT_ID)/realms/$(REALM_ID)/applications" \
    -X POST \
    -H "Authorization: Bearer $(TOKEN)" \
    -H "Content-Type: application/json" \
    -d "{\"application\":{\"display_name\":\"$(DISPLAY_NAME)\",\"resource_server_id\":\"$(RESOURCE_SERVER_ID)\",\"authenticator_config_id\":\"$(AUTHENTICATOR_CONFIG_ID)\",\"protocol_config\":{\"type\":\"oidc\",\"allowed_scopes\": [\"$(SCOPE)\"],\"confidentiality\": \"$(CLIENT_TYPE)\",\"token_endpoint_auth_method\":\"$(TOKEN_ENDPOINT_AUTH_METHOD)\",\"grant_type\": [\"authorization_code\"],\"redirect_uris\": [\"$(REDIRECT_URI)\"],\"token_configuration\":{\"subject_field\":\"$(TOKEN_SUBJECT_FIELD)\",\"expires_after\":86400,\"token_signing_algorithm\":\"RS256\"},\"pkce\":\"s256\", \"token_format\": \"self_contained\"}}}"

    Token configuration, such as expiration and default allowed scopes, can be modified either through the Beyond Identity Admin Console or through API on application update.

What can you do next?