diff --git a/docs/_sidebar.md b/docs/_sidebar.md index a24712241..18fb1e704 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -19,6 +19,7 @@ - [Email provider](email.md) - [Supported standards](standard-support.md) - [FoxIDs inside](foxids-inside.md) + - [Control Client & API](control#.md) - [Plans](plan.md) - [Development](development.md) - [Samples](samples.md) diff --git a/docs/control.md b/docs/control.md index a2f97f2bf..6d28772d3 100644 --- a/docs/control.md +++ b/docs/control.md @@ -60,13 +60,14 @@ The track properties can be configured by clicking the top right setting icon. ![Configure track settings](images/configure-track-setting.png) ## FoxIDs Control API -FoxIDs Control API is a REST API. The API expose a Swagger (OpenApi) interface document. +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 access tenant data in a particular tenant. Normally only tenant data is accessed. +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 client can be an OAuth 2.0 client. Where the client is granted the administrator role `foxids:tenant.admin` acting as the client itself using client credentials grant. - Her is how the [sample seed tool](samples.md#configure-the-sample-seed-tool) client is granted access. - - Or a OpenID Connect client with an authenticated master track user. Where the user is granted the administrator role `foxids:tenant.admin`. + - 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](samples.md#configure-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. @@ -76,5 +77,323 @@ FoxIDs Control API is called with an access token as described in the [OAuth 2.0 The Swagger (OpenApi) interface document is exposed on `.../api/swagger/v1/swagger.json`. -You can also find the FoxIDs.com Swagger (OpenApi) [interface document](https://control.foxids.com/api/swagger/v1/swagger.json) online. - +> FoxIDs.com Swagger (OpenApi) [https://control.foxids.com/api/swagger/v1/swagger.json](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:
+ |
+ |
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 | +
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 | +