FoxIDs Control

FoxIDs is configured through FoxIDs Control which consists of Control Client and Control API. Control Client and API is secured by FoxIDs and Control Client use Control API.

Control API contain all the configuration functionality. Therefore, it is possible to automate the configuration by integrating with Control API.

FoxIDs Control Client

Control Client is a Blazor WebAssembly (WASM) app.

Open your Control Client on FoxIDs.com.

Tenant and master environment

If you use FoxIDs.com. Your one tenant will be pre created on registration.

Otherwise if you deployed FoxIDs (self-Hosted) you get access to the master tenant. In this case you firstly need to create a tenant which will contain your entire security configuration. You probably only need one, but it is possible to configure an unlimited number of tenants.

A tenant contains a master environment, from where the entire tenant is configured. The master environment contains a user repository and on creation only one administrator user.

Normally you should not change the master environment configuration or add new authentication methods or application registrations, but it is possible. You can e.g., by adding an authentication method gain single sign-on (SSO) to the master environment.

Create administrator user(s)

It is possible to create more administrator users in the master environment. A user become an administrator by adding the administrator role foxids:tenant.admin like shown below.

Create a user:

1. Open the master environment
2. Select the Users tab
3. Click Create User
4. Add the user information and click Create.

Environments

Configure a number of environments, one for each of your environments e.g. dev, qa and prod.

Create one or more environments, do not place configuration in the master environment.

Each environment contains a user repository and a default created login authentication method.

You can add OpenID Connect, OAuth 2.0 and SAML 2.0 application registrations and authentication methods.

A environment contains a primary certificate and possible a secondary certificate in the Certificates tab. It is possible to swap between the primary and secondary certificate if both is configured, depending on the certificate container type.

The environment properties can be configured by clicking the top right setting icon.

• Sequence lifetime is the max lifetime of a user's login flow from start to end.
• FoxIDs protect against password guess. Configured in max failing logins, failing login count lifetime and observation period.
• Password requirements are configured regarding length, complexity and password risk.
• It is possible to host FoxIDs in an iframe from allowed domains.
• You can sent emails with you one SendGrid tenant by adding a custom email address and SendGrid key.

FoxIDs Control API

Control API is a REST API and has a Swagger (OpenApi) interface description.

If you host FoxIDs your self the Swagger (OpenApi) interface document is exposed in FoxIDs Control on .../api/swagger/v1/swagger.json.

FoxIDs Cloud Swagger (OpenApi) https://control.foxids.com/api/swagger/v1/swagger.json

The Control API URL contains the tenant name and environment name on winch you want to operate .../[tenant_name]/[environment_name]/.... To call your API you replace the [tenant_name] element with your tenant name and the [environment_name] element with the environment name of the environment you want to call.

If you e.g. want to read a OpenID Connect application registration on FoxIDs Cloud with the name some_oidc_app you do a HTTP GET call to https://control.foxids.com/api/[tenant_name]/[environment_name]/!oidcdownparty?name=some_oidc_app - replaced with your tenant and environment names.

You can either call the Control API as a system/demon with a OAuth 2.0 client or in the context of a user via a OpenID Connect client.

In the following we will create a OAuth 2.0 client and grant the client admin access rights by scopes and roles.

Create a OAuth 2.0 client in the FoxIDs Control Client:

1. Select the master environment (in the header)
2. Select the Applications tab
3. Click New Application
4. Click Backend Application
   1. Add a Name e.g., My API Client
   2. Click Register
   3. Remember the Client ID and Client secret.
   4. Click Close
5. Click on your client registration in the list to open it
6. In the Resource and scopes section - This will granted the client access to your tenant
   1. Click Add Resource and scope and add the resource foxids_control_api
   2. Then click Add Scope and add the scope foxids:tenant
7. Select Show advanced
8. In the Issue claims section - This will granted the client the tenant administrator role
   1. Click Add Claim and add the claim role
   2. Then click Add Value and add the claim value foxids:tenant.admin
9. Click Update

Then do a OAuth 2.0 Client Credentials Grant call to obtain an access token for the Control API.

Replace the [tenant_name], [environment_name], [client_id] and [client_secret]. And change the domain if you are using a custom domain or you are self-hosting.

HTTP request sample that performs OAuth 2.0 Client Credentials Grant and uses the application registration's token endpoint.

POST https://foxids.com/[tenant_name]/[environment_name]/[client_id](*)/oauth/token HTTP/1.1
Host: foxids.com
Content-Type: application/x-www-form-urlencoded

client_id=[client_id]
&client_secret=[client_secret]
&grant_type=client_credentials
&scope=foxids_control_api%3Afoxids%3Atenant

Token JSON response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

{
    "access_token":"eyJhGfjlc...nNjH3iIWvMdCM",
    "token_type":"Bearer",
    "expires_in":3600
}

The access_token is for the Control API.

C# code sample that performs OAuth 2.0 Client Credentials Grant and uses the application registration's OpenID Discovery endpoint.

// NuGet package: ITfoxtec.Identity
using ITfoxtec.Identity.Helpers

var oidcDiscoveryUrl = "https://foxids.com/[tenant_name]/[environment_name]/[client_id](*)/.well-known/openid-configuration";
// Inject IHttpClientFactory httpClientFactory
var oidcDiscovery = new OidcDiscoveryHandler(httpClientFactory, oidcDiscoveryUrl);

// Inject IHttpClientFactory httpClientFactory
var tokenHelper = new TokenHelper(httpClientFactory, oidcDiscovery);

var clientId = "[client_id]";
var clientSecret = "[client_secret]";
var scope = "foxids_control_api:foxids:tenant";
(var accessToken, var expiresIn) = await tokenHelper.GetAccessTokenWithClientCredentialGrantAsync(clientId, clientSecret, scope);

Then call the Control API with the access token as a Authorization Bearer header. Defined in the OAuth 2.0 Bearer Token (RFC 6750) standard.

C# code sample shows how to add the access token to the HttpClient.

// NuGet package: ITfoxtec.Identity
using ITfoxtec.Identity

// Inject IHttpClientFactory httpClientFactory
var httpClient = httpClientFactory.CreateClient();
// Add the access token
httpClient.SetAuthorizationHeaderBearer(accessToken);

// Call Control API using the httpClient
// E.g. read a OpenID Connect application registration
using var response = await client.GetAsync("https://control.foxids.com/api/[tenant_name]/[environment_name]/!oidcdownparty?name=some_oidc_app");

API access rights

This shows the Control API configuration in a tenants master environment with the default set of scopes that grants access to tenants data.

More scopes can be added to extend the Control API access rights in the different environments. To achieve least privileges access rights for each environment.

Access to Control API is limited by scopes and roles. There are two sets of scopes based on foxids:master which grant access to the master tenant data and foxids:tenant which grant access to tenant data.
The Control API resource foxids_control_api is defined in each tenant's master environment and the configured set of scopes grant access the tenants data through the Control API.

A scopes access is limited by adding more elements separated with semicolon and dot. The dot notation limits to a specific sub role, the notation is both used in scopes and roles. To be granted access the caller is required to possess one or more matching scope(s) and role(s).

Each access right is both defined as a scope and a role. This makes it possible to limit or grant access on both client and user level. The access rights are a hierarchy and the client and user do not need to be granted matching scopes and roles.

The administrator role foxids:tenant.admin grants access to all data in a tenant and the master tenant data, it is the same as having the roles foxids:tenant and foxids:master.

A client request a scope by requesting a scope on a resource, separating the resource and scope with a semicolon. E.g., to request the foxids:tenant:track:party.create scope the client request for foxids_control_api:foxids:tenant:track:party.create.

If a request is denied due to insufficient access rights, a trace item is logged with the possible authorising scopes and roles along with the users actual scopes and roles.

Tenant access rights

The tenant access rights is at the same time both scopes and roles.

If the scope you need is not defined on the Control API foxids_control_api you can add the scope.

The :track[xxxx] specifies an environment by the technical name. e.g., a Test environment with the technical name hsgm7je5 is :track[hsgm7je5] and a Production environment with the technical name - is :track[-].

Scope / role	Access
Access to everything in the tenant, not master tenant data.
foxids:tenant	read, create, update, delete
foxids:tenant.read	read
foxids:tenant.create	create
foxids:tenant.update	update
foxids:tenant.delete	delete
Access to basic tenant elements: My profile used in the Control Client. Call the ReadCertificate API to get a JWT with certificate information from a X509 Certificate.
foxids:tenant:basic	read, create, update, delete
foxids:tenant:basic.read	read
foxids:tenant:basic.create	create
foxids:tenant:basic.update	update
foxids:tenant:basic.delete	delete
Access to everything in all environments in a tenant, not including the master environment.
foxids:tenant:track	read, create, update, delete
foxids:tenant:track.read	read
foxids:tenant:track.create	create
foxids:tenant:track.update	update
foxids:tenant:track.delete	delete
Access to everything in a specific environment in a tenant. `xxxx` is the environments technical name.
foxids:tenant:track[xxxx]	read, create, update, delete
foxids:tenant:track[xxxx].read	read
foxids:tenant:track[xxxx].create	create
foxids:tenant:track[xxxx].update	update
foxids:tenant:track[xxxx].delete	delete
All usage logs in all environments in a tenant, not including the master environment. Not applicable in the master tenant.
foxids:tenant:track:usage	read
Usage logs in a specific environment in a tenant. Not applicable in the master tenant.
foxids:tenant:track[xxxx]:usage	read
All logs in all environments in a tenant, not including the master environment.
foxids:tenant:track:log	read, create, update, delete
foxids:tenant:track:log.read	read
foxids:tenant:track:log.create	create
foxids:tenant:track:log.update	update
foxids:tenant:track:log.delete	delete
Logs in a specific tenant.
foxids:tenant:track[xxxx]:log	read, create, update, delete
foxids:tenant:track[xxxx]:log.read	read
foxids:tenant:track[xxxx]:log.create	create
foxids:tenant:track[xxxx]:log.update	update
foxids:tenant:track[xxxx]:log.delete	delete
All users in all environments in a tenant, not including the master environment.
foxids:tenant:track:user	read, create, update, delete
foxids:tenant:track:user.read	read
foxids:tenant:track:user.create	create
foxids:tenant:track:user.update	update
foxids:tenant:track:user.delete	delete
All users in a specific environment in a tenant.
foxids:tenant:track[xxxx]:user	read, create, update, delete
foxids:tenant:track[xxxx]:user.read	read
foxids:tenant:track[xxxx]:user.create	create
foxids:tenant:track[xxxx]:user.update	update
foxids:tenant:track[xxxx]:user.delete	delete
All application registrations and authentication methods in all environments in a tenant, not including the master environment.
foxids:tenant:track:party	read, create, update, delete
foxids:tenant:track:party.read	read
foxids:tenant:track:party.create	create
foxids:tenant:track:party.update	update
foxids:tenant:track:party.delete	delete
All application registrations and authentication methods in a specific environment in a tenant.
foxids:tenant:track[xxxx]:party	read, create, update, delete
foxids:tenant:track[xxxx]:party.read	read
foxids:tenant:track[xxxx]:party.create	create
foxids:tenant:track[xxxx]:party.update	update
foxids:tenant:track[xxxx]:party.delete	delete

Master tenant access rights

The master tenant access rights is at the same time both scopes and roles.

Scope / role	Access
Access to the master tenant data Can list, create and delete tenants but not look into other tenants.
foxids:master	read, create, update, delete
foxids:master.read	read
foxids:master.create	create
foxids:master.update	update
foxids:master.delete	delete
Usage log in the master tenant.
foxids:master:usage	read