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:
- Open the master environment
- Select the Users tab
- Click Create User
- 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.
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 environment 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 Control API configuration in a tenants master environment with a scope that grants access to tenant data.
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 Control API URL contains the tenant name and environment name on winch you want to operate .../[tenant_name]/[environment_name]/...
.
To call the 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 read a OpenID Connect application registration on FoxIDs.com 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.
API access rights
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 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 forfoxids_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:
|
|
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. | |
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.
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.