Skip to main content
Version: v1

Applications

Last updated on

Prerequisites​

Application Overview​

An application is an abstraction in the admin console that enables you to configure passkey binding and authentication in your mobile/web apps. An application contains client configuration, token configuration, and an Authenticator Config. There are two ways to create an admin console application for your apps:

  • One application per platform: In this scenario, there is one admin console application created per app on each platform your app supports (iOS, Android, Web, etc). This is easier to configure upfront and provides flexibility in regards to platform specific configurability. However, it is more difficult to configure the generation of passkey binding links across platforms.

  • One application for all platforms: In this scenario, there is one admin console application created for your app across all platforms you support. This is more difficult to configure upfront as it required building a web routing layer to redirect passkey binding links appropriately, however it makes it easier to accomplish a more seamless experience when generating passkey binding links across platforms.

A realm contains multiple applications, and an application utilizes the realm's directory, policy, events, and branding objects. To see how an application fits in the wider Beyond Identity architecture, check out Architecture.

Create Application from Admin Console​

An application can be created from the Beyond Identity Admin Console. Navigate to your application's realm and from the navigation bar, click Apps, then click Add app. Configure both the External Protocol tab as well as the Authenticator Config tab.

External Protocol​

From the External Protocol tab, configure your application's OAuth 2.0 and OIDC values such as the Client Type, PKCE, Token Endpoint Auth Method, token minting configurations, and a redirect URI back to your application. After saving, the values entered will be used to generate OpenID Connect well-known configuration endpoints for your application as well as your Client ID and Client Secret.

Which Client Type should I use?

Confidential clients are applications that are able to securely authenticate with the authorization server, for example being able to keep their registered client secret safe. Think of an application with a backend.

Public clients are unable to use registered client secrets, such as applications running in a browser or on a mobile device. You will not receive an application "Client Secret" if you create this type of application.

Authenticator Config​

From the Authenticator Config tab, select a Configuration Type. This setting determines if your application is using an Embedded SDKs or the hosted Web Authenticator to generate and manage passkeys.

For more information on the Authenticator Config, visit the Authenticator Config guide.

Which Configuration Type should I use?

Embedded SDK, select this if your application is using either a native SDK (iOS, Android, Flutter, React Native) or web SDK (JS). When this option is selected you can configure your application's Invocation Type, Invoke URL, and Trusted Origins.

Hosted Web, select this to default all bound credentials and authentications to our Hosted Web Authenticator. This is a constrained version of the Embedded Authenticator Config with the following values:

  • Invocation Type: automatic
  • Invoke URL: https://auth-<REGION>.beyondidentity.com/authenticator/
  • Trusted Origins: [https://auth-<REGION>.beyondidentity.com/authenticator/]

Embedded SDK​

If you selected the Embedded SDK Configuration Type, you will need to configure a few more items:

  1. Set an Invocation Type to specify how an authentication URL is delivered to your application.
Which Invocation Type should I use?

Automatic does a lot of the heavy lifting for you. If you initiate an OAuth2.0 request and specify the "Invoke URL" correctly, we'll get the Beyond Identity authentication URL to where it needs to be, whether this is inside of a native app or a web application.

Manual gives you a lot more control, but you'll have to do a little extra work to wire this flow up. The possibilities include:

  • Completley silent OAuth 2.0 authentication using Passkeys. No redirects needed in a web app and no web view needed in a native application.
  • The flexibility to write your own intelligent routing layer using the Beyond Identity authentication URL. You may want to authenticate against passkeys in your browser on desktop, but use passkeys on your native app on mobile.
  1. Set an Invoke URL that "points" to where your application is. In the case of a native application (iOS, Android, Flutter, React Native), this is either an App Scheme or an Universal URL / App Link. In the case of a web application, this is just a URL to your web application or a specific page of your web application.
caution

While app schemes are generally easier to set up, Universal URLs and App Links are recommended as they provide protection against App Scheme hijacking.

  1. Set Trusted Origins with your website's URL to add it to a whitelist. By default, cross origin requests are blocked by our server.

Create Application by API​

An application can also be created from the Beyond Identity API. Before making any API calls you'll want to generate an API access token. Check out API Tokens for help creating an access token.

Create a Resource Server​

Before creating an application by API, you may want to create a resource server. A resource server is a namespace for application scopes. Application scopes is a set of all scopes supported by the application. When an application is created without a resource server, this application may provide authentication (identity) but not authorization (access). If your application doesn't provide multiple levels of access -- like admin access vs user access, then there might not be a need for a resource server.

If you are creating another application to mint tokens, you will want to set the resource server to the "Beyond Identity Management API" resource server.

If you create a resource server, make note of the response id, as you'll need the resource server ID when creating an application.

/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)\"]}}"

Create an Authenticator Config​

Before creating an application by API, you'll need to create an Authenticator Config by setting the application's Configuration Type, Invocation Type, Invoke URL and Trusted Origins. See configuring the Authenticator Config from the admin console for help setting the appropriate options.

Make note of the response id, as you'll need the Authenticator Config ID when creating an application.

/authenticator-configs
1
2
3
4
5
curl "https://api-$(REGION).beyondidentity.com/v1/tenants/$(TENANT_ID)/realms/$(REALM_ID)/authenticator-configs" \
-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)\"}}}"

Create an Application​

Once you have created an Authenticator Config and a Resouce Server, you can create an application.

While the Resouce Server ID is optional, make sure to have the Authenticator Config ID for the applications with grant_type set to authorization_code. If you only wish to create an application with the client credentials OAuth flow, then the Authenticator Config ID is not required either. This is how the Beyond Identity Management API appliction is configured in your Beyond Identity Admin realm, however for most applications you will want to use the authorization code flow. The below example makes this assumption.

Set the application's Display Name, Client Type, Token Configuration, and redirect URI in the below request.

There are two options available for confidentiality:

  • If you choose confidential, set the token_endpoint_auth_method to either client_secret_post or client_secret_basic.
  • If you choose public, then set the token_endpoint_auth_method value to none.

If the application references a resource server, the allowed_scopes must be a subset of the resource server's available scopes. If the application does not reference a resource server, then this application can only be used for authentication and thereby scopes must necessarily be empty.

See configuring External Protocol from the admin console for help setting appropriate options.

/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\"}}}"