FoxIDs Control

FoxIDs is configured with FoxIDs Control which consists of FoxIDs Control Client and FoxIDs Control API. FoxIDs Control Client and API is secured by FoxIDs and FoxIDs Control Client relay on FoxIDs Control API.

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

FoxIDs Control Client

FoxIDs Control Client is a Blazor WebAssembly (WASM) app.

Open your FoxIDs Control Client on FoxIDs.com.

Tenant and master track

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

Otherwise if FoxIDs is deployed in your one Azure tenant 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.

Configure tenants

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

Normally you should not change the master track configuration or add new up-parties or down-parties, but it is possible. You can e.g., by adding an up-party gain single sign-on (SSO) to the master track.

Create administrator user(s)

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

Create a user:

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

Configure administrator user

Tracks

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

Create one or more tracks, do not place configuration in the master track.

Configure tracks

Each track contains a user repository and a default created login up-party.

You can add OpenID Connect, OAuth 2.0 and SAML 2.0 down-parties and up-parties in the Parties tab.

Configure down-parties and down-parties

A track 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.

Configure certificates

The track 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.

Configure track settings

FoxIDs Control API

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

FoxIDs Control API require that the client calling the API is granted the foxids:master scope to access master tenant data or the foxids:tenant scope to access tenant data in a particular tenant. Normally only tenant data is accessed.

  • The API can be accessed with a OAuth 2.0 client. Where the client is granted the administrator role foxids:tenant.admin acting as the client itself using client credentials grant.
    It is probably helpful to take a look at how the sample seed tool client is granted access.
  • Or the API can be accessed with a OpenID Connect client with an authenticated master track user. Where the user is granted the administrator role foxids:tenant.admin.
    As an advanced option the mater user can also be granted access via a trust.

This shows the FoxIDs Control API configuration in a tenants master track with a scope that grants access to tenant data.

Configure foxids_control_api

FoxIDs Control API is called with an access token as described in the OAuth 2.0 Bearer Token (RFC 6750) standard.

The Swagger (OpenApi) interface document is exposed on .../api/swagger/v1/swagger.json.

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

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

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

API access rights

Access to FoxIDs 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 track and the configured set of scopes grant access the tenants data in the Control API.

A scopes access is limited by adding more elements separated with semicolon and dot. The dot notation limits or grant a 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 role 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.

Tenant access rights

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

The :track[xxxx] specifies a tenant e.g., the dev tenant is :track[dev].

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 tracks in a tenant, not including the master track.
    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 track in a tenant.
    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 tracks in a tenant, not including the master track. Not applicable in the master tenant.
    foxids:tenant:track:usage read
    Usage logs in a specific track in a tenant. Not applicable in the master tenant.
    foxids:tenant:track[xxxx]:usage read
    All logs in all tracks in a tenant, not including the master track.
    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 tracks in a tenant, not including the master track.
    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 track 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 down-parties and up-parties in all tracks in a tenant, not including the master track.
    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 down-parties and up-parties in a specific track 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.

    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

    If the scope you need is not defined on the Control API foxids_control_api you can add the scope. The same goes for roles which has to be defined on the user or the calling client.