An App Space is a representation on the server of a challenge ecosystem. The components are an app that runs on user devices, as well as Request Origins that initiate challenges. To create or edit an App Space or its IDP, the Company Admin role is required.

Overview

The overview provides a quick glance at the App Space configuration.

App Space Name

The name of the App Space in the system. This name is simply for ease of identification.

GUID

The unique identifier for this App Space.

IDP Type

The type of IDP that is configured to be the system of record for the App Space's users.

IDP Name

The name of the IDP in the system. This name is simply for ease of identification.

Request Origins

Provides a quick glance at active Request Origins and provides a link to manage them.

Current Active Request Origins

Displays the number of active Request Origins on this App Space. A Request Origin is considered active if it has active credentials. For more information, see Request Origins.

Active Users

Provides a quick glance at active App Users and provides a link to manage them. To manage App Users, the App Space Admin or User Support roles are required.

Total Current Active Users

The number of users that have interacted with challenge requests within a recent time frame. Note: a user can still be managed here even if they are considered inactive.

Administrators

Here you can manage the list of App Space admins and User Support admins related to this App Space. You can add, edit, and remove administrators from here.

Identity Provider Types

There are two mechanisms by which apps can be bound to App Spaces: Simple and Identity Provider Driven.

❗️

Server Restart

Editing an IDP after it has been created will require a server restart for the changes to take effect.

Simple

With Simple binding, a Request Origin initiates the binding process with the Bind Account API call. Using this mechanism, users can be directly managed in Active Users section. Using this method, Privakey CX is the authoritative system.

Identity Provider Driven

Using this method, the IDP is the authoritative system. When using the IDP driven mechanism, the user will initiate the bind process from their device. They will be redirected to the Identity Provider based on how it is configured in the Admin Portal. Once they complete authentication, the Auth Service will store the user's access tokens and refresh tokens, to use on their behalf.

If an access token fails during use, the Auth Service will use the refresh token to request a new set. If the refresh token fails, the Auth Service considers the user's token set as invalid on the Identity Provider's authority. The user will then, by default, be automatically prevented from responding to challenges. If the user's status is restored in the Identity Provider, they will be required to re-register to obtain a new set of tokens.

The exact behavior that occurs when an access token is considered invalid can be configured in the options.

App Protocol

In order for a seamless redirect from the Identity Provider back to the App to occur, an App Protocol will need to be supplied. This is the protocol that the app will register so Privakey CX can redirect to the app after completing the OpenID Connect authentication. E.g. myapp://

Token Fail Behavior

A Token Fail Behavior can be set to determine what Privakey CX should do if it is unable to validate or refresh an access token.

• Suspend User - The Privakey CX user account is suspended and may be recovered. This is the default setting.
• Revoke User - The Privakey CX user account is revoked and may not be recovered. In this case a new account would be created if the user's account with the Identity Provider becomes active.
• Do Nothing - The status of the Privakey CX user account will not change. They can continue to act on challenge requests.

OpenID Connect

When using OpenID Connect binding, the Privakey CX server will use an OpenID Connect Identity Provider for authentication, and store access tokens in its database. Note: for security reasons, the access token will be obtained using Authorization Code Flow.

OpenID Connect requires some additional configuration items:

1. IDP Server Name - A descriptive name for the OpenID Connect Server
2. OIDC Discovery URL - The discovery endpoint for the OpenID Connect Server. This functionality is required.
3. Client Id - The client id from the OpenID Connect Server
4. Secret - The client secret from the OpenID Connect Server
5. App Protocol - The App's protocol.
6. Token Fail Behavior - The behavior of the Auth Service when an access token is invalid.

On the OpenID Connect Server, the configuration must be updated to include a callback url to the Privakey CX Server. This callback url will be formatted as follows:

https://<privakey CX host name>/api/idp/oidc/verify

OAuth2

When using OAuth2 binding, the Privakey CX server will use an OAuth2 Identity Provider for authentication, and store access tokens in its database. Note: for security reasons, the access token will be obtained using Authorization Code Grant.

OAuth2 requires some additional configuration items:

1. IDP Server Name - A descriptive name for the OpenID Connect Server
2. Client Id - The client id from the OAuth2 Server
3. Secret - The client secret from the OAuth2 Server
4. App Protocol - The App's protocol.
5. Token Fail Behavior - The behavior of the Auth Service when an access token is invalid.
6. Access Token URL - The endpoint to exchange an authorization code for an access token and refresh token.
7. Authorization URL - The endpoint to request an authorization code from.
8. User Profile URL - The endpoint that can be used to obtain the user's data from the OAuth2 service.
9. Verify Token URL - The endpoint that can be used to verify an access token. If not set, the Auth Service will fall back to the User Profile URL, and attempt to use the access token to pull user information to verify the token.
10. Scopes - A space separated list of scopes to be claimed with the access token.
11. End User ID Name - The name of the field which denotes the user's identifier (eg. "user_id"). This is used to find and set the user's Account ID.

OAuth2 Example: Login With Amazon

Privakey CX can use any OAuth2 provider, so long as the appropriate values are provided. For example, to use Login With Amazon as an OAuth2 provider, the following values would be used:

1. Access Token URL: https://api.amazon.com/auth/o2/token
2. Authorization URL: https://www.amazon.com/ap/oa
3. User Profile URL: https://api.amazon.com/user/profile
4. Verify Token URL: https://api.amazon.com/auth/o2/tokeninfo
5. Scopes: profile profile:user_id
6. End User ID Name: user_id