Skip to content

Commit

Permalink
Merge pull request #727 from ITfoxtec/pre-master
Browse files Browse the repository at this point in the history 
Pre master
  • Loading branch information
@Revsgaard
Revsgaard authored Feb 12, 2024
2 parents 34649da + 36f5246 commit d42b9bb
Show file tree
Hide file tree
Showing 150 changed files with 2,347 additions and 596 deletions.
1 change: 1 addition & 0 deletions docs/_sidebar.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
333 changes: 326 additions & 7 deletions docs/control.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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]`.

<table>
<tr>
<th>Scope / role</th>
<th>Access</th>
</tr>
<tr>
<td colspan=2><i>Access to everything in the tenant, not master tenant data.</i></td>
</tr>
<tr>
<td><code>foxids:tenant</code></td>
<td>read, create, update, delete</td>
</tr>
<tr>
<td><code>foxids:tenant.read</code></td>
<td>read</td>
</tr>
<tr>
<td><code>foxids:tenant.create</code></td>
<td>create</td>
</tr>
<tr>
<td><code>foxids:tenant.update</code></td>
<td>update</td>
</tr>
<tr>
<td><code>foxids:tenant.delete</code></td>
<td>delete</td>
</tr>
<tr>
<td colspan=2><i>Access to basic tenant elements:
<lu>
<li>My profile used in the Control Client.</li>
<li>Call the ReadCertificate API to get a JWT with certificate information from a X509 Certificate.</li>
</lu>
</i></td>
</tr>
<tr>
<td><code>foxids:tenant:basic</code></td>
<td>read, create, update, delete</td>
</tr>
<tr>
<td><code>foxids:tenant:basic.read</code></td>
<td>read</td>
</tr>
<tr>
<td><code>foxids:tenant:basic.create</code></td>
<td>create</td>
</tr>
<tr>
<td><code>foxids:tenant:basic.update</code></td>
<td>update</td>
</tr>
<tr>
<td><code>foxids:tenant:basic.delete</code></td>
<td>delete</td>
</tr>
<tr>
<td colspan=2><i>Access to everything in all tracks in a tenant, not including the master track.</i></td>
</tr>
<tr>
<td><code>foxids:tenant:track</code></td>
<td>read, create, update, delete</td>
</tr>
<tr>
<td><code>foxids:tenant:track.read</code></td>
<td>read</td>
</tr>
<tr>
<td><code>foxids:tenant:track.create</code></td>
<td>create</td>
</tr>
<tr>
<td><code>foxids:tenant:track.update</code></td>
<td>update</td>
</tr>
<tr>
<td><code>foxids:tenant:track.delete</code></td>
<td>delete</td>
</tr>
<tr>
<td colspan=2><i>Access to everything in a specific track in a tenant.</i></td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]</code></td>
<td>read, create, update, delete</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx].read</code></td>
<td>read</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx].create</code></td>
<td>create</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx].update</code></td>
<td>update</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx].delete</code></td>
<td>delete</td>
</tr>
<tr>
<td colspan=2><i>All usage logs in all tracks in a tenant, not including the master track. Not applicable in the master tenant.</i></td>
</tr>
<tr>
<td><code>foxids:tenant:track:usage</code></td>
<td>read</td>
</tr>
<tr>
<td colspan=2><i>Usage logs in a specific track in a tenant. Not applicable in the master tenant.</i></td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:usage</code></td>
<td>read</td>
</tr>
<tr>
<td colspan=2><i>All logs in all tracks in a tenant, not including the master track. </i></td>
</tr>
<tr>
<td><code>foxids:tenant:track:log</code></td>
<td>read, create, update, delete</td>
</tr>
<tr>
<td><code>foxids:tenant:track:log.read</code></td>
<td>read</td>
</tr>
<tr>
<td><code>foxids:tenant:track:log.create</code></td>
<td>create</td>
</tr>
<tr>
<td><code>foxids:tenant:track:log.update</code></td>
<td>update</td>
</tr>
<tr>
<td><code>foxids:tenant:track:log.delete</code></td>
<td>delete</td>
</tr>
<tr>
<td colspan=2><i>Logs in a specific tenant.</i></td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:log</code></td>
<td>read, create, update, delete</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:log.read</code></td>
<td>read</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:log.create</code></td>
<td>create</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:log.update</code></td>
<td>update</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:log.delete</code></td>
<td>delete</td>
</tr>
<tr>
<td colspan=2><i>All users in all tracks in a tenant, not including the master track.</i></td>
</tr>
<tr>
<td><code>foxids:tenant:track:user</code></td>
<td>read, create, update, delete</td>
</tr>
<tr>
<td><code>foxids:tenant:track:user.read</code></td>
<td>read</td>
</tr>
<tr>
<td><code>foxids:tenant:track:user.create</code></td>
<td>create</td>
</tr>
<tr>
<td><code>foxids:tenant:track:user.update</code></td>
<td>update</td>
</tr>
<tr>
<td><code>foxids:tenant:track:user.delete</code></td>
<td>delete</td>
</tr>
<tr>
<td colspan=2><i>All users in a specific track in a tenant. </i></td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:user</code></td>
<td>read, create, update, delete</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:user.read</code></td>
<td>read</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:user.create</code></td>
<td>create</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:user.update</code></td>
<td>update</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:user.delete</code></td>
<td>delete</td>
</tr>
<tr>
<td colspan=2><i>All down-parties and up-parties in all tracks in a tenant, not including the master track.</i></td>
</tr>
<tr>
<td><code>foxids:tenant:track:party</code></td>
<td>read, create, update, delete</td>
</tr>
<tr>
<td><code>foxids:tenant:track:party.read</code></td>
<td>read</td>
</tr>
<tr>
<td><code>foxids:tenant:track:party.create</code></td>
<td>create</td>
</tr>
<tr>
<td><code>foxids:tenant:track:party.update</code></td>
<td>update</td>
</tr>
<tr>
<td><code>foxids:tenant:track:party.delete</code></td>
<td>delete</td>
</tr>
<tr>
<td colspan=2><i>All down-parties and up-parties in a specific track in a tenant.</i></td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:party</code></td>
<td>read, create, update, delete</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:party.read</code></td>
<td>read</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:party.create</code></td>
<td>create</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:party.update</code></td>
<td>update</td>
</tr>
<tr>
<td><code>foxids:tenant:track[xxxx]:party.delete</code></td>
<td>delete</td>
</tr>
</table>

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

<table>
<tr>
<td colspan=2><i>Access to the master tenant data<br />
Can list, create and delete tenants but not look into other tenants.
</i></td>
</tr>
<tr>
<td><code>foxids:master</code></td>
<td>read, create, update, delete</td>
</tr>
<tr>
<td><code>foxids:master.read</code></td>
<td>read</td>
</tr>
<tr>
<td><code>foxids:master.create</code></td>
<td>create</td>
</tr>
<tr>
<td><code>foxids:master.update</code></td>
<td>update</td>
</tr>
<tr>
<td><code>foxids:master.delete</code></td>
<td>delete</td>
</tr>
<tr>
<td colspan=2><i>Usage log in the master tenant.</i></td>
</tr>
<tr>
<td><code>foxids:master:usage</code></td>
<td>read</td>
</tr>
</table>

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.
12 changes: 8 additions & 4 deletions docs/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,18 @@
##### Only the `sub`, `sid`, `acr` and `amr` claims are pass through. I get more claims from the up-party by using log claims trace. What am I doing wrong?
By default an up-party should pass through all claims to the down-party if Forward Claims has a `*`.
![Up-party default pass through all claims to the down-party](images/faq-pass-through-all-claims-up-party.png)
You can also make the down-party (OpenID Connect client) add all claims in the access token issued to the application (not default).
You can also make the down-party (in this case a OpenID Connect client) add all claims to the access token issued to the application (not default).
Navigating to the down-party then click Show advanced settings and add a `*` in the Issue claims field. Optionally also include all claims in the issued ID token.
![Make the down-party issue all claims](images/faq-pass-through-all-claims-down-party.png)

##### Is it possible to avoid the "Pick an account" dialog?
Yes FoxIDs support to forward the login hint from an up-party to an external IdP or another FoxIDs down-party. In OpenID Connect the login hint is forwarded in the `login_hint` parameter.
In SAML 2.0 the login hint is forwarded as a `NameID` with the Email Format `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` in the `Subject` element.

##### Way am I unable to login for a moment when I change the certificate container types to 'Key Vault renewed self-signed certificates'?
The first certificate have to be generated by Key Vault before the track can perform logins again. Thereafter the certificate is renewed without seamlessly.
The first certificate have to be generated by Key Vault before the track can perform logins again. Thereafter the certificate is renewed seamlessly.

##### I am unable to logout of a client using OIDC if I login and theafter changed the certificate container type.
The problem occurs if the OIDC logout require an ID Token before accepting logout. In this case the ID Token is invalid because the container type and there by the signing certificate have changed.
The problem will occur in the FoxIDs Controle Client. You need to close the browser and start over.
The problem occurs if the OIDC logout require an ID Token before accepting logout. In this case the ID Token is invalid because the container type and there by the signing certificate have changed.
Solution: You need to close the browser and start over.

2 changes: 1 addition & 1 deletion docs/gs-context-handler.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Test Context Handler with the <a href="https://aspnetcoreoidcallupsample.itfoxte
The OpenID Connect test app call FoxIDs and FoxIDs call Context Handler to let the user authenticate.

## Context Handler details
FoxIDs support Context Handler including OIOSAML3, login, single logout, logging, issuer naming, OCES3 certificates and NSIS.
FoxIDs support Context Handler including OIOSAML3, login, single logout, logging, issuer naming, OCES3 (RSASSA-PSS) certificates and NSIS.

> Transform the [DK privilege XML claim](claim-transform-dk-privilege.md) to a JSON claim.
Expand Down
2 changes: 1 addition & 1 deletion docs/gs-nemlogin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Test NemLog-in with the <a href="https://aspnetcoreoidcallupsample.itfoxtec.com/
The OpenID Connect test app call FoxIDs and FoxIDs call NemLog-in to let the user authenticate with MitID.

## NemLog-in details
FoxIDs support NemLog-in including OIOSAML3, login, single logout, logging, issuer naming, OCES3 certificates and NSIS.
FoxIDs support NemLog-in including OIOSAML3, login, single logout, logging, issuer naming, OCES3 (RSASSA-PSS) certificates and NSIS.

> Transform the [DK privilege XML claim](claim-transform-dk-privilege.md) to a JSON claim.
Expand Down
Loading

0 comments on commit d42b9bb

Please sign in to comment.